Captions

Note: On March 13, 2024, YouTube announced that it is deprecating the sync parameter for the captions.insert and captions.update API endpoints. Captions auto-syncing is still available in YouTube Creator Studio. See the API revision history for more details.

A caption resource represents a YouTube caption track. A caption track is associated with exactly one YouTube video.

Methods

The API supports the following methods for captions resources:

list: Retrieve a list of caption tracks that are associated with a specified video. Note that the API response does not contain the actual captions and that the captions.download method provides the ability to retrieve a caption track. Try it now.
insert: Upload a caption track.
update: Update a caption track. When updating a caption track, you can change the track's draft status, upload a new caption file for the track, or both.
delete: Delete a specified caption track. Try it now.
download: Download a caption track. The caption track is returned in its original format unless the request specifies a value for the tfmt parameter and in its original language unless the request specifies a value for the tlang parameter.

Resource representation

The following JSON structure shows the format of a captions resource:

{
  "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
  }
}

Properties

The following table defines the properties that appear in this resource:

Properties
`kind`	`string` Identifies the API resource's type. The value will be `youtube#caption`.
`etag`	`etag` The Etag of this resource.
`id`	`string` The ID that YouTube uses to uniquely identify the caption track.
`snippet`	`object` The `snippet` object contains basic details about the caption.
`snippet.videoId`	`string` The ID that YouTube uses to uniquely identify the video associated with the caption track.
`snippet.lastUpdated`	`datetime` The date and time when the caption track was last updated. The value is specified in ISO 8601 format.
`snippet.trackKind`	`string` The caption track's type. Valid values for this property are: `ASR` – A caption track generated using automatic speech recognition. `forced` – A caption track that plays when no other track is selected in the player. For example, a video that shows aliens speaking in an alien language might have a forced caption track to only show subtitles for the alien language. `standard` – A regular caption track. This is the default value.
`snippet.language`	`string` The language of the caption track. The property value is a BCP-47 language tag.
`snippet.name`	`string` The name of the caption track. The name is intended to be visible to the user as an option during playback. The maximum name length supported is 150 characters.
`snippet.audioTrackType`	`string` The type of audio track associated with the caption track. Valid values for this property are: `commentary` – The caption track corresponds to an alternate audio track that includes commentary, such as directory commentary. `descriptive` – The caption track corresponds to an alternate audio track that includes additional descriptive audio. `primary` – The caption track corresponds to the primary audio track for the video, which is the audio track normally associated with the video. `unknown` – This is the default value.
`snippet.isCC`	`boolean` Indicates whether the track contains closed captions for the deaf and hard of hearing. The default value is `false`.
`snippet.isLarge`	`boolean` Indicates whether the caption track uses large text for the vision-impaired. The default value is `false`.
`snippet.isEasyReader`	`boolean` Indicates whether caption track is formatted for "easy reader," meaning it is at a third-grade level for language learners. The default value is `false`.
`snippet.isDraft`	`boolean` Indicates whether the caption track is a draft. If the value is `true`, then the track is not publicly visible. The default value is `false`.
`snippet.isAutoSynced`	`boolean` Indicates whether YouTube synchronized the caption track to the audio track in the video. The value will be `true` if a sync was explicitly requested when the caption track was uploaded. For example, when calling the `captions.insert` or `captions.update` methods, you can set the `sync` parameter to `true` to instruct YouTube to sync the uploaded track to the video. If the value is `false`, YouTube uses the time codes in the uploaded caption track to determine when to display captions.
`snippet.status`	`string` The caption track's status. Valid values for this property are: `failed` `serving` `syncing`
`snippet.failureReason`	`string` The reason that YouTube failed to process the caption track. This property is only present if the `state` property's value is `failed`. Valid values for this property are: `processingFailed` – YouTube failed to process the uploaded caption track. `unknownFormat` – The caption track's format was not recognized. `unsupportedFormat` – The caption track's format is not supported.