Add captions or caption certification files

The YouTube XML format is being replaced by DDEX (music only) and CSV templates (all industries). YouTube strongly discourages any new implementations of the YouTube XML format. This page should be used solely as reference material for existing implementations. Visit Using the YouTube DDEX feed for more information about the new format.
The features described in this article are available only to partners who use YouTube's Content Manager to manage their copyrighted content.

A <caption> tag either contains metadata about a caption track that is also specified in your feed (using a <file> tag) or it contains a certification explaining why captions are not available for a video. 

Providing captions

If you are providing a caption track for a video, then the <caption> tag's contents specify a title for the caption track, the track's language, and the format of the caption file. The following list identifies the elements that must be present in your feed to associate captions with a video:

  • A <file> tag identifies the file that actually contains the caption track. This file must be posted to the same directory as the XML file you are uploading or to a subdirectory of that directory. The <file> tag's type attribute value must be set to timed_text.

  • A <caption> tag encapsulates metadata about the caption track.

    • The <language> tag specifies the language of the text in the caption track. The value must be a two-letter ISO 639-1 language code.

    • The <name> tag specifies the display name for the caption track. By default, the YouTube player uses the language of a caption track as its display name. However, if a video has multiple caption tracks in the same language, you must specify a <name> to differentiate between those tracks.

      If you are uploading a caption track and you specify the same name and language as a previously uploaded track for the same video, the track that you are uploading will overwrite the previously uploaded track. Similarly, if a video already has a track in a particular language, and the track does not have an additional name, and you add a new track in the same language without specifying a track name, the new track will also overwrite the older one.

    • The <format> tag specifies the format of the caption file. The value must be transcript if the file is a transcript without timestamps that needs to be aligned with the video content and converted to captions. YouTube supports a number of caption file formats, including SubViewer (sbv), SubRip (srt), and Scenarist (scc).

      If you would like YouTube to process the file as a transcript if it does not match one of our supported caption file formats, set the <name> tag value to transcript. In that case, YouTube will attempt to convert the file's contents to a caption track and align the captions with the video's audio track.

    • The <enabled> tag specifies whether the captions appear when users view the video. Set it to False if you want to review the captions against the video before displaying them to users. Disabled captions appear on the video when you are signed in as the owner of the video, but not when other users view it.

  • A <relationship> associates the caption track and the caption metadata with the appropriate video. Within the <relationship> tag, the caption track and metadata are identified by <item> tags, and the video is identified by a <related_item> tag.

The XML snippet below demonstrates how to add captions to a video. The example defines a caption track and caption metadata and associates them with a previously uploaded video.


<feed
   xmlns="http://www.youtube.com/schemas/cms/2.0"
   notification_email="someone@example.com" channel="TestChannel">

    <caption tag="EN-12345678abc">
      <format>sbv</format>
      <language>EN</language>
      <name>English</name>
    </caption>
 
    <file type="timed_text" tag="EN-12345678abc">
      <filename>en_12345678abc.sbv</filename>
    </file>

    <relationship>
      <item path="/feed/caption[@tag='EN-12345678abc']"/>
      <item path="/feed/file[@tag='EN-12345678abc']"/>
      <related_item path="/external/video[@id='12345678abc']"/>
    </relationship>

</feed>

Providing a caption certification

If you are providing a caption certification tag for a video, then the <caption> tag contains a <certification> tag that, in turn, contains a <reason> tag, which specifies the reason that captions are not available for the video. The XML snippet below contains a caption certification that is associated with a video:


<feed
   xmlns="http://www.youtube.com/schemas/cms/2.0" channel="TestChannel">

  <caption tag="CERT1">
    <certification>
      <reason>1</reason>
    </certification>
  </caption>

  <relationship>
    <item path="/feed/caption[@tag='CERT1']"/>
    <related_item path="/external/video[@id='LsapmlueBgo']"/>
  </relationship>

</feed>
Was this helpful?
How can we improve it?