Captions

Nota: il 13 marzo 2024, YouTube ha annunciato che il parametro sync verrà ritirato captions.insert e captions.update endpoint API. La sincronizzazione automatica dei sottotitoli è ancora disponibile in YouTube Creator Studio. Consulta le Cronologia delle revisioni delle API per ulteriori dettagli.

Una risorsa caption rappresenta una traccia di sottotitoli di YouTube. Una traccia di sottotitoli è associata a un solo video di YouTube.

Metodi

L'API supporta i seguenti metodi per le risorse captions:

list
Recupera un elenco di tracce di sottotitoli codificati associate a un video specifico. Tieni presente che la risposta dell'API non contiene i sottotitoli effettivi e che il metodo captions.download offre la possibilità di recuperare una traccia di sottotitoli. Prova subito.
inserisci
Carica una traccia sottotitoli codificati.
aggiorna
Aggiorna una traccia sottotitoli. Quando aggiorni una traccia di sottotitoli codificati, puoi modificare lo stato di bozza della traccia, caricare un nuovo file di sottotitoli codificati per la traccia o eseguire entrambe le operazioni.
elimina
Eliminare una traccia di sottotitoli specifica. Prova subito.
scaricare
Scarica una traccia di sottotitoli codificati. La traccia dei sottotitoli codificati viene restituita nel formato originale, a meno che la richiesta non specifichi un valore per il parametro tfmt e nella lingua originale, a meno che la richiesta non specifichi un valore per il parametro tlang.

Rappresentazione della risorsa

La seguente struttura JSON mostra il formato di una risorsa captions:

{
  "kind": "youtube#caption",
  "etag": etag,
  "id": string,
  "snippet": {
    "videoId": string,
    "lastUpdated": datetime,
    "trackKind": string,
    "language": string,
    "name": string,
    "audioTrackType": string,
    "isCC": boolean,
    "isLarge": boolean,
    "isEasyReader": boolean,
    "isDraft": boolean,
    "isAutoSynced": boolean,
    "status": string,
    "failureReason": string
  }
}

Proprietà

La tabella seguente definisce le proprietà visualizzate in questa risorsa:

Proprietà
kind string
Identifica il tipo di risorsa API. Il valore sarà youtube#caption.
etag etag
L'ETag di questa risorsa.
id string
L'ID utilizzato da YouTube per identificare in modo univoco la traccia dei sottotitoli codificati.
snippet object
L'oggetto snippet contiene i dettagli di base della didascalia.
snippet.videoId string
L'ID utilizzato da YouTube per identificare in modo univoco il video associato alla traccia di sottotitoli codificati.
snippet.lastUpdated datetime
La data e l'ora dell'ultimo aggiornamento della traccia dei sottotitoli codificati. Il valore è specificato nel formato ISO 8601.
snippet.trackKind string
Il tipo di traccia di sottotitoli codificati.

I valori validi per questa proprietà sono:
  • ASR: una traccia di sottotitoli codificati generata utilizzando il riconoscimento vocale automatico.
  • forced - Una traccia di sottotitoli codificati riprodotta quando non è selezionata nessun'altra traccia nel player. Ad esempio, un video che mostra alieni che parlano in una lingua aliena potrebbe avere una traccia di sottotitoli codificati forzata per mostrare solo i sottotitoli per la lingua aliena.
  • standard - Una traccia di sottotitoli standard. Questo è il valore predefinito.
snippet.language string
La lingua della traccia dei sottotitoli codificati. Il valore della proprietà è un tag di lingua BCP-47.
snippet.name string
Il nome della traccia di sottotitoli codificati. Il nome deve essere visibile all'utente come opzione durante la riproduzione. La lunghezza massima del nome supportata è 150 caratteri.
snippet.audioTrackType string
Il tipo di traccia audio associato alla traccia di sottotitoli codificati.

I valori validi per questa proprietà sono:
  • commentary: la traccia dei sottotitoli codificati corrisponde a una traccia audio alternativa che include i commenti, ad esempio i commenti della guida.
  • descriptive - La traccia dei sottotitoli corrisponde a una traccia audio alternativa che include un audio descrittivo aggiuntivo.
  • primary: la traccia dei sottotitoli codificati corrisponde alla traccia audio principale del video, ovvero quella normalmente associata al video.
  • unknown - Questo è il valore predefinito.
snippet.isCC boolean
Indica se la traccia contiene sottotitoli per Sordi e disabilità uditiva. Il valore predefinito è false.
snippet.isLarge boolean
Indica se la traccia dei sottotitoli utilizza testo di grandi dimensioni per ipovedenti. Il valore predefinito è false.
snippet.isEasyReader boolean
Indica se la traccia dei sottotitoli è formattata per "easy reader", ovvero a un livello di terza elementare per gli studenti di lingue. Il valore predefinito è false.
snippet.isDraft boolean
Indica se la traccia dei sottotitoli codificati è una bozza. Se il valore è true, la traccia non è visibile pubblicamente. Il valore predefinito è false.
snippet.isAutoSynced boolean
Indica se YouTube ha sincronizzato la traccia dei sottotitoli con la traccia audio del video. Il valore sarà true se è stata richiesta esplicitamente una sincronizzazione al momento del caricamento della traccia dei sottotitoli codificati. Ad esempio, quando chiami i metodi captions.insert o captions.update, puoi impostare il parametro sync su true per indicare a YouTube di sincronizzare la traccia caricata con il video. Se il valore è false, YouTube utilizza i codici temporali nella traccia di sottotitoli caricata per stabilire quando visualizzare i sottotitoli.
snippet.status string
Stato della traccia dei sottotitoli codificati.

I valori validi per questa proprietà sono:
  • failed
  • serving
  • syncing
snippet.failureReason string
Il motivo per cui YouTube non è riuscito a elaborare la traccia dei sottotitoli codificati. Questa proprietà è presente solo se il valore della proprietà state è failed.

I valori validi per questa proprietà sono:
  • processingFailed – YouTube non è riuscito a elaborare la traccia dei sottotitoli codificati caricata.
  • unknownFormat - Il formato della traccia di sottotitoli non è stato riconosciuto.
  • unsupportedFormat - Il formato della traccia di sottotitoli non è supportato.