Aller au contenu
FR
Obtenir une clé API

YouTube Data / JavaScript

Sous-titres YouTube : choisir la langue et gérer les pistes absentes

Choisissez la langue et le type de sous-titres YouTube, automatiques ou fournis par le créateur, conservez les horodatages et gérez les pistes absentes avec JavaScript.

FlashData · Publié

Deux pistes de sous-titres sous une vidéo, dont une sélectionnée

Une vidéo peut proposer des sous-titres automatiques en anglais, une piste en espagnol fournie par le créateur, les deux ou aucune. Demander une langue ne crée pas une piste absente de la vidéo. Ce guide montre comment choisir explicitement une piste et l’enregistrer sans la remplacer silencieusement par une autre langue ou un autre type de sous-titres.

Sous-titres automatiques ou fournis par le créateur

FlashData propose deux sources : youtube_transcript sélectionne les sous-titres automatiques par défaut, tandis que youtube_captions sélectionne ceux du créateur. Les deux sources permettent de définir explicitement params.auto : true sélectionne les sous-titres automatiques et false sélectionne ceux fournis par le créateur. Les deux sources récupèrent les sous-titres YouTube existants et renvoient des segments horodatés.

Définissez params.language sur la langue de la piste souhaitée, par exemple en, es ou en-US. Un code régional et un code de langue seul ne sont pas nécessairement interchangeables. Si la langue et le type de sous-titres demandés sont indisponibles, la requête peut échouer ou ne renvoyer aucun texte exploitable. L’API ne traduit pas automatiquement le texte, ne transcrit pas l’audio et ne bascule pas vers un autre type de piste.

Choisir une piste avant d’envoyer la requête

Utilisez Node.js 22 ou une version ultérieure et une clé API associée à un compte disposant de crédits. Choisissez l’ID d’une vidéo que vous êtes autorisé à traiter. Pour un simple export de texte, consultez Récupérer des sous-titres YouTube avec JavaScript.

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

Utilisez CAPTION_AUTO=false pour demander une piste fournie par le créateur. Le script envoie une seule requête. Il ne teste pas toutes les langues et n’envoie pas automatiquement une seconde requête payante si la première échoue.

Récupérer la piste choisie avec ses horodatages

Enregistrez le code suivant dans caption-track.mjs. Le script valide les paramètres, vérifie les erreurs d’outil et les erreurs HTTP, puis conserve la langue et la provenance indiquées dans la réponse.

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

Que faire si la piste demandée est absente ?

  • Vérifiez l’erreur avant de modifier les paramètres des sous-titres. Une clé invalide, un solde de crédits insuffisant ou un délai dépassé ne prouve pas que la vidéo n’a pas de sous-titres.

  • Si vous récupérez déjà les métadonnées de la vidéo, consultez hasTranscripts et transcriptLanguages pour orienter votre choix. La présence d’une langue n’implique pas que des pistes automatiques et des pistes du créateur existent toutes deux dans cette langue.

  • Si une autre piste convient à votre usage, choisissez-la explicitement et envoyez une requête distincte. Enregistrez la langue demandée, la langue renvoyée et la valeur de isAutoGenerated avec le texte.

  • Si votre workflow exige cette piste précise, marquez la vidéo comme indisponible et passez aux autres. Répéter la même requête ne créera pas les sous-titres manquants.

Conserver la langue et les horodatages avec le texte

Les segments contiennent start, end et text ; les temps sont exprimés en secondes. Conservez l’ID de la vidéo et la langue lorsque vous découpez la transcription pour la recherche. Un lien vidéo horodaté permet de vérifier le contexte d’origine. Ne présentez pas un segment de sous-titres comme une transcription créée par votre application.

Les sous-titres automatiques peuvent contenir des erreurs de reconnaissance. Pour des résumés ou des citations, permettez au lecteur de consulter le segment et la vidéo d’origine. La disponibilité d’une piste et l’exactitude de son texte sont deux choses distinctes.

Comparez les API Transcript et Captions, ou découvrez les API YouTube Data.