Перейти к содержимому
RU
Ключ API

YouTube Data / 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, которое вы можете обработать. Для основного текста экспортный рабочий процесс, см. Получить субтитры YouTube с JavaScript.

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 и Производитель: API, или исследовать YouTube Data API.