Pular para o conteúdo
PT
Obter chave API

YouTube Data / JavaScript

YouTube legendas: escolha uma língua e manuseie faixas perdidas.

Escolha o YouTube automático ou fornecido pelo upload por linguagem, preserve timestamps, e lide com faixas desaparecidas explicitamente com JavaScript.

FlashData · Publicado

Duas faixas de legenda com uma selecionada abaixo de uma moldura de vídeo.

Um vídeo pode ter legendas automáticas inglesas, uma faixa espanhola fornecida pelo upload, ambos, ou nenhum dos dois. Pedir uma linguagem não cria uma faixa que o vídeo não tenha. Este guia torna a escolha da legenda explícita e mostra como salvar a faixa selecionada sem substituir silenciosamente outra língua ou fonte da legenda.

Legendas automáticas e legendas fornecidas pelo uploader

FlashData expõe duas fontes convenientes: youtube_transcript padrão para legendas automáticas, enquanto youtube_captions O padrão é a legenda fornecida pelo uploader. Ambos apoiam um explícito params.auto Valor: true seleciona legendas automáticas e false seleciona legendas fornecidas pelo uploader. Ambos recuperam as legendas YouTube existentes e retornam segmentos com data de retorno.

Preparar params.language para a pista que você precisa, por exemplo en, es ou en-US. Um código regional e um código somente para linguagem não são promessas intercambiáveis. Se o idioma e a fonte de legenda não estiverem disponíveis, o pedido pode falhar ou não ter nenhum texto utilizável. O API não traduz automaticamente, gera discurso-texto, ou cai de volta entre as fontes da pista.

Escolha uma faixa antes de enviar o pedido

Use Node.js 22 ou mais tarde e um API chave Com créditos disponíveis. Defina um vídeo ID que você pode processar. Para o fluxo básico de exportação de texto, veja Obter YouTube legendas com JavaScript.

bash
export FLASHDATA_API_KEY='your-api-key'
export YOUTUBE_VIDEO_ID='your-video-id'
export CAPTION_LANGUAGE='en'
export CAPTION_AUTO='true'

Use CAPTION_AUTO=false para pedir uma faixa fornecida pelo uploader. O roteiro envia exatamente um pedido. Ele não tenta cada idioma ou emitir um segundo pedido pago automaticamente quando o primeiro falha.

Pegue a faixa escolhida e mantenha as datas

Guarde o seguinte código como caption-track.mjs. Ele valida a escolha de entrada, verifica erros de nível de ferramenta, bem como falhas HTTP, e preserva a língua e informação de origem relatada na resposta.

javascript
import { writeFile } from "node:fs/promises";

const key = process.env.FLASHDATA_API_KEY;
const videoId = process.env.YOUTUBE_VIDEO_ID;
const language = process.env.CAPTION_LANGUAGE ?? "en";
const autoSetting = process.env.CAPTION_AUTO ?? "true";
if (!key || !/^[A-Za-z0-9_-]{11}$/.test(videoId ?? "")) {
  throw new Error("Set FLASHDATA_API_KEY and an 11-character YOUTUBE_VIDEO_ID.");
}
if (!["true", "false"].includes(autoSetting)) {
  throw new Error("CAPTION_AUTO must be true or false.");
}
if (!/^[A-Za-z0-9-]{1,35}$/.test(language)) {
  throw new Error("Use a caption language code such as en or en-US.");
}
const auto = autoSetting === "true";
const source = auto ? "youtube_transcript" : "youtube_captions";
const response = await fetch("https://data.flashdata.dev/v1/queries/realtime", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-Key": key },
  body: JSON.stringify({ source, video_id: videoId, params: { language, auto } }),
  signal: AbortSignal.timeout(60000),
});
const payload = await response.json();
if (!response.ok || payload.error || payload.status !== "done") {
  console.error(JSON.stringify({ httpStatus: response.status,
    requestId: response.headers.get("x-request-id"),
    detail: payload.detail ?? payload.message ?? payload.error }, null, 2));
  throw new Error("Caption request failed. Inspect the error before trying another track.");
}
const track = payload.results?.[0];
if (!Array.isArray(track?.segments) || !track.segments.some(s => s.text?.trim())) {
  throw new Error("No usable caption segments were returned for this selection.");
}
const saved = {
  requested: { videoId, language, auto },
  returned: { videoId: track.videoId, languageCode: track.languageCode,
    isAutoGenerated: track.isAutoGenerated, segments: track.segments },
};
await writeFile("caption-track.json", JSON.stringify(saved, null, 2));
await writeFile("caption-track.txt", track.fullText || track.segments.map(s => s.text).join("\n"));
console.log(`Saved ${track.segments.length} segments from ${track.languageCode}`);
bash
node caption-track.mjs

O que fazer quando a pista solicitada está faltando?

  • Verifique o erro antes de mudar as configurações de legenda. Uma chave inválida, créditos insuficientes ou um intervalo não é evidência de que o vídeo não tem legendas.

  • Se você já buscar metadados de vídeo, inspecione hasTranscripts e.. transcriptLanguages como sinais úteis. Uma linguagem relatada não garante que faixas automáticas e fornecidas por carregadores existam nessa língua.

  • Se uma pista alternativa é aceitável para o seu caso de uso, escolha-a deliberadamente e faça um pedido separado. Grave o idioma solicitado e devolvido e isAutoGenerated Valorize com o texto.

  • Se seu fluxo de trabalho requer a faixa exata, marque o item indisponível e continue com outros vídeos. Repetidamente enviar o mesmo pedido não criará legendas perdidas.

Mantenha a linguagem e a origem da hora com seu texto

Segmentos contêm start, end e.. text; Os tempos são medidos em segundos. Mantenha o vídeo ID e linguagem ao dividir uma transcrição em pedaços de busca. Um link de vídeo cronometrado pode ajudar um leitor a verificar o contexto original. Evite tratar um segmento de legenda como uma nova transcrição que sua aplicação produziu.

Legendas automáticas podem conter erros de reconhecimento. Se você usar o texto para resumos ou citações, fornecer uma maneira de inspecionar o segmento original e vídeo. Disponibilidade e precisão são perguntas separadas: recuperar uma pista com sucesso não garante que sua redação esteja correta.

Compare o Transcrição API e.. Legendas API, ou explorar o YouTube APIs de dados.