Create YouTube videos
A <video> tag provides metadata about a YouTube video. Whereas the subtags of the <asset> tag identify and describe an asset, the subtags of the <video> tag define data that affects the way the video is displayed on YouTube’s website or the way that YouTube users can locate the video by browsing or searching for videos.
A video is associated with exactly one reference. However, a reference will only be associated with a video if you have elected to create a public or private YouTube video from the reference.
The most common use case is to have an asset that has exactly one reference that will also be a public YouTube video. The sample feed below illustrates how you might construct a feed for this use case. In this case, the parser requires you to claim the video that is being created since the reference is being linked to an asset at the same time that the video is being created. The example identifies the rights administrator for the asset as well as the policy that will be applied to the claimed video.
<asset type="web" tag="foo.mpg"> <title>Webisode of Foo, attempt II</title> <custom_id>1234-abcde</custom_id> <!-- other asset details included in feed --> </asset> <file type="video" tag="foo.mpg"> <filename>foo.mpg</filename> </file> <ownership/> <relationship> <item path="/feed/asset[@tag='foo.mpg']"/> <related_item path="/feed/ownership[1]"/> </relationship> <video tag="foo.mpg"> <title>Webisode of Foo</title> <description>Catch new recipes from Foo.</description> <keyword>FooReality</keyword> <keyword>FooCooking</keyword> <genre>Comedy</genre> <allow_embedding>False</allow_embedding> <allow_comments>Approve</allow_comments> <allow_ratings>True</allow_ratings> <public>True</public> </video> <relationship> <item path="/feed/file[@tag='foo.mpg']"/> <related_item path="/feed/asset[@tag='foo.mpg']"/> <related_item path="/feed/video[@tag='foo.mpg']"/> </relationship> <rights_admin type="usage" owner="True"/> <rights_admin type="match" owner="True"/> <!-- declare a one-off policy --> <rights_policy> <rule action="monetize"/> </rights_policy> <!-- Claim our uploaded video with the one-off policy --> <claim type="audiovisual" video="/feed/video[@tag='foo.mpg']" asset="/feed/asset[@tag='foo.mpg']" rights_admin="/feed/rights_admin[@type='usage']" rights_policy="/feed/rights_policy[1]"/> <relationship> <item path="/feed/rights_admin[@type='match']"/> <item path="/feed/rights_policy[1]"/> <related_item path="/feed/asset[@tag='foo.mpg']"/> </relationship>
Add captions or caption certification files
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 totimed_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>
Update video metadata
To update metadata for a video, you first need to provide information to identify the video you want to update. You use the YouTube-assigned video ID to uniquely identify the video. The XML snippet updates the title of the video without affecting its other metadata:
<video type="episode" id="VIDEO_ID_1_"> <title>New video title</title> </video>
You only need to provide values for the metadata fields you are updating. The new values overwrite the previous values, even for fields like <keyword> that accept repeating values. You cannot incrementally update a repeating tag value by only adding the new values in your feed.
If you leave a field out, it will not be updated, and fields that have default values will not be reset to their defaults if you omit them. Or, if you prefer, you can provide all of the metadata for the asset in the update request, specifying the already existing values for fields that have not changed.
When you upload a show or movie to YouTube using the XML content feed, you can specify values for certain metadata fields as part of the asset definition or the video definition. For example, you can identify the <director> as a subtag of the <asset> tag or the <video> tag. When YouTube processes your upload, these shared metadata tags are ultimately stored as part of the video regardless of where you specified them in the feed.
| Video metadata fields that you can set on the asset during upload | ||
|---|---|---|
| <actor> | <notes> | <show_custom_id> |
| <content_type> | <original_release_date> | <spoken_language> |
| <director> | <original_release_medium> | <subtitled_language> |
| <episode> | <producer> | <tms_id> |
| <genre> | <rating> | <url> |
| <season> | <writer> | |
If you subsequently need to update the values for these fields, you must update the video, not the asset. You need the video ID, not the asset ID. You won’t receive an error if you update the asset, but your changes won’t be reflected on the video.
Delete videos
You can use the <video> tag’s delete action to remove a video from YouTube’s website (if the video is publicly visible) and also remove the video from the My Videos page in your YouTube account. In addition, by deleting a video, you will also delete all of that video’s statistics, such as the number of times the video had been viewed, as well as user comments associated with the video.
The sample feed below demonstrates how to delete a video. The sample uses the <video> tag’s id attribute to identify the video to be deleted and sets the tag’s action attribute value to delete.
<feed xmlns="http://www.youtube.com/schemas/cms/2.0" channel="TestChannel"> <video action="delete" id="VIDEO_ID_1_"/> </feed>
Please note the following other aspects of this feature:
- Deleting a video does not have any impact on the reference file associated with that video. If you also want to remove the reference matching the video from YouTube’s Content ID system, you also need to delete the reference file.
- Once you have deleted a video, you will be able to successfully upload the same video to the same YouTube account. For this reason, this feature can be very useful while you are testing your feed uploading systems since you can use the same video(s) during your testing process and automatically delete the videos between tests.
Manage playlists
A playlist is a collection of videos that can be viewed sequentially and shared with other users. The same video can be included in multiple playlists.
A <playlist> tag identifies a playlist that you want to create, update, or delete. The following sections show different types of operations that you can perform for playlists.
The following example demonstrates how to create a playlist. The <name> tag inside of the <playlist> tag specifies the playlist name, and the <item> tags identify the videos that are being added to the playlist. Each <item> tag specifies a value for the index attribute, which indicates where the video appears in the playlist.
<playlist> <name>Comedy highlights</name> <item path="/external/video[@id='VIDEO_ID_1_']"/> <item path="/external/video[@id='VIDEO_ID_2_']"/> <item path="/external/video[@id='VIDEO_ID_3_']"/> </playlist>
The example above uses a number of default playlist settings. As such, if you include this excerpt in a feed (with valid video IDs), you will see the following behavior:
- Since the <playlist> tag does not specify a value for its channel attribute, the playlist will be created in the default YouTube user account identified for your content owner. If you specify a value for the channel attribute, then the playlist will be created in that channel instead. (The channel must be linked to your content owner.)
- Since the <item> tags do not specify values for the index attribute, the videos will be added to the playlist in the order that they appear in the feed.
- Since none of the <item> tags contain the icon attribute (with a value of True), a thumbnail image from the first video in the playlist will be used as the playlist’s icon. If you do set the icon attribute to True for one of the videos in the playlist, then that video will automatically appear first in the playlist, regardless of any other ordering instructions that you include for the playlist videos.
In addition, note that this example specifies a playlist name of “Comedy highlights“. If your channel already contained a playlist with that name, then the request above would create a second playlist with the same name.
The following XML demonstrates how to add an additional video to the playlist created in the previous section:
<playlist id="PL586D322B5E2764CF"> <item path="/external/video[@id='VIDEO_ID_4_']"/> </playlist>
To reorder the videos in a playlist, use the <item> tag’s index attribute to explicitly specify the order in which the videos should appear. The following XML updates the playlist created in the previous section so that instead of having videos appear in 1-2-3-4 order, they appear in 3-1-4-2 order. (The third video has an index value of 1, the first video has an index value of 2, and so forth.)
<playlist id="PL586D322B5E2764CF"> <item index="1" path="/external/video[@id='VIDEO_ID_3_']"/> <item index="2" path="/external/video[@id='VIDEO_ID_1_']"/> <item index="3" path="/external/video[@id='VIDEO_ID_4_']"/> <item index="4" path="/external/video[@id='VIDEO_ID_2_']"/> </playlist>
The example below reorders the videos in the same way, but it uses the icon attribute to indicate that the third video appears first in the playlist. The icon attribute value supersedes the other ordering instructions for the playlist items:
<playlist id="PL586D322B5E2764CF"> <item icon="True" path="/external/video[@id='VIDEO_ID_3_']"/> <item index="2" path="/external/video[@id='VIDEO_ID_1_']"/> <item index="3" path="/external/video[@id='VIDEO_ID_4_']"/> <item index="4" path="/external/video[@id='VIDEO_ID_2_']"/> </playlist>
To remove a video from a playlist, set the action attribute value to delete for that item. The example below removes the fourth video from the playlist:
<playlist id="PL586D322B5E2764CF"> <item action="delete" path="/external/video[@id='VIDEO_ID_4_']"/> </playlist>
To make a playlist a series playlist, set the <playlist> tag’s series attribute value to True for that playlist. By default, playlists are not created as series playlists, and if you do not specify a value for the series attribute, then YouTube will not update the playlist’s existing state.
The following XML updates the playlist created in the example above into a series playlist:
<playlist series="True"/> <name>Comedy highlights</name> </playlist>
Define channel page layouts
Channels with the YouTube One Channel design have a Browse view that showcases their content. The Browse view organizes channel content into customized sections that display videos from particular playlists or based on channel usage, like the most recent or most popular videos. You can also choose a “trailer” video to show to non-subscribers when they visit your channel.
The <channel> tag sets the custom layout of the Browse view by specifying which <sections> to include and which video to use as the <trailer>. You can only set the layout for an existing channel linked to your content owner, and the channel must use the YouTube One Channel design for the settings to have any visible effect.
The following example configures the channel’s Browse view to include a trailer and four sections. Each <section> has atype attribute that specifies which videos to include and a style attribute that specifies the layout for that section. The first section displays the videos from the specified playlist in a horizontal row (style=”expanded”). The other three sections retrieve videos based on channel activity – recent uploads, likes, and upcoming events – and display only the first item (style=”compact”).
<channel id="CHANNEL_ID_1_"> <trailer video_id="VIDEO_ID_1_" /> <sections> <section type="single_playlist" style="expanded"> <playlist id="PLAYLIST_ID_1_" /> </section> <section type="recent_uploads" style="compact" /> <section type="likes" style="compact" /> <section type="upcoming_events" style="compact" /> </sections> </channel>
Updating channel layouts
When the feed includes the <trailer> or <sections> tag, the specified layout overwrites the current layout of the channel’s Browse view. To retain the current trailer video or sections, omit the <trailer> or <sections> tag. Use the following tag to remove the current trailer without providing a replacement.
<trailer action="delete" />
For more information on Multi Channel Network’s and YouTube how to videos please check back weekly or subscribe here.
