跳转到正文
中文
获取 API 密钥

YouTube 数据 / JavaScript

YouTube 字幕:选择语言并处理缺失轨道

按语言选择自动生成或上传者提供的 YouTube 字幕,保留时间戳,并使用 JavaScript 显式处理轨道缺失的情况。

FlashData · 发布于

视频画面下方有两个字幕轨道,其中一个已选中

一个视频可能有英文自动字幕、上传者提供的西班牙语字幕轨道、两者都有,或两者都没有。请求某种语言并不会创建视频原本没有的轨道。本指南明确指定字幕选项,并展示如何保存所选轨道,而不会悄悄替换成其他语言或字幕来源。

自动字幕和上传者提供的字幕

FlashData 提供两种便捷的数据源: youtube_transcript 默认使用自动字幕,而 youtube_captions 默认使用上传者提供的字幕。两者均支持显式指定 params.auto 值: true 选择自动字幕, false 选择上传者提供的字幕。两者均获取现有 YouTube 字幕,并返回带时间戳的分段。

设置 params.language 设为所需轨道,例如 en, es 或 en-US。地区代码与仅含语言的代码不能视为等效的保证。如果所请求的语言和字幕来源不可用,请求可能失败或没有可用文本。API 不会自动翻译、进行语音转文字,也不会在字幕轨道来源之间自动回退。

发送请求前选择一个轨道

使用 Node.js 22 或更高版本,以及一个 API 密钥 ,并确保有可用积分。设置一个你有权处理的视频 ID。基本文本导出流程请参阅 使用 JavaScript 获取 YouTube 字幕.

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

使用 CAPTION_AUTO=false ,以请求上传者提供的字幕轨道。脚本只发送一次请求,不会尝试所有语言,也不会在首次请求失败时自动发起第二次付费请求。

获取所选轨道并保留时间戳

将以下代码保存为 caption-track.mjs。它会验证输入选项,检查工具级错误和 HTTP 失败,并保留响应中报告的语言和来源信息。

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

请求的轨道不存在时如何处理

  • 更改字幕设置前先检查错误。密钥无效、积分不足或超时都不能证明视频没有字幕。

  • 如果你已经获取视频元数据,请检查 hasTranscripts 和 transcriptLanguages 作为有用的参考信息。返回某种语言并不保证该语言同时存在自动字幕轨道和上传者提供的字幕轨道。

  • 如果你的使用场景可以接受其他轨道,请明确选择该轨道并单独发起请求。记录请求和返回的语言以及 isAutoGenerated 值,与文本一同保留。

  • 如果工作流程必须使用指定轨道,请将该项标记为不可用,并继续处理其他视频。反复发送相同请求不会创建缺失的字幕。

随文本保留语言与时间戳的来源信息

片段包含 start, end 和 text;时间以秒为单位。将字幕文本拆分成用于搜索的分块时,请保留视频 ID 和语言。带时间戳的视频链接可以帮助读者核实原始上下文。不要将字幕分段视为你的应用新生成的语音转写。

自动字幕可能包含识别错误。如果将文本用于摘要或引用,请提供查看原始分段和视频的方式。可用性与准确性是两回事:成功获取轨道不保证其中的措辞正确。

比较 转录文本 API 和 Captions API,或探索 YouTube 数据 API.