Captions

Nota: El 13 de marzo de 2024, YouTube anunció que dejará de admitir el parámetro sync para los extremos de la API de captions.insert y captions.update. La sincronización automática de subtítulos sigue disponible en YouTube Creator Studio. Consulta el historial de revisiones de la API para obtener más detalles.

Un recurso caption representa una pista de subtítulos de YouTube. Una pista de subtítulos se asocia con exactamente un video de YouTube.

Métodos

La API admite los siguientes métodos para los recursos captions:

list
Recupera una lista de pistas de subtítulos asociadas con un video específico. Ten en cuenta que la respuesta de la API no contiene los subtítulos reales y que el método captions.download permite recuperar una pista de subtítulos. Pruébalo ahora.
insertar
Sube una pista de subtítulos. Pruébala ahora.
actualización
Actualiza una pista de subtítulos. Cuando actualizas una pista de subtítulos, puedes cambiar el estado de borrador, subir un archivo de subtítulos nuevo o ambas opciones. Pruébalo ahora.
descargar
Descarga una pista de subtítulos. La pista de subtítulos se muestra en su formato original, a menos que la solicitud especifique un valor para el parámetro tfmt, y en su idioma original, a menos que la solicitud especifique un valor para el parámetro tlang. Pruébalo ahora.
borrar
Borra una pista de subtítulos especificada. Pruébala ahora.

Representación de recursos

En la siguiente estructura JSON, se muestra el formato de un recurso 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
  }
}

Propiedades

La siguiente tabla define las propiedades que aparecen en este recurso:

Propiedades
kindstring
Identifica el tipo de recurso de la API. El valor será youtube#caption.
etagetag
Es la etiqueta de Etag de este recurso.
idstring
Es el ID que YouTube usa para identificar de forma inequívoca la pista de subtítulos.
snippetobject
El objeto snippet contiene detalles básicos sobre el subtítulo.
snippet.videoIdstring
Es el ID que YouTube usa para identificar de forma exclusiva el video asociado con la pista de subtítulos.
snippet.lastUpdateddatetime
Es la fecha y hora de la última actualización de la pista de subtítulos. El valor se especifica en formato ISO 8601.
snippet.trackKindstring
Es el tipo de pista de subtítulos.

Los valores válidos para esta propiedad son los siguientes:
  • ASR: Es una pista de subtítulos generada con el reconocimiento de voz automático.
  • forced: Es una pista de subtítulos que se reproduce cuando no se selecciona ninguna otra pista en el reproductor. Por ejemplo, un video que muestra a extraterrestres que hablan en un idioma extraterrestre puede tener una pista de subtítulos forzada para mostrar solo subtítulos en ese idioma.
  • standard: Es una pista de subtítulos normal. Este es el valor predeterminado.
snippet.languagestring
Es el idioma de la pista de subtítulos. El valor de la propiedad es una etiqueta de idioma BCP-47.
snippet.namestring
Es el nombre de la pista de subtítulos. El usuario debe poder ver el nombre como una opción durante la reproducción. La longitud máxima del nombre admitida es de 150 caracteres.
snippet.audioTrackTypestring
Es el tipo de pista de audio asociada con la pista de subtítulos.

Los valores válidos para esta propiedad son los siguientes:
  • commentary: La pista de subtítulos corresponde a una pista de audio alternativa que incluye comentarios, como los de directorio.
  • descriptive: La pista de subtítulos corresponde a una pista de audio alternativa que incluye audio descriptivo adicional.
  • primary: La pista de subtítulos corresponde a la pista de audio principal del video, que es la pista de audio que normalmente se asocia con el video.
  • unknown: Este es el valor predeterminado.
snippet.isCCboolean
Indica si la pista contiene subtítulos para personas con hipoacusia y discapacidad auditiva. El valor predeterminado es false.
snippet.isLargeboolean
Indica si la pista de subtítulos usa texto grande para personas con discapacidad visual. El valor predeterminado es false.
snippet.isEasyReaderboolean
Indica si la pista de subtítulos tiene el formato de “lector fácil”, es decir, que está en un nivel de tercer grado para estudiantes de idiomas. El valor predeterminado es false.
snippet.isDraftboolean
Indica si la pista de subtítulos es un borrador. Si el valor es true, el segmento no es visible para el público. El valor predeterminado es false.
snippet.isAutoSyncedboolean
Indica si YouTube sincroniza la pista de subtítulos con la pista de audio del video. El valor será true si se solicitó explícitamente una sincronización cuando se subió la pista de subtítulos. Por ejemplo, cuando llames a los métodos captions.insert o captions.update, puedes establecer el parámetro sync en true para indicarle a YouTube que sincronice la pista subida con el video. Si el valor es false, YouTube usa los códigos de tiempo de la pista de subtítulos subida para determinar cuándo mostrarlos.
snippet.statusstring
Es el estado de la pista de subtítulos.

Los valores válidos para esta propiedad son los siguientes:
  • failed
  • serving
  • syncing
snippet.failureReasonstring
Es el motivo por el que YouTube no pudo procesar la pista de subtítulos. Esta propiedad solo está presente si el valor de la propiedad state es failed.

Los valores válidos para esta propiedad son los siguientes:
  • processingFailed: YouTube no pudo procesar la pista de subtítulos subida.
  • unknownFormat: No se reconoció el formato de la pista de subtítulos.
  • unsupportedFormat: No se admite el formato de la pista de subtítulos.