Captions
Stay organized with collections
Save and categorize content based on your preferences.
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:
|
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.
|
Except as otherwise noted, the content of this page is licensed under the
Creative Commons Attribution 4.0 License
, and code samples are licensed under the
Apache 2.0 License
. For details, see the
Google Developers Site Policies
. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-03-14 UTC.
[{
"type": "thumb-down",
"id": "missingTheInformationINeed",
"label":"Missing the information I need"
},{
"type": "thumb-down",
"id": "tooComplicatedTooManySteps",
"label":"Too complicated / too many steps"
},{
"type": "thumb-down",
"id": "outOfDate",
"label":"Out of date"
},{
"type": "thumb-down",
"id": "samplesCodeIssue",
"label":"Samples / code issue"
},{
"type": "thumb-down",
"id": "otherDown",
"label":"Other"
}]
[{
"type": "thumb-up",
"id": "easyToUnderstand",
"label":"Easy to understand"
},{
"type": "thumb-up",
"id": "solvedMyProblem",
"label":"Solved my problem"
},{
"type": "thumb-up",
"id": "otherUp",
"label":"Other"
}]