Questa pagina è stata tradotta dall'API Cloud Translation.

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.