Wednesday, December 28, 2011

Understanding Playback Restrictions

Have you ever tried to show a user a YouTube video embedded on your site only to find out that they don’t have access to view it? For instance, if you try to play the video below, it’ll say “This video contains content from test_yt_owner, who has blocked it on copyright grounds.” There are many reasons why video playback can be restricted. The user might be in a country where the video is blocked, or the video’s content owner might have decided to block access to the video from all mobile applications.



While we strive to make YouTube content available everywhere, we believe it's important to give YouTube content owners the ability to control where their videos are viewed, which sometimes means you can't view videos in a certain country or on a certain device.

With enhanced content controls comes increased complexity. The only foolproof way to determine if a user has access to watch a video is to ask them to try watching it. So, if you’re writing an application and you’d like to prevent users from seeing videos that they don’t have the ability to watch, here are a list of things to check:

1. yt:accessControl

Videos that are available for embedding on third-party applications will have the following:

<yt:accesscontrol action='embed' permission='allowed' />
If you’d like to only search for videos that are embeddable, add format=5 to your query.

Just as a video can be embeddable or not, it can also be syndicatable or not:
<yt:accesscontrol action='syndicate' permission='allowed' />
A video that is embeddable but not syndicatable will play on YouTube.com or on other sites that embed the YouTube player, but may not play on devices such as mobile phones or TVs. If you’d like to learn more about retrieving videos suitable for playback on mobile devices, see the developer’s guide.

2. Geo Restrictions

Some videos may be restricted in certain countries. This restriction applies to where the viewer is located, not where your third-party server is located. For instance, if a video is blocked in the US, it will have the following:
<media:restriction type='country'
relationship='deny'>US</media:restriction>
When you make a query, you can add a restriction parameter to filter videos that will not be playable by a client with a specific IP or from a specific country.

3. yt:state

It’s also important to check the yt:state of the video in the API response. Even if yt:accessControl indicates that syndication is allowed, yt:state might override it. For example, a video that has limited syndication would have the following:
<app:control>
<yt:state name='restricted' reasoncode='limitedSyndication'>
Syndication of this video was restricted by its owner.
</yt:state>
</app:control>
You might also see the message, “Syndication of this video was restricted by the content owner.” Hence, even if the uploader allows syndication, the content owner could override that and disallow syndication. For example, this could happen if someone uploads a video that contains a soundtrack that is owned by another content owner.

4. Rentals

Some YouTube videos are rentals. You can tell that they are rentals because they have a media:price tag:
<media:price type='rent' price='1.99' currency='USD' yt:duration='PT2592000S' />
Note that the media:price tag is only included in the response if you use a developer key in the query. If you are building a non-browser based YouTube application where it would be impossible for the user to rent a video, you might want to filter out the rentals. You can do that by passing the parameter paid-content=false.

5. Other Restrictions not Currently Exposed via the API

There are even more subtle restrictions that occasionally come into play. Not all of these are currently queryable via the API. For instance, some videos are only playable on a certain set of domains. As I mentioned above, the only foolproof way to know if a user has access to watch a video is to have them try watching it.

Going back to the video above, you might be wondering why it won’t play. If you look at its video entry:

http://gdata.youtube.com/feeds/api/videos/1kIsylLeHHU?v=2&prettyprint=true

you’ll see that it’s blocked in all countries:
<media:restriction type='country' relationship='deny'>
BD BE BF...
</media:restriction>
Furthermore, both syndication and embedding are disallowed:
<yt:accesscontrol action='embed' permission='denied' />
<yt:accesscontrol action='syndicate' permission='denied' />
Hopefully this short blog post on video playback restrictions will help you write applications that have a better understanding of what videos users can and can’t watch. If you have any questions, you can ask them on our forum.

Cheers,
—Shannon -jj Behrens, YouTube API Team