Un video può avere didascalie automatiche in inglese, una traccia spagnola di uploader, sia, sia, sia. Chiedere una lingua non crea una traccia che il video non ha. Questa guida rende esplicita la scelta didascalia e mostra come salvare la traccia selezionata senza sostituire silenziosamente un'altra lingua o fonte didascalia.
Cappucci automatici e didascalie fornite dal caricatore
FlashData espone due fonti convenienti: youtube_transcript predefiniti per le didascalie automatiche, mentre youtube_captions predefinizioni per le didascalie fornite dal caricatore. Entrambi sostengono un esplicito params.auto valore: true seleziona le didascalie automatiche e false seleziona le didascalie fornite da uploader. Entrambi recuperano le didascalie YouTube esistenti e i segmenti timestamp di ritorno.
Set Set params.language per la pista di cui hai bisogno, ad esempio en, es o en-US. Un codice regionale e un codice di sola lingua non sono promesse intercambiabili. Se la lingua richiesta e la fonte di didascalia non sono disponibili, la richiesta può fallire o non avere testo utilizzabile. Lo API non traduce automaticamente, genera discorsi-testo, o rientra tra le fonti di traccia.
Scegli una traccia prima di inviare la richiesta
Utilizzare Node.js 22 o più tardi e un Chiave API con Crediti disponibili. Impostare un video ID è consentito elaborare. Per il flusso di lavoro di esportazione di testo di base, vedere Ottieni sottotitoli YouTube con JavaScript.
export FLASHDATA_API_KEY='your-api-key'
export YOUTUBE_VIDEO_ID='your-video-id'
export CAPTION_LANGUAGE='en'
export CAPTION_AUTO='true'
Uso CAPTION_AUTO=false per chiedere una traccia di uploader-provided. Lo script invia esattamente una richiesta. Non prova ogni lingua o emette una seconda richiesta a pagamento automaticamente quando il primo non riesce.
Prendi la traccia scelta e tieni i timestamp
Salvare il seguente codice come caption-track.mjs. Esso convalida la scelta di input, i controlli per gli errori di livello degli strumenti e i guasti HTTP, e conserva le informazioni di lingua e di origine riportate nella risposta.
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}`);
node caption-track.mjs
Cosa fare quando manca la traccia richiesta
Controllare l'errore prima di cambiare le impostazioni di didascalia. Una chiave non valida, crediti insufficienti o un timeout non è la prova che il video manca di didascalie.
Se si prescrivono i metadati video, ispezionare
hasTranscriptsetranscriptLanguagescome segnali utili. Una lingua riportata non garantisce che esistano sia tracce automatiche che provviste di uploader in quella lingua.Se una traccia alternativa è accettabile per il vostro caso di utilizzo, sceglierla deliberatamente e fare una richiesta separata. Registrare la lingua richiesta e restituita e
isAutoGeneratedvalore con il testo.Se il flusso di lavoro richiede la traccia esatta, contrassegnare l'elemento non disponibile e continuare con altri video. L'invio ripetuto della stessa richiesta non creerà le didascalie mancanti.
Mantenere la lingua e la prova di timestamp con il testo
Segmenti contengono start, end e text; i tempi sono misurati in secondi. Tenere il video ID e la lingua quando si divide una trascrizione in blocchi di ricerca. Un collegamento video timestamp può aiutare un lettore a verificare il contesto originale. Evitare di trattare un segmento di didascalia come una nuova trascrizione che la vostra applicazione ha prodotto.
Le capzioni automatiche possono contenere errori di riconoscimento. Se si utilizza il testo per sintesi o citazioni, fornire un modo per ispezionare il segmento originale e video. Disponibilità e precisione sono domande separate: recuperare con successo una traccia non garantisce che la sua formulazione è corretta.
Confrontare Trascrizione API e Didascalie API, o esplorare il API di dati YouTube.