Questa pagina è stata tradotta dall'API Cloud Translation.

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.