Rights administration and policies
Assets
Create assets
An asset is the representation of your intellectual property in the YouTube rights management system. An <asset> tag identifies and describes an asset. The tag’s type attribute indicates what kind of asset it is, such as a movie, music video, sound recording, television episode, or composition. The other attributes provide various ways of identifying the asset when you need to refer to it later:
- The id attribute is the unique identifier that YouTube assigns to the asset when you create it.
- The tag attribute is a custom identifier that you assign to the asset. The tag should be unique for a given asset type, so that the combination of the type and tag attributes uniquely identifies one asset.
- The path attribute enables you to identify an asset using an XPath.
You can use the tag and path attributes to refer to an asset defined in the current feed. The asset id doesn’t exist until you create the asset, so you can only use it when you update an existing asset.
The subtags of <asset> describe the asset. The available tags differ depending on the asset type. For example, a movie asset has a rating while a sound recording asset has an ISRC number. See Expected metadata fields for specific asset types for details about the tags for each asset type.
Update assets
To update an existing asset, you first need to identify the asset you want to update. There are two ways to identify an existing asset:
- By asset ID (the preferred and more reliable option)This example uses the YouTube-assigned asset ID to uniquely identify the asset. The XML snippet below would update the title of the asset without affecting its other metadata:
<asset type="sound_recording" id="ASSET_ID_1_"> <title>New sound recording title</title> </asset>
- By custom ID and asset typeThis example identifies the asset using an XPath that specifies the asset type and the custom ID that you provided for the asset.
<asset path="/external/asset[@custom_id='internal-id-012'] [@type='sound_recording']" type="sound_recording"> <title>New sound recording title</title> </asset>
Note that the <asset> tag’s type attribute is required, so the asset type must be specified twice – once in the XPath and again in the type attribute value.
You should identify existing assets using their asset IDs whenever possible. YouTube’s feed handler may update the correct asset if you specify the same values for tags that uniquely identify the asset (such as an ISRC, a TMS ID, an ISWC, or a custom ID), but you may wind up creating a second asset instead of updating the original asset. The duplicate asset might eventually be merged with the original, but this might not happen automatically or in a timely matter.
In addition, even if the feed handler does update the proper asset, the update will still not be processed like a typical metadata update:
- If you do not specify an asset ID, then all of the asset’s metadata will be replaced, even if fields are not specified. As such, the only way to submit an incremental data update is to use the id attribute to identify the asset being updated.
- If you update an asset without having provided an asset ID, the status report will identify the Process asset action as anINSERT even though the actions carried out constituted an update.
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. The exception to this rule is the <asset_label> tag, which does append new values.
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.
You can delete the values stored for an optional tag by setting the tag value to an empty string. For example, the XML feed below updates the title of a movie asset and deletes its list of actors.
<asset type="movie" id="ASSET_ID_1_"> <title>This title may not seem new, but it is</title> <actor/> </asset>
For episode and movie assets
Many <asset> subtags (such as <actor>, <director>, and <rating>) actually set values on the associated video object. You’ll want to update the video metadata, not the asset metadata. (You update the asset metadata to make changes that affect rights management rather than providing video information.) SeeUpdate video metadata for more information.
References
Create references
You don’t create a reference for an asset directly using the <reference> tag. You create the reference indirectly by defining a relationship between the asset and a file that contains the audio or video content you want Content ID to use for matching, or a fingerprint of that content (that is, a <file> whose type attribute is video, audio or x-gfp).
<file type="video"> <filename>foo.mpg</filename> </file> <relationship> <item path="/feed/file[1]"/> <related_item path="/external/asset[@id='ASSET_ID_1_']"/> </relationship>
You can also create a reference by defining a relationship between the asset and an existing YouTube video, as long as the video was uploaded to a YouTube user account that is linked to your content owner.
<relationship> <item path="/external/video[@id='VIDEO_ID_1_']"/> <related_item path="/external/asset[@id='ASSET_ID_1_']"/> </relationship>
When you create a reference, YouTube returns a unique reference ID in the status report that details the actions taken while processing the feed. You use the reference ID (and the <reference> tag) to delete, deactivate, or reactivate the reference.
When you create a reference for an asset, you must also specify a match policy for the asset.
Exclude reference content from match consideration
YouTube’s Content ID system uses a reference for an asset as the basis for determining matches and claiming videos. When a reference includes content that you don’t own, you need to exclude that content from consideration when determining matches. For example, a news program might include footage received from other sources. You don’t want to claim videos that match the footage you don’t own.
A <reference_exclusions> tag specifies one or more time intervals in a reference that YouTube should exclude when determining Content ID matches. Each <interval> tag specifies a duration to exclude:
<reference_exclusions> <interval start="0:00" end="0:10"/> <interval start="1:00:20" end="1:00:30"/> </reference_exclusions>
To exclude portions of a reference from consideration during matching, include the <reference_exclusions> tag in your feed and define a relationship that associates the tag with the reference to which it applies. The feed supports two ways to associate the exclusions with a reference:
- To apply the exclusions when you create a reference file, include the <reference_exclusions> element in the relationship that creates the reference. For example:
<file type="video"> <filename>foo.mp4</filename> </file> <reference_exclusions> <interval start="0:00" end="0:10"/> <interval start="1:00:20" end="1:00:30"/> </reference_exclusions> <relationship> <item path="/external/asset[@id='ASSET_ID_1_']"/> <item path="/feed/reference_exclusions[1]"/> <related_item path="/feed/file[1]"/> </relationship>
- To apply the exclusions to an existing reference, define a relationship between the reference and the <reference_exclusions> element. For example:
<reference_exclusions> <interval start="0:00" end="0:10"/> </reference_exclusions> <relationship> <item path="/feed/reference_exclusions[1]"/> <related_item path="/external/reference[@id='REFERENCEID']"/> </relationship>
To remove the exclusions, associate an empty <reference_exclusions> tag with the reference.
<reference_exclusions/> <relationship> <item path="/feed/reference_exclusions[1]"/> <related_item path="/external/reference[@id='REFERENCEID']"/> </relationship>
Delete or deactivate references
Deleting a reference removes the file from the system; deactivating a reference instructs YouTube to stop trying to match the reference against newly uploaded videos but does not remove it. When you delete or deactivate a reference, you also specify whether to release any existing Content ID match claims made based on that reference.
Even though you create a reference indirectly by associating a <file> element with an <asset> element, you delete or deactivate a reference by using the <reference> tag and the reference ID. You set the release_claims attribute to specify whether to release existing claims made based on the reference.
The following samples show how to use the <reference> tag to delete, deactivate, or reactivate a reference.
This sample deletes the reference and releases any automatic match claims that YouTube created because an uploaded video matched the reference being deleted.
<reference action="delete" release_claims="True" id="REFERENCEID" />
This sample instructs YouTube to stop trying to match the reference against newly uploaded videos. As in the previous example, this example releases any automatic match claims that YouTube created because an uploaded video matched the reference being deactivated.
<reference active="False" release_claims="True" id="REFERENCEID" />
This sample instructs YouTube to start trying to match a previously deactivated reference against newly uploaded videos.
<reference active="True" id="REFERENCEID" />
Declare ownership of an asset
An <ownership> tag contains information about the owner of an asset or group of assets. It also contains other ownership data, such as the percentage of the asset that is owned and the territories where the asset is owned. YouTube does not assume that you own every asset that appears in your feed, so you must associate ownership data with each asset to specify the territories where you own it.
You update the ownership of an asset by defining the new ownership rules and associating the new <ownership> element with the asset using a relationship.
Ownership samples
The XML snippet below specifies that you have worldwide ownership of an asset. It includes an empty <ownership> tag. This ownership data must then be associated with an asset, using a relationship to actually assign ownership of the asset to the feed provider.
<ownership/>
If you do not own an asset worldwide, you need to define rules that identify the territories where you do have ownership. You can identify the territories in which you own the asset or the territories in which you don’t own the asset.
Example 1: You own an asset in the United States and Canada.
<ownership> <owner> <rule percentage="100"> <condition restriction="include" type="territory">US CA</condition> </rule> </owner> </ownership>
Example 2: You own an asset everywhere except Japan.
<ownership> <owner> <rule percentage="100"> <condition restriction="exclude" type="territory">JP</condition> </rule> </owner> </ownership>
You remove ownership from an asset by providing a new <ownership> tag with its ownership percentage set to 0 and associating it with the asset using a <relationship> tag. Setting the ownership to 0 removes the asset ownership in all territories.
<feed xmlns="http://www.youtube.com/schemas/cms/2.0"> <!-- remove ownership from asset --> <ownership tag="noownershipww"> <owner> <rule percentage="0"> <condition restriction="exclude" type="territory"/> </rule> </owner> </ownership> <relationship type="associate"> <item path="/external/asset[@id='ASSET_ID']"/> <related_item path="/feed/ownership[@tag='noownershipww']"/> </relationship> </feed>
Ownership for composition assets
For composition assets only, you can also specify that you only own particular publishing rights or that you only own a percentage of an asset in a territory. In addition, you can identify third-party publishers who own a percentage of the asset as well as their publishing rights and ownership territories. This is a common use case for record labels, which often provide ownership information for compositions that they do not administer but that are instead administered by music publishers.
Ownership samples for compositions
The following examples demonstrate how to specify ownership data for compositions that you do not own or administer. In these cases, the <owner> tag uses the type attribute to indicate that the named owner is a publisher that needs to be mapped to a content owner. In addition, the <owner> tag uses the name attribute to specify the publisher’s name.
Example 1: A single publisher owns the composition worldwide.
<ownership> <owner type="publisher" name="XYZ Publishing"> <rule percentage="100"> <condition restriction="exclude" type="territory"/> </rule> </owner> </ownership>
Example 2: Several publishers share ownership of a composition.
This example shows ownership data for a composition that is entirely owned by one publisher in the United States but owned by three different publishers in the rest of the world:
<ownership> <owner type="publisher" name="XYZ Publishing"> <rule percentage="100"> <condition restriction="include" type="territory">US</condition> </rule> </owner> <owner type="publisher" name="XYZ Publishing"> <rule percentage="50"> <condition restriction="exclude" type="territory">US</condition> </rule> </owner> <owner type="publisher" name="ABC Publishing"> <rule percentage="25"> <condition restriction="exclude" type="territory">US</condition> </rule> </owner> <owner type="publisher" name="DEF Publishing"> <rule percentage="25"> <condition restriction="exclude" type="territory">US</condition> </rule> </owner> </ownership>
A common use case is where you partially own and administer a composition, which a third-party publisher also partially owns and administers. In these cases, the <ownership> tag contains multiple <owner> tags, each of which provides information about a different owner of the composition.
The example below demonstrates how to provide ownership for a composition if you own and administer 67 percent of the composition and another publisher owns and administers the other 33 percent of the composition.
<ownership> <!-- The feed provider owns 67 percent of the composition --> <owner> <rule percentage="67"> <condition restriction="exclude" type="territory"/> </rule> </owner> <!-- Another publisher, whose CMS partner name is unknown, owns 33 percent of the composition --> <owner name="Andy the Publisher - Foo" type="publisher"> <rule percentage="33"> <condition restriction="include" type="territory">US CA</condition> </rule> </owner> </ownership>
In this example, you are the first listed owner, and the <owner> tag specifies your content owner name. The other publisher’s content owner name is unknown, so the second <owner> tag’s type attribute is set to publisher rather than the default value (partner), and the name attribute does not need to contain a content owner name but can instead contain any string value. YouTube will then try to determine whether it has a deal in place directly with that publisher or with an administrative publisher or collection society that represents that publisher.
Another common use case for composition ownership is where you own specific publishing rights for the composition or even that you own a percentage of one or more publishing rights. Again, you can also identify owners of other publishing rights or the owners of the remaining percentage of partially owned publishing rights.
The example below indicates that you own sync rights worldwide and also own lyric, mechanical, and performance rights in the United States and Canada. In this example, both <owner> tags identify you.
<ownership> <!-- The feed provider owns sync rights worldwide. --> <owner sync="true"> <rule> <condition restriction="exclude" type="territory"/> </rule> </owner> <!-- The feed provider owns lyric, mechanical, and performance rights in U.S. and Canada. --> <owner lyric="true" mechanical="true" performance="true"> <rule> <condition restriction="include" type="territory">US CA</condition> </rule> </owner> </ownership>
The next example indicates that you own sync rights worldwide and also owns 50 percent of mechanical and performance rights worldwide. It also identifies another publisher that owns the remaining 50 percent of the mechanical and performance rights. In this example, the first two <owner> tags identify you, and the third <owner> tag identifies the other publisher.
<ownership> <!-- The feed provider owns sync rights worldwide. --> <owner sync="true"> <rule> <condition restriction="exclude" type="territory"/> </rule> </owner> <!-- The feed provider owns 50 percent of mechanical rights and performance rights worldwide. --> <owner mechanical="true" performance="true"> <rule percentage="50"> <condition restriction="exclude" type="territory"/> </rule> </owner> <!-- Another publisher owns the other 50 percent of mechanical and performance rights worldwide. --> <owner mechanical="true" performance="true"> <rule percentage="50"> <condition restriction="exclude" type="territory"/> </rule> </owner> </ownership>
Include a sound recording in AudioSwap
YouTube’s AudioSwap program enables users to use audio tracks from participating music artists and record labels as the soundtracks for their videos. The AudioSwap program is designed to benefit artists and record labels while enabling YouTube users to create more exciting, engaging videos.
If you include a sound recording asset in the AudioSwap program, YouTube applies the match policy for the sound recording to the videos of any users who select the recording.
To include a sound recording in AudioSwap:
- Insert the <audioswap> tag in your XML feed. The tag, which does not have any attributes, is a child of the <feed> tag.
- Create a sound recording asset that includes a title, artist, and genre.
- Create a reference for the sound recording.
- Create a relationship that associates the reference file with the asset and the <audioswap> element.
<feed xmlns="http://www.youtube.com/schemas/cms/2.0"> <audioswap/> <asset type="sound_recording" tag="YOUR_ID_HERE"> <title>Title required for AudioSwap</title> <artist>John Smith and the AudioSwap Requirements</artist> <genre>Blues</genre> <!-- more asset metadata --> </asset> <file type="audio" tag="foo.mp3"> <filename>foo.mp3</filename> </file> <relationship> <item path="/feed/file[@tag='foo.mp3']"/> <related_item path="/feed/asset[@tag='YOUR_ID_HERE']"/> <related_item path="/feed/audioswap"/> </relationship> <!-- FP reference (created above) needs a match composite license --> <relationship> <item path="/external/rights_policy[@name='External rights policy']"/> <related_item path="/feed/asset[@tag='YOUR_ID_HERE']"/> </relationship> </feed>
There are two ways to remove a track from the AudioSwap program:
- Update the reference for the sound recording to turn off AudioSwap. To do this, include a <reference> tag in your feed with its action attribute set to audioswap and its active attribute set to false:
<reference action="audioswap" active="false" id="REFERENCEID"/>
- Deactivate the reference for the sound recording. This action automatically removes the recording from the AudioSwap library, but does not impact any claims on existing videos that use the recording.
