Captions

Nota: il 13 marzo 2024 YouTube ha annunciato che ritirerà il parametro sync per gli endpoint API captions.insert e captions.update. La sincronizzazione automatica dei sottotitoli codificati è ancora disponibile in YouTube Creator Studio. Per ulteriori dettagli, consulta la cronologia delle revisioni dell'API.

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

Metodi

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

list
Recupero di 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 consente di recuperare una traccia di sottotitoli codificati. Prova subito.
insert
Carica una traccia sottotitoli codificati. Prova subito.
update
Aggiorna una traccia sottotitoli. Quando aggiorni una traccia dei sottotitoli codificati, puoi modificare lo stato della bozza della traccia, caricare un nuovo file dei sottotitoli codificati per la traccia o entrambe le cose. Prova subito.
scaricare
Scarica una traccia dei 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. Prova subito.
elimina
Elimina una traccia dei sottotitoli codificati specificata. Prova subito.

Rappresentazione delle risorse

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 dei 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 sottotitoli codificati che viene 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 codificati standard. Questo è il valore predefinito.
snippet.language string
La lingua della traccia dei sottotitoli codificati. Il valore della proprietà è un tag 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 è di 150 caratteri.
snippet.audioTrackType string
Il tipo di traccia audio associata alla traccia dei 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 codificati corrisponde a una traccia audio alternativa che include 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 codificati per non udenti e persone con disabilità uditiva. Il valore predefinito è false.
snippet.isLarge boolean
Indica se la traccia dei sottotitoli codificati utilizza un testo grande per le persone con disabilità visive. Il valore predefinito è false.
snippet.isEasyReader boolean
Indica se la traccia dei sottotitoli codificati è formattata per "lettori facili", ovvero è a 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, il canale non è visibile pubblicamente. Il valore predefinito è false.
snippet.isAutoSynced boolean
Indica se YouTube ha sincronizzato la traccia dei sottotitoli codificati 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 dei sottotitoli codificati caricata per determinare quando visualizzare i sottotitoli.
snippet.status string
Lo 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 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 codificati non è stato riconosciuto.
  • unsupportedFormat: il formato della traccia dei sottotitoli codificati non è supportato.