Implementation: Captions

To retrieve a list of caption tracks that are available for a specific video, call the captions.list method. Set the videoId parameter value to the YouTube video ID that uniquely identifies the video for which you are retrieving captions. Your request must be authorized using OAuth 2.0.

The request below retrieves a list of captions for a video on the Google Stories YouTube channel:

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.list?
part=snippet
&videoId=PRU2ShMzQRg

See the captions.list method's documentation for code samples.

This query cannot be tested using the APIs Explorer because the APIs Explorer does not support the ability to upload files, which is a requirement for this method.

You can use the API's captions.insert method to upload a new caption track for a video. When uploading a track, you must specify a value for the following caption resource properties:

• snippet.videoId - This identifies the video to which the caption track is being added.
• snippet.language - The language of the caption track.
• snippet.name - The name of the caption track.

The following additional options are available when uploading a caption track:

• If you set the sync parameter to true, YouTube will disregard any time codes that are in the uploaded caption file and generate new time codes for the captions.

  You should set the sync parameter to true if you are uploading a transcript, which has no time codes, or if you suspect the time codes in your file are incorrect and want YouTube to try to fix them.

• If you set the caption resource's snippet.isDraft property to true, the track will not be publicly visible.

See the captions.insert method's documentation for code samples.

This query cannot be tested using the APIs Explorer because the APIs Explorer does not support the ability to download files.

To download a specific caption track, call the captions.download method. Set the id parameter value to the YouTube caption track ID that uniquely identifies the caption track that you are downloading. Your request must be authorized using OAuth 2.0.

The v3 API supports the following options:

• To specify that a caption track should be returned in a specific format, set the tfmt parameter value to identify the desired format. The parameter definition lists supported values.

• To retrieve a translation of a caption track, set the tlang parameter value to an ISO 639-1 two-letter language code that identifies the desired caption language. The translation is generated by using machine translation, such as Google Translate.

See the captions.download method's documentation for code samples.

The API supports the ability to change a caption track's draft status, upload a new caption track for a file, or both.

You can use the APIs Explorer to test the ability to change a track's draft status. However, you cannot use the APIs Explorer to update the actual caption track because tool does not support the ability to upload files.

The request below retrieves a list of captions for a video on the Google Stories YouTube channel:

The request updates the draft status of a caption track to true, which means the track will not be publicly visible. To complete the request in the APIs Explorer, you need to set the id property's value to identify a caption track.

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.update?
part=snippet

See the captions.update method's documentation for code samples.

This example shows how to delete a caption track. The example has the following steps:

• Step 1: Retrieve the caption track ID

  Follow the steps above to retrieve a list of caption tracks for a video. The list could be used to display a list of caption tracks, using each track's ID as a key.

• Step 2: Delete the track

  Call the captions.delete method to delete a specific video. In the request, the id parameter specifies the caption track ID of the track that you are deleting. The request must be authorized using OAuth 2.0. If you are testing this query in the APIs Explorer, you will need to substitute a valid caption track ID for the id parameter value.

  https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.captions.delete?
  id=CAPTION_TRACK_ID