Captions

AI-generated Key Takeaways

• YouTube deprecated the sync parameter for the captions.insert and captions.update API endpoints on March 13, 2024, but auto-syncing remains available in YouTube Creator Studio.

• A caption resource represents a YouTube caption track, which is associated with one specific YouTube video, and the API provides methods to list, insert, update, download, and delete these tracks.

• The captions resource includes a snippet object that contains details like the associated videoId, the language, the trackKind, and whether it's a draft, among others.

• The caption track's snippet.isAutoSynced boolean property indicates if YouTube synchronized the caption track to the audio, with a false value indicating that YouTube used the time codes in the uploaded track.

• Caption track properties include status indicators such as serving, syncing, or failed, with failureReason providing the specific reason for any failures, such as processingFailed or unsupportedFormat.

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. Try it now.

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. Try it now.

download

Download a caption track. The caption track is returned to its original format unless the request specifies a value for the tfmt parameter and to its original language unless the request specifies a value for the tlang parameter. Try it now.

delete

Delete a specified caption track. Try it now.

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.