Captions

Remarque:Le 13 mars 2024, YouTube a annoncé l'abandon du paramètre sync pour les points de terminaison des API captions.insert et captions.update. La synchronisation automatique des sous-titres reste disponible dans YouTube Studio. Pour en savoir plus, consultez l'historique des révisions de l'API.

Une ressource caption représente une piste de sous-titres YouTube. Une piste de sous-titres est associée à une seule vidéo YouTube.

Méthodes

L'API est compatible avec les méthodes suivantes pour les ressources captions:

liste
Récupère la liste des pistes de sous-titres associées à une vidéo spécifique. Notez que la réponse de l'API ne contient pas les sous-titres réels et que la méthode captions.download permet de récupérer une piste de sous-titres. Essayer maintenant
insérer
Importez une piste de sous-titres.
mise à jour
Modifier une piste de sous-titres. Lorsque vous modifiez une piste de sous-titres, vous pouvez modifier son état brouillon et/ou importer un nouveau fichier de sous-titres pour cette piste.
supprimer
Supprimer une piste de sous-titres spécifiée. Essayer
télécharger
Téléchargez une piste de sous-titres. La piste de sous-titres est renvoyée dans son format d'origine, sauf si la requête spécifie une valeur pour le paramètre tfmt et dans sa langue d'origine, sauf si elle spécifie une valeur pour le paramètre tlang.

Représentation des ressources

La structure JSON suivante montre le format d'une ressource 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
  }
}

Propriétés

Le tableau suivant définit les propriétés qui apparaissent dans cette ressource:

Propriétés
kind string
Identifie le type de ressource d'API. La valeur est youtube#caption.
etag etag
Etag de cette ressource.
id string
ID utilisé par YouTube pour identifier la piste de sous-titres de manière unique.
snippet object
L'objet snippet contient des informations de base sur les légendes.
snippet.videoId string
ID utilisé par YouTube pour identifier de façon unique la vidéo associée à la piste de sous-titres.
snippet.lastUpdated datetime
Date et heure de la dernière mise à jour de la piste de sous-titres. La valeur est spécifiée au format ISO 8601.
snippet.trackKind string
Type de la piste de sous-titres.

Les valeurs valides pour cette propriété sont les suivantes :
  • ASR : piste de sous-titres générée à l'aide de la reconnaissance vocale automatique.
  • forced : piste de sous-titres qui est lue lorsqu'aucune autre piste n'est sélectionnée dans le lecteur. Par exemple, une vidéo montrant des extraterrestres parlant dans une langue étrangère peut disposer d'une piste de sous-titres forcée pour n'afficher que les sous-titres pour la langue extraterrestre.
  • standard : piste de sous-titres standard. Il s'agit de la valeur par défaut.
snippet.language string
Langue de la piste de sous-titres. La valeur de la propriété est une balise de langue BCP-47.
snippet.name string
Nom de la piste de sous-titres. Ce nom est destiné à être visible par l'utilisateur en tant qu'option lors de la lecture. Le nom ne doit pas dépasser 150 caractères.
snippet.audioTrackType string
Type de piste audio associée à la piste de sous-titres.

Les valeurs valides pour cette propriété sont les suivantes :
  • commentary : la piste de sous-titres correspond à une autre piste audio incluant des commentaires (par exemple, un commentaire du répertoire).
  • descriptive : la piste de sous-titres correspond à une autre piste audio qui comprend une piste audio descriptive supplémentaire.
  • primary : la piste de sous-titres correspond à la piste audio principale de la vidéo, qui est normalement associée à la vidéo.
  • unknown : valeur par défaut.
snippet.isCC boolean
Indique si le titre contient des sous-titres destinés aux sourds et aux malentendants. La valeur par défaut est false.
snippet.isLarge boolean
Indique si la piste de sous-titres contient du texte en gros caractères pour les malvoyants. La valeur par défaut est false.
snippet.isEasyReader boolean
Indique si le format de la piste de sous-titres est adapté à la lecture facile, c'est-à-dire si elle est de CE2 pour les apprenants de langue étrangère. La valeur par défaut est false.
snippet.isDraft boolean
Indique si la piste de sous-titres est un brouillon. Si la valeur est true, le canal n'est pas visible publiquement. La valeur par défaut est false.
snippet.isAutoSynced boolean
Indique si YouTube a synchronisé la piste de sous-titres avec la piste audio de la vidéo. La valeur est true si une synchronisation a été explicitement demandée lors de l'importation de la piste de sous-titres. Par exemple, lorsque vous appelez les méthodes captions.insert ou captions.update, vous pouvez définir le paramètre sync sur true pour demander à YouTube de synchroniser la piste importée avec la vidéo. Si la valeur est false, YouTube utilise les codes temporels de la piste de sous-titres importées pour déterminer quand afficher les sous-titres.
snippet.status string
État de la piste de sous-titres.

Les valeurs valides pour cette propriété sont les suivantes :
  • failed
  • serving
  • syncing
snippet.failureReason string
Raison pour laquelle YouTube n'a pas pu traiter la piste de sous-titres. Cette propriété n'est présente que si la valeur de la propriété state est failed.

Les valeurs valides pour cette propriété sont les suivantes :
  • processingFailed : YouTube n'a pas réussi à traiter la piste de sous-titres importée.
  • unknownFormat : le format de la piste de sous-titres n'est pas reconnu.
  • unsupportedFormat : le format de la piste de sous-titres n'est pas accepté.