Questa pagina è stata tradotta dall'API Cloud Translation.

Captions

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

Una risorsa caption rappresenta una traccia di sottotitoli codificati di YouTube. Una traccia di sottotitoli codificati è associata esattamente a un 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 specificato. 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.
inserire: Carica una traccia di sottotitoli codificati.
aggiornamento: Aggiornare una traccia di sottotitoli codificati. Durante l'aggiornamento di una traccia di sottotitoli codificati, puoi modificarne lo stato di bozza, caricare un nuovo file di sottotitoli codificati per la traccia o eseguire entrambe le operazioni.
elimina: Eliminare una traccia di sottotitoli specificata. Prova subito.
scarica: 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 sua lingua originale, a meno che la richiesta non specifichi un valore per il parametro tlang.

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 di 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 della traccia dei 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 in cui vengono mostrati alieni che parlano in una lingua aliena potrebbe disporre di una traccia di sottotitoli forzata per mostrare solo i sottotitoli per tale lingua. `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 è di 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 di sottotitoli codificati corrisponde a una traccia audio alternativa che include commenti, come i commenti della directory. `descriptive` - La traccia di sottotitoli codificati 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 la traccia audio normalmente associata al video. `unknown` - Questo è il valore predefinito.
`snippet.isCC`	`boolean` Indica se la traccia contiene sottotitoli per le persone sorde e con disabilità uditiva. Il valore predefinito è `false`.
`snippet.isLarge`	`boolean` Indica se la traccia di sottotitoli codificati utilizza testo di grandi dimensioni per gli ipovedenti. Il valore predefinito è `false`.
`snippet.isEasyReader`	`boolean` Indica se la traccia di sottotitoli codificati è formattata per "easy reader", ovvero se è di terza elementare per gli studenti di lingue. Il valore predefinito è `false`.
`snippet.isDraft`	`boolean` Indica se la traccia di sottotitoli è 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 codificati con la traccia audio del video. Il valore sarà `true` se è stata richiesta esplicitamente una sincronizzazione quando è stata caricata la 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 determinare quando visualizzare i sottotitoli.
`snippet.status`	`string` Lo stato della traccia di 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 di 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 di sottotitoli caricata. `unknownFormat` - Il formato della traccia di sottotitoli codificati non è stato riconosciuto. `unsupportedFormat` - Il formato della traccia di sottotitoli codificati non è supportato.