YouTube API Blog

Watch History Comes to the API

2012-01-24T13:50:00.000-08:00

There’s a new entry in the growing list of video feeds supported by the YouTube Data API: the watch history feed. This feed allows authenticated API users to retrieve their own YouTube viewing histories—retrieving the watch history of any other user is not allowed. The information in this new feed corresponds to the viewing history exposed on the YouTube website.

The feed could enable interesting new functionality in your applications. If your site displays a list of recommended videos for an authenticated user to watch, you might consider excluding those videos that have been already viewed, for instance. Or you might want to include a video that you discover the user has been watching over and over again. Knowing the sorts of videos that a user watches makes it easier for your application to algorithmically suggest other videos that might interest your users.

As with any functionality related to the YouTube API, the best place to ask questions about the new watch history feed is the YouTube API developer forum.

Cheers,
—Jeff Posnick, YouTube API Team

Building Professional Video Sites with YouTube APIs

2011-12-29T14:57:00.000-08:00

Using video on your website can add greater depth and richness for your audience. However, to do encoding, hosting and streaming right it takes some time and skill. If you’re lacking in either, here are some suggestions for sites that make it easy to help you setup video-based websites.

VidCaster is a video content management system, whose goal is to make building a website with video as easy as possible.

VidCaster makes use of custom URLs, video sitemaps, metadata, and thumbnails to integrate well with search engines. They provide lots of features to customize your video site, like uploading a logo, picking a theme and choosing custom colors, and you can even upload custom CSS. Using their video management interface, you can publish, unpublish and delete videos. VidCaster can even distribute the videos from your video site to third-party sites such as YouTube and Twitter, and they can also integrate analytics from third-party sources.

VidCaster uses OAuth2 with the YouTube API to manage the user’s YouTube account, using both SUP (Simple Update Protocol) and polling to make sure a user’s video site is always in sync with their YouTube channel. Companies that use VidCaster include AirBnB, Hackers and Founders, and Dirtcast.

By integrating closely with YouTube’s data API, VidCaster makes it easy for users to take advantage of YouTube’s video service from within their own custom video site.

Moviecom.tv tries to make it easy for businesses to build video sites about their company.

Like VidCaster, Moviecom.tv provides users with a variety of features to customize their video site. They too show videos hosted on YouTube, but their integration with YouTube doesn’t yet include all the features that VidCaster does — for instance, Moviecom.tv can show YouTube videos using the iframe player, but they haven’t yet integrated with YouTube’s data API. This is something they plan on doing early in 2012. Moviecom.tv also touts their mobile application which takes the friction out of recording and uploading video to the right place.

And they’re doing well at it — they were recently named a Red Herring Global 100 Winner. Internet World, City Index, and Staples are all example sites created using their platform:

Companies like VidCaster and Moviecom.tv are a welcome part of the online video ecosystem. As Moviecom.tv CEO Gillian O'Neil once noted, Moviecom.tv isn’t competing with YouTube. By enabling third-party video sites to embed YouTube videos, YouTube isn’t trying to get a bigger piece of the pie. They’re making the pie bigger.

Cheers,
—Shannon -jj Behrens, YouTube API Team

Understanding Playback Restrictions

2011-12-28T13:30:00.000-08:00

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

YouTube Direct Keeps Growing

2011-12-16T14:45:00.000-08:00

YouTube Direct, our open source platform for obtaining and moderating user-generated videos (and photos!), was first announced over two years ago. Since that time, the project has continued to grow, and we’re happy to announce the latest round of additional features.

Most notably, we’ve released a completely rewritten YouTube Direct upload client for iOS devices (seen below). You can find it in its own open source project, and it complements the existing upload client for Android devices. As with the Android client, we see the iOS code as a reference implementation and a starting point for developers who want to build their own branded applications that submit video or photos that could be moderated using YouTube Direct.

The biggest change in the 3.0 release of the YouTube Direct server code has to do with multitenancy. As explained in this guide, YouTube Direct administrators can now deploy their code to App Engine once, and have App Engine serve many different logical instances of YouTube Direct, each with their own submission queues and moderators. While not every YouTube Direct deployment will benefit from this new functionality, we see it being particularly useful for agencies and other organizations that might have multiple individual clients, each interested in keeping track of their own YouTube Direct submissions.

YouTube Direct powers a wide variety of video submission initiatives: sites as diverse as the New York Times’ Reflections on 9/11 project, DrugFree.org’s “You are not alone” and Google Developers’ own “Share your story” page are running by YouTube Direct behind the scenes.

As always, please let us know about any specific issues you encounter with YouTube Direct or either of the mobile clients in the issue trackers associated with each open source project. If you have any general questions about YouTube Direct, we’d be happy to answer them in our YouTube API developer’s forum.

Cheers,
—Jeff Posnick, YouTube API Team

A Friendly Update

2011-12-07T14:19:00.001-08:00

As you might have recently read, there’s an upcoming change that affects any “friends” you might have associated with your YouTube account. Your existing “friend” connections will be automatically converted into Address Book contacts, and when you visit YouTube.com you will be given the option of creating subscriptions to any or all of those accounts.

If you’re a developer, you might ask yourself how this impacts your existing code that uses the YouTube Data API. One specific feed that’s exposed via the API is no longer relevant: the friends activity feed. The users of your application may have converted their old friends to corresponding subscriptions, and in that case you can make use of a new feed in our staging environment that contains activity updates from the accounts you’re subscribed to:

https://gdata.youtube.com/feeds/api/users/default/subtivity

As of right now on our staging server, and around December 14 in production, we will automatically translate requests to the existing friends activity feed’s URL into requests to the new subscriptions activity feed, rather than just returning an empty friends activity feed. While this translation will take place transparently behind the scenes, we encourage all developers who are using the friends activity feed to explicitly update their code to point to the new subscription activity feed as a best practice.

There are also API calls related to YouTube contact management that would accept either an email address (in a <gd:email> element) or a YouTube username (in a <yt:username> element). As a side effect of this migration, you can only use <yt:username> for these calls, which is what the API’s documentation has recommended doing all along. An attempt to use <gd:email> will lead to a HTTP 400 error response.

Thanks for bearing with us through these changes. If you have any questions or concerns, please let us know in our developer forum.

Cheers,
—Jeff Posnick, YouTube API Team

Insight Report Enhancements

2011-10-31T13:40:00.000-07:00

YouTube Insight reports provide video owners with statistics about their viewership above and beyond public view count information. They’re a crucial tool when you want to find out more about the demographic or regional breakdown of your videos’ viewership, or what sites are embedding your videos. The YouTube API has provided a way for developers to retrieve YouTube Insight reports in a comma-separated value format for some time now, but there are some recent additions to the Insight retrieval process that we wanted to highlight.

First, we wanted to mention that the API allows developers to access Insight reports for an entire channel’s worth of videos, not just a single video. The appropriate base URL to use for downloading a channel report can be found when requesting the profile corresponding to the user who’s authenticated with the YouTube API, as described in our developer’s guide. The element looks something like:

It can be identified by the rel='http://gdata.youtube.com/schemas/2007#insight.views' attribute. As with single-video Insight retrieval, these reports are only available to the corresponding owner, so authenticating as the correct user is a must.

Current users of the Insight API know that we previously supported a rather restrictive set of custom date ranges for reports. We’re happy to announce that these restrictions have been relaxed—we now support date ranges that span 31 days (up from 28) and, more significantly, you can specify any arbitrary start date for your report going back to March 1, 2009. Please see our documentation for more information on formatting your custom date range parameters to take advantage of this historical data.

As always, we’re waiting to hear from you in our developer forum with any questions or comments.

Cheers,
—Jeffrey Posnick, YouTube API Team

Upcoming YouTube API Events

2011-10-27T21:14:00.000-07:00

It was a pleasure meeting YouTube developers at the recent GDD, DevFest and GTUG sessions in São Paulo, Buenos Aires, Moscow, Prague, Paris and Warsaw. We would like to let you know that our around-the-world API tour continues and we hope to meet you at one of our upcoming YouTube API presentations. Here is the list of currently planned YouTube sessions:

GDD Tokyo, Nov 1^st: “HTML5, Flash and the Battle for Faster YouTube Cat Videos”
GDD Sydney, Nov 8^th: “Take a sneak peek at YouTube Live Streaming APIs”
DevFest Singapore, Nov 12^th: "Create Magical Apps and Engage Your Audience Using YouTube APIs"
GDD Tel Aviv, Nov 13^th: “HTML5, Flash and the Battle for Faster YouTube Cat Videos”
GDD Berlin, Nov 19^th: “HTML5, Flash and the Battle for Faster YouTube Cat Videos”

We will also be speaking at local GTUGs; for the most up to date information please check the event schedule of a GTUG near you. As always, upcoming event information can be found on our Google Developer Events Calendar available at http://code.google.com/events/.

Cheers,

--Jarek Wilkiewicz, YouTube API Team

More Ways to Find What You’re Looking For

2011-10-13T19:27:00.000-07:00

We’ve got some exciting additions to the list of supported search parameters for YouTube feeds that should make it easier to narrow down your search results to exactly the videos you’re looking for. Each of these search parameters has an accompanying element in a video entry’s metadata, which we’ll cover as well. Here's a quick rundown:

license - This parameter lets you filter search results based on whether they're Creative Commons licensed (license=cc) or use the standard YouTube license (license=youtube). The default behavior is to return videos regardless of their license in search results. The license for a given video entry is reflected in its <media:license> element.

hd - This one lets you request videos that have high-resolution versions available. If you specify hd (no value is needed), all the videos in your search results will be available for playback in at least 720p, and higher resolutions, like 1080p, might be available, too. If you leave the parameter out, then search results won't be filtered at all based on resolution. The <yt:hd> element corresponds to this search parameter.
duration - If you cater to an audience with a short attention span, then this parameter is for you. This parameter lets you filter search results based on video length. To find videos less than 4 minutes long, use duration=short. To find videos that are between 4 and 20 minutes long (inclusive), use duration=medium. Only videos that are longer than 20 minutes will be returning when requesting duration=long. The <yt:duration> element in a video entry provides a video’s exact runtime.
3d - Finally, for those of you living in the future who want to find 3D content on YouTube, this aptly-named parameter is for you. Adding 3d (no value is needed) to your searches will ensure that all videos you get back are available for viewing in 3D. Videos that are available in 3D will have a <yt:threed> element in them, and that element will contain more detail about the nature of the 3D content in the given video.

Putting it all together, let’s say you want to use the API to find Creative Commons-licensed 3D YouTube videos that are available in resolutions of 720p and above and are longer than 20 minutes.The following request URL will return a feed of such videos:

https://gdata.youtube.com/feeds/api/videos?prettyprint=true&v=2&license=cc&hd&duration=long&3d

As always, if you have any questions or comments, please let us know in our developer forum.

Cheers,
—Jeff Posnick, YouTube API Team

Introducing Google Account support and YouTube API v2.1

2011-10-07T15:46:00.000-07:00

Update (December 2011): The YouTube API now supports associating an unlinked Google Account with a YouTube channel as well as providing username suggestions.

Authenticated access to YouTube APIs lets your app offer many features that are unavailable to logged-out users. By authenticating user actions, your app can allow users to manage subscriptions, create playlists, and upload videos. Until recently, users could only perform any of these operations if they had YouTube accounts. (A YouTube account provides a user with a YouTube channel.)

We are pleased to announce that we have also started to give Google Account holders who don’t already have YouTube channels access to certain YouTube features on YouTube.com and in the YouTube API. We call these unlinked Google Accounts since they haven’t already been linked to a YouTube channel. For example, a user with a Gmail account or an Android device is certain to have a Google Account but may not have already linked that account to a YouTube channel.

What this means for your application is that with a few relatively simple changes, you should be able to allow authenticated access for users who have unlinked Google Accounts. Thus, those users will be able to log in to YouTube without having to create a YouTube username.

In a moment, we’ll dive into the details of how to use the API with unlinked Google Accounts and also offer a few user experience recommendations for your YouTube API application. First, though, a quick note about the new minor YouTube API revision that we’re introducing.

Say "Hello!" to YouTube API v2.1

When designing this feature, we decided to take a conservative approach toward backward compatibility. The set of write operations supported for Google Accounts is currently a subset of API operations available to YouTube account holders. Rather than expose existing applications to accounts with potentially restricted functionality, we’re explicitly requiring that an application prepared to handle unlinked Google Accounts tells us so by using the API version 2.1, a new, minor version of the API. Our documentation explains that you can specify an API version by appending v=2.1 to the API request URI or by using the GData-Version: 2.1 request header.

HTTP response codes for authenticated operations

API v2.0 supports all authenticated operations for users with YouTube accounts, which could also be called linked Google Accounts, but doesn’t support any authenticated operations for unlinked Google Accounts. If the authentication token for a v2.0 API request identifies an unlinked Google Account, the API will return a 401 NoLinkedYouTubeAccount error.

In API v2.1, however, a number of operations that require authentication are supported for users with unlinked Google Accounts, and the API will return a 200 response code for those operations. For operations that aren’t supported for unlinked Google Accounts in v2.1, the API will return an HTTP 403 Forbidden error with a youtube_signup_required error code.

The table below shows how API v2.1 changes response codes when different types of users try to execute operations that require authentication:

	API v2	API v2.1
YouTube Account	200 OK	200 OK
Unlinked Google Account	401 NoLinkedYouTubeAccount	200 OK or 403 Forbidden youtube_signup_required

Handling the youtube_signup_required error

We do not recommend that you try to modify your application to provide a different experience for users with YouTube accounts than for unlinked Google Accounts. That approach would require you to constantly update your application as YouTube expands the list of features that we support for unlinked Google Accounts.

Instead, we recommend that you prepare your application to gracefully handle the youtube_signup_required error, preferably by associating the unlinked Google Account with a YouTube channel using the API, or presenting an option for the user to navigate to https://www.youtube.com/create_channel. If you are building a mobile application, you can bypass a redirect by using https://m.youtube.com/create_channel instead. The API documentation lists the operations that are and are not currently supported for unlinked Google Account holders.

The XML below shows a sample youtube_signup_required error:

<errors> 
  <error>
    <domain>yt:service</domain>
    <code>youtube_signup_required</code> 
  </error>
</errors>

User profiles for unlinked Google Account holders

A user profile entry for a user with an unlinked Google Account differs from a user profile entry for a user with a YouTube account in two ways:

An entry for an unlinked Google Account holder contains a <yt:incomplete> tag. (This tag is not present if the user already has a YouTube channel.) It is useful if you choose to disregard our advice about the youtube_signup_required error and modify your application to provide a different user experience for users with unlinked Google Accounts.
An entry for an unlinked Google Account holder contains only a few tags as those users can not customize their profile data without first creating a YouTube channel. The <entry> tag definition lists the different tags that may appear in a profile entry depending on whether the user has a YouTube account or an unlinked Google Account.

Displaying an email address for unlinked Google Account holders

In addition to handling the youtube_signup_required error, your application should also be prepared to display an email address for users with unlinked Google Accounts.

In Closing

If you have reached this point in the blog post, thanks for being a dedicated reader. We recognize that unlinked Google Accounts do introduce a certain level of complexity, but, at the same time, they can also open your application to a much larger audience of users who use Google services but haven’t created YouTube channels yet.

We also want to note that v2.1 does not deprecate v2.0 since it is a minor revision. Going forward, new features unrelated to unlinked Google Accounts will be added to both v2.0 and v2.1 but not to the (deprecated) v1.0 of the API.

Version 2.1 of the API is now available for testing on stage.gdata.youtube.com, and will be released to production in mid-October.

Cheers,

—Jarek Wilkiewicz, YouTube API Team

Support for the Watch Later List

2011-10-05T11:44:00.000-07:00

YouTube’s Watch Later list is the perfect way to keep track of interesting videos you come across but don’t have time to watch at the moment. Since rolling out that feature on the YouTube website and the embedded players, developers have been asking for ways to interact with the Watch Later list via the YouTube Data API. We’re happy to announce that this is now possible.

As explained in our documentation, the YouTube Data API treats the Watch Later list like a playlist, and the normal playlist operations (additions, retrievals, modifications) can all be performed on the Watch Later list. While every YouTube user has their own Watch Later list, it’s important to keep in mind that by default it’s a private playlist, so it will not normally be accessible unless you’re making an authenticated request as the list’s owner.

If you have any questions about using the Data API to work with the Watch Later list, please let us know in our developer forum.

Cheers,
—Jeff Posnick, YouTube API Team

YouTube API and the News

2011-09-28T12:23:00.000-07:00

If you love to follow the news as much as you love to code, then Hacks/Hackers, an international organization that sits at the nexus of journalism and technology, is for you. Its mission is to create a network of journalists (“hacks”) and technologists (“hackers”) to rethink the future of news and information. Recently, YouTube and LinkTV hosted a Hacks/Hackers meetup at Google’s San Francisco office. Together with four developer partners, we demoed web applications used by reporters and built using the YouTube API. The presentation started with a YouTube API overview, followed by demos of the following:

YouTube Direct is an open source, user-generated content video submission and moderation platform.
Storyful was founded by journalists to discover the smartest conversations about world events and raise up the authentic voices on the big stories.
Storify lets users make stories using social media. With Storify you can drag-and-drop tweets, YouTube videos, Flickr images, Facebook updates, etc. and add your own narrative to tell a story.
Shortform is a new social entertainment medium, delivering continuous channels containing the best videos from anywhere on the web, curated by our community of video DJs (VJs).
GoAnimate was founded to provide an outlet for everyone's creative ideas. In just 10 minutes, you can make fun animated videos without having to draw.
Link TV recently launched Link News, an international news website that sifts through YouTube's library of news content to deliver breaking news and hidden stories to a wider audience.

We would like to share the video recording of the event with you so that you can learn more. If you want to discover more about Hacks/Hackers, you can find the list of local chapters here.

Cheers,
—Jarek Wilkiewicz, YouTube API Team

Getting 3D Content on YouTube

2011-09-08T22:47:00.000-07:00

Over the last few months, we've been steadily rolling out features for YouTube 3D. Early this year, we announced support for the LG Optimus 3D and NVIDIA 3D Vision, and this month we announced support for Samsung 3D TVs. And we'll keep rolling out to more platforms to make it easier for everyone to get access to user-generated 3D content.

Many readers have been asking how to upload content. 3D uploads to YouTube will work across all supported devices, from red/blue glasses to the latest 3D televisions.

There are two ways to upload content to YouTube in 3D. If you're just uploading one or two videos, upload content in any supported format and then edit the video settings to tell us that it's 3D. From a video's watch page, select "edit info", then "3D Video". This will only work on videos you've uploaded yourself.

If you're using the API to upload 3D videos, you'll want to format your video in a certain way. YouTube supports automatic detection of 3D content with certain file formats. If you upload with a format that supports automatic detection, we'll automatically set the correct settings so that your video shows up automatically in 3D and shows up properly on phones, TVs, and PCs.

In both cases, YouTube requires that content be uploaded in Side by Side L/R with each frame squashed 50% and preferably with a 16:9 aspect ratio. The following formats are automatically detected when uploaded:

WebM with the StereoMode setting set to STEREOMODE_TYPE_LEFT_RIGHT. Note that other modes, including alternate track, are not supported.
H264 AVC with Supplementary Enhancement Information, Frame Packing Arrangement set. If you are using x264, the argument --frame-packing=3 will set this correctly. In Handbrake you can set this in "x264 Advanced Option String".

Be sure to get the squashing and positioning exactly correct. 3D content won't look right if video formatting is off by even a pixel or two.

We're excited to see what you'll show us! Here's an idea from a favorite webcomic of ours.

Cheers,

—Jonathan Huang, YouTube 3D Product Manager

P.S.—We recently worked with some folks to help them get 3D Mars footage from 1979 restored from the Viking landers. Check it out!

Auth Tokens & Unlinked YouTube Accounts

2011-08-25T12:46:00.000-07:00

Dedicated readers of this blog will remember our post from a few months back entitled “ClientLogin #FAIL”. In it, we laid out a number of scenarios in which attempts to use ClientLogin authentication would result in an error (and urged developers to move off of ClientLogin in general). The first failure scenario involved users whose YouTube account is not linked to a Google Account. Fortunately, the number of YouTube accounts in that unlinked state has decreased greatly over the past few months, so failures of that sort with ClientLogin are not as common now.

There’s another related failure scenario that we want to bring to everyone’s attention, this time involving both AuthSub and OAuth (collectively referred to here as “auth”) tokens. Starting on Wednesday, August 31, if your code attempts to use an auth token that was generated for an unlinked YouTube account, your request will fail with an HTTP 401 response code indicating that the token is invalid.

It’s important to note that what determines when the token is invalid is whether the YouTube account was linked at the time the initial auth token was generated. For example, if your code generated the auth token for an unlinked YouTube account on March 1, and then the user linked their YouTube and Google accounts on March 2, the auth token will still be considered invalid.

On March 31 we started to enforce the need to have a linked Google Account as part of the AuthSub and OAuth login flow, meaning that it was impossible to generate an auth token for an unlinked YouTube account after that date. So this change can only affect auth tokens generated before March 31 of this year.

While auth tokens normally don’t expire, users have the option of manually revoking them. If your code uses a revoked token, you’ll also get back an HTTP 401 response. If you’re using a client library, it will generate an exception to indicate the failure. It’s a best practice to make sure that your code handles invalid token errors by asking your user to go through the AuthSub or OAuth login flow again, storing the new token value and discarding the old one in the process.

If you have any questions about YouTube API authentication, please let us know in our developer forum.

Cheers,
—Jeff Posnick, YouTube API Team

The New CodeIgniter PHP Client Library

2011-08-23T07:04:00.000-07:00

While the YouTube Data API’s RESTful nature means that talking to YouTube is as easy as making an HTTP request, using a client library is a great way to improve your YouTube Data API productivity and write code using your preferred language’s native features. PHP developers using the Zend framework have had access to a client library for a while now, and that library continues to be a supported way of using the YouTube API. But if you’re a PHP developer using the CodeIgniter framework, you’ll be happy to hear that there’s now an alternative client library available just for you.

A third-party developer, Jim Saunders, has developed a YouTube Data API library specifically for the CodeIgniter framework. You download the library on GitHub, and read the article he’s written to find out how to get started with some sample code.

While Jim wrote and still maintains the library, please feel free to ask any questions about the YouTube API in general in our developer forum!

Cheers,
—Jeff Posnick, YouTube API Team

Coming Soon: The Dark Player for Embeds

2011-08-05T22:04:00.000-07:00

You may have noticed that we’ve changed the look of the player on YouTube. You may even have noticed that we’ve been experimenting with changing the look of embedded players too. Coming up on August 10, all embeds will automatically be updated to the new "dark player":

Although we’re very excited about this change, which comes after months of design, research, and experimentation, we realize that some embedders would prefer a lighter color to match a lighter webpage, so we’re also announcing a few other themes that we’ll be making available. We also realize that some embedders would prefer something more mild than our use of red, so we’re happy to introduce a "desaturated" color option without any bright colors at all. (Note: Using the desaturated color disables the modestbranding option.)

To pick an alternate theme, pass in values for the "theme" and "color" player parameters. For instance, if you’d like to keep the traditional colors, you can pass parameters such as:

<iframe width="560" height="349"
  src="http://www.youtube.com/embed/9h1swNWgP8Q?theme=light&color=red"
  frameborder="0" allowfullscreen></iframe>

Here are all the new themes, including the new default:

If you have any questions about this change, you can ask them on our forum.

Cheers,
—Shannon -jj Behrens, YouTube API Team

YouTube @ Google I/O: Your Game + YouTube = Instant Community

2011-07-28T13:01:00.001-07:00

If you have ever wondered how to generate excitement around your video game using YouTube, we would like to share a few hints from the makers of Call of Duty: Black Ops. They included the ability to upload gameplay video clips directly from the game to YouTube using the YouTube upload APIs. This fourth, and final installment of Google I/O 2011 session videos covers a game-focused presentation entitled “Your Game + YouTube = Instant Community” by Jarek Wilkiewicz from the YouTube Developer Relations team, Doug Muir, Technical Director from Activision, Cliff Samaniego and Kenji Arai from the YouTube Strategic Partner Management team.

The presentation gives an overview of YouTube platform features relevant to the gaming audience and highlights the benefits that integrating gameplay video uploads can bring into your title. The session also covers the good, the bad and the ugly of the integration project that Black Ops team had undertaken on a compressed timeframe. Finally, we show a couple of examples of user-generated gameplay video clips from Blacks Ops.

Since hindsight is 20/20, especially as it relates to software projects, the presentation also features a small demo of OAuth 2.0 for Devices authorization flow. OAuth 2.0 for Devices streamlines authorization process for embedded devices such as gaming consoles. While the technology was not yet released at the time of Activision’s integration, it is now in Beta. Another example of technology not initially introduced in the integration is WebM/VP8 encoding. If you watch the video you will learn about why the video clips were restricted in size and how WebM helps with solving this issue.

The full video of the session is embedded below, and you can find the slides here.

Cheers,

—Jarek Wilkiewicz, YouTube API Team

Say Hello to the New Playlist Player

2011-07-14T18:19:00.000-07:00

While the YouTube embedded single-video player has seen a number of improvements in the past few months, the embedded playlist player has lagged behind—until now. We’re happy to introduce a completely rewritten embedded playlist players, ready for inclusion on any of your web pages that needs to display a series of videos in the same player. The new embedded playlist player has a user interface that should be familiar to anyone using our current single-video player. Take a look at the example below:

Any developer can try out the new playlist player right now by appending the version=3 URL query parameter to the URL they’re currently using for an embedded playlist player. For example, if you’re currently specifying http://www.youtube.com/p/E46798C874B35B7F?fs=1 in your <object>/<embed> tags, using http://www.youtube.com/p/E46798C874B35B7F?fs=1&version=3 will play back the same playlist in the new player.

Alternatively, you can just wait until next week. We plan on making the new version of the embedded playlist player the default on July 20, and at that point existing URLs will automatically trigger the new player.

We do encourage all developers to take the opportunity to test the new player with an explicit version=3 in advance of that change—while we don’t anticipate any issues with using the new version, if you do notice anything that is amiss, you can let us know in the YouTube API Google Group.

Cheers,
—Jeff Posnick, YouTube API Team

Introducing YouTube.com/create

2011-07-01T10:42:00.000-07:00

YouTube.com/create is a platform for third-party applications that enable users to create videos. The idea is simple. The third-party application runs in an HTML iframe on YouTube. The user creates a video with the application, and then the application uploads the video to YouTube for the user to watch and share.

Many different types of applications are already listed at YouTube.com/create. One True Media is a simple video editor. GoAnimate lets you create custom animations. Stupeflix lets you mix pictures, videos, maps, text, and music into a story. Xtranormal lets you turn anything you type into a fully-animated CG movie. Who knows what other developers have in store for YouTube.com/create?

Here’s one example of a company that decided to integrate with YouTube.com/create and experienced a signficant growth in traffic:

To list your application on YouTube.com/create, you’ll need the following:

The name of your application (max 60 characters).
A description of your application (max 50 words).
A 120x120 icon. The icon will display with rounded corners.
A tutorial video (hosted on YouTube).

The application itself must meet the following requirements:

It must support Google federated login using OpenID.
It must post the resulting video to YouTube. The application should upload the video on behalf of the user using OAuth2 or AuthSub.
It must provide branding within the user interface if the user is required to upload assets (to make it clear that the upload is going to the third-party application, not to YouTube).
It must not show ads within the iframe. However, the freemium model is acceptable, providing the base level of functionality is useful.

The application must run within the context of a 960px-wide iframe that will display on YouTube. The iframe does not limit the vertical space that your application occupies. For best appearance, your application should have a white background.

When you are ready to submit your application for inclusion on YouTube.com/create, submit it to the YouTube Project Gallery using the hashtag #create, and YouTube will contact you via email.

For more information about integrating with YouTube’s API, check out our developer documentation and join us on our mailing list!

Cheers,
—Shannon -jj Behrens, YouTube API Team

Sunsetting the Custom Player

2011-06-22T12:07:00.000-07:00

YouTube previously offered a specialized way of embedding playlists (as well as uploads and favorites feeds) for playback on third party sites in a customizable interface—we called this the Custom Player. While the Custom Player had its fans, it never saw a great deal of usage, and we recently removed support for the creation of new Custom Players. If you’ve already created a Custom Player and have it embedded on your site it should continue to work as-is; the only thing that has changed is that new Custom Players cannot be created.

One common concern is that owners cannot update the videos featured in existing Custom Players. We recommend that you update the associated playlist to reflect the videos that you would like to feature in the Custom Player, or embed a new playlist.

While we will not allow for the creation of new custom players at this time, similar functionality is available through creating embedded playlists, which can be accessed by visiting http://youtube.com/my_playlists, clicking Share, and then using the embed code given there.

We apologize that taking away the ability to create new Custom Players caught anyone off guard. Stay tuned to this blog for upcoming announcements about modern alternatives to the Custom Player—we’ve got some exciting things in store!

Cheers,
—David Boyle, YouTube Team

The next step in embedded videos: HD preview images and a logoless option

2011-06-13T12:54:00.000-07:00

(Cross-posted from The Official YouTube Blog.)

It may be hard to imagine but YouTube’s video preview images represent to many the ultimate deciding factor as to whether or not they watch a video. If a preview image looks interesting, it can mean the difference between someone pressing the play button. In addition, your site and the videos on it represent to you polished masterpieces. Yet, your videos’ preview images can appear lower in quality, and sometimes you don't want a logo in your player. So today we're rolling out new features for both situations: HD preview images and the option to remove the logo from your player.

HD preview images
Video resolutions have been increasing across YouTube, and the sizes of your embedded players are bigger than ever. But until now, video preview images in today’s larger players (e.g. the image that appears before you click “Play”) haven’t kept up with your high-quality and larger videos.

Any new video uploaded to the site in a resolution of 480p or higher will have an HD preview image wherever the player is embedded. The difference is even more striking with larger embeds (which don’t fit on this blog), so try it out yourself and see what we’re talking about. Here’s an example:

Before:

Now:

We’ll also automatically give HD preview images to older videos in the next few weeks, as long as they’re 480p or larger.

A note for partners, if you’ve uploaded a custom preview image for your video, you’ll need to re-upload a new one for your videos in order to upgrade it to HD (1920 x 1080px, 2MB max).

Logoless player
Many of you have asked us for a version of the YouTube player without a YouTube logo, so the video plays without any branding nearby. We’ve now added a simple option to do it. At the end of the video URL in your embed code, just add the code ?modestbranding=1 and the player will show without the YouTube logo in the control bar. Note that a small “YouTube” text label will still show up in the upper-right corner of a paused video when you hover over the player. We’ve published the full list of the player’s possible parameters, and here’s an example:

We hope these features help you show your videos the way you want them to be seen.

Kevin Wilson, Software Engineer, recently watched “I'm Yours (ukulele)” and Ravi Kanodia, Software Engineer, recently watched “Candy BBQ - Epic Meal Time.”

YouTube @ Google I/O: API Bootcamp

2011-06-13T12:34:00.000-07:00

There was more to Google I/O 2011 than formal presentations—Google I/O BootCamp was a day-long developer event geared towards providing beginning-level content to newer developers. Two engineers who work on the YouTube Data API, Raul Furnică and Günther Noack, participated in a BootCamp session that introduced the YouTube Data API and covered examples of how it could be used to discover and curate YouTube content.

If you’re just getting started with the YouTube Data API and want an overview of what it offers, or if you have a particular interest developing apps for content curation, please do check out the session video embedded below!

Cheers,
—Jeff Posnick, YouTube API Team

YouTube @ Google I/O: All About Captioning

2011-06-03T08:17:00.000-07:00

Google I/O 2011 may be over, but we’re continuing our series of blog posts recapping the great developer material covered at the event. We previously covered our talk on the iframe Player API, and the next presentation we’re highlighting is “The YouTube Caption API, Speech Recognition, and WebVTT captions for HTML5”.

The session features Jeff Posnick from the YouTube Developer Relations team, Naomi Black from the Accessibility Engineering team, and Cynthia Boedihardjo, a Live Stream Program Manager. As the session’s title suggests, a number of different topics were covered, with video accessibility and captions the common theme throughout.

The material covering the YouTube Captions API, including a sample application that demonstrates using the API from Python, will be of particular interest to the YouTube API developer community. The talk also includes some early WebKit demos of WebVTT implementations for the <track> element in HTML5 as well as more information and stats about the Live Caption gadget launched at Google I/O. The gadget provides captions alongside streaming video.

The full video of the session is embedded below, and the slides from the talk are available as well.

Cheers,
—Jeff Posnick, YouTube API Team

YouTube @ Google I/O: The iframe Player API

2011-05-31T12:22:00.000-07:00

Google I/O 2011 may be over, but all the great developer information lives on! We want to start our recap of YouTube-related I/O activities by highlighting our developer presentation entitled “YouTube’s iframe Player: The Future of Embedding”.
The session features Jeff Posnick and Jarek Wilkiewicz from the YouTube Developer Relations team, and Greg Schechter, one of the engineers who works on the iframe Player and its API. Topics covered include the development of the iframe Player, challenges related to exposing an API on an iframe element, differences between the ActionScript 3 Player API and the iframe Player API, and real-world example applications that use the new API.

The full video of the session is embedded below (using the iframe Player, of course), and the slides from the talk are available if you’d prefer to read along with the presentation. Be sure to check out the sample web application (along with its source) that illustrates iframe Player API usage as well!

Cheers,
—Jeff Posnick, YouTube API Team

Making stories with social media and YouTube videos

2011-05-11T15:38:00.000-07:00

By Xavier Damman, co-founder of Storify

(Cross-posted from the Google Code blog, where the post is part of Who's at Google I/O, a series of guest blog posts written by developers who are appearing in the Developer Sandbox at Google I/O.)

Storify is part of the Google I/O Sandbox. Please come say hi to find out more about how you can leverage our APIs so your users can remix your content to create stories to share on social networks.

Storify provides a super simple drag and drop user experience to create stories using elements from the web: tweets, YouTube videos, Facebook updates, SlideShare presentations, audioboo files, and so on (see Storify in action here). This post explains how we incorporate videos in Storify using YouTube Data API and Player API. All the code snippets are in JavaScript. In fact, our full stack is in JavaScript: we use NodeJS and MongoDB which we think is an über cool mix.

The source of the source

To create a Storify source, we need to be able to get a feed of results using JSONp (basically JSON with a callback function so that you can do cross domain calls; from the YouTube API perspective this is the JSON-C format). For YouTube, the main search API endpoint looks like this:

request: function(formdata) {
   return {
      'url' : 'http://gdata.youtube.com/feeds/api/videos',
      'params': {
         'v'  : 2,
         'max-results' : 20,
         'alt'  : 'jsonc',
         'q'  : formdata.keywords
       }
    };
  }

This function is called when the user clicks Submit in the search tab of the YouTube source in the Storify Editor. The main controller executes the request and sends the JSON result to the results method, which returns an array of normalized results:

results: function(json) {
 
  if (json.data && json.data.totalItems && json.data.totalItems == 0) {
    throw "No results found";
    }
  
  var videos = json.data.items;
  var results_array = [];

  for (var i = 0; i < videos.length; i++) {
        var normalizedResult = {
           permalink   : 'http://www.youtube.com/watch?v='+videos[i].id,
           source  : 'youtube',
           elementClass : 'video',
           metadata  : videos[i],
           thumbnail   : videos[i].thumbnail.sqDefault,
           title: videos[i].title,
           description  : videos[i].description.substr(0,140),
           author: {username: videos[i].uploader },
           created_at  : videos[i].uploaded,
           oembed: {html: '<iframe id="youtube-'+videos[i].id+'" type="text/html" width="360" height="294" src="http://www.youtube.com/embed/'+videos[i].id+'?enablejsapi=1&origin=storify.com" frameborder="0">'
           }};
     
           results_array.push(normalizedResult);
  }
  return results_array;
}

Thanks to this normalized representation of a story element – in this case, it’s a video object – we can build an object-oriented story as the user drags and drops any of these elements. This technique has multiple benefits: we maintain attribution to the original content creator, and we can track the content as it spreads across the web (how many times it has been seen and from where).

The story element also provides the oEmbed HTML code. This is used to render the video embed when the video is added to the story. For that purpose we use the YouTube Player API with their new iframe embed.

Story.json

We have a very simple way to get any data out of our platform: just append .json to any storify.com URL and you get the JSON representation of the content of that page.

For example:

http://storify.com/latest.json?topic=googleio returns the latest stories with the tag #googleio
http://storify.com/xdamman.json returns the user object and the user’s latest stories.
http://storify.com/xdamman/googleio.json returns the story object of the story “GoogleIO” of xdamman. You can use this to easily filter the elements of the story to retrieve only the YouTube videos of a given story and create a fancy HTML5 visualization (see the slideshow or this version). You can see some open source examples at http://github.com/storify/templates.

Add the Storify Editor to your site

The Storify Editor can be called in an iframe. You just need to provide a callback parameter, like this: http://storify.com/story/new?callback=yoursiteurlcallback. The user will be asked to authenticate with Twitter and then will be able to create a new story. Once the user is done and hits “Publish”, we call you back, passing you the permalink of the new story created:
yoursiteurlcallback?permalink=storyPermalink.

You can then either fetch the JSON of the story by appending “.json” to the storyPermalink or you can embed the story by loading <script src=”storyPermalink.js”></script>. This is a great way to provide your community with a way to create stories right from your site.

This is only the start. We plan to open a Sources API so that any developer can build a source for any service. Please come see us at our booth at the Google I/O Sandbox if you’re interested in joining our developer community. And check out this article in the New York Times to learn more.

Come see Storify in the Developer Sandbox at Google I/O on May 10-11.

Xavier Damman is the co-founder of Storify. He is also the founder of HackDemocracy, a community of hackers who want to improve our democracies using technology.

Reinventing News Video with Knight, Mozilla, and the YouTube API

2011-05-05T13:00:00.000-07:00

(This is a guest blog post by Ben Moskowitz of the Mozilla Foundation.)

Over the next few weeks, the Knight Foundation and Mozilla are running a series of news innovation challenges. The goal: get the world's smartest hackers thinking about how news organizations can harness the open web.

The first challenge, which runs through Sunday, May 8th, is all about video. This is a great opportunity to be creative with the YouTube APIs—if you have a big, ambitious idea, you could get support from Knight and Mozilla to make it real.

Check out the brief:

Video is a central part of many people's daily news experience. But despite all the opportunity offered by the open web (social, linkable, real-time, dynamic), most online video is still stuck in a boring embedded box, like "TV on a web page." This offers little in the way of context or opportunities for viewers to engage more deeply.

If you're reading this blog, you're probably interested in hacking web video. The challenge is: how can web video bring innovation to the news biz?

How would you take advantage of modern JavaScript, advanced HTML5 features, and the richness of web service APIs like YouTube's? How would you make use of the millions of connected YouTubers who upload 35 hours of video per minute? What are the news video opportunities that are unique to the web?

The YouTube API blog is rife with possibility: check out some posts on curation, remix, and the YouTube chromeless player. Read up on YouTube Direct, a cool open source app, or visit the YouTube API project gallery. While you're at it, check out popcorn.js, the HTML5 video framework (now including a wrapper for the YouTube Flash player!)

What kinds of innovations would you bring to the newsroom? How would you transform news video?

Head over to the challenge site and enter your idea. Submit a short abstract, a napkin sketch, or however you choose to best express yourself. By entering your idea, you'll be eligible to take part in an online learning lab with famous hackers like Christian Heilmann, Burt Herman, Aza Raskin, John Resig. And if your idea rocks, Knight and Mozilla will fly you to Berlin for an in-person development sprint, to take your idea from napkin sketch to prototype to deployment.

Finally: five participants will be invited to become Knight-Mozilla news technology fellows. Fellowships are paid positions inside newsrooms at the BBC, Boston.com, The Guardian, Al Jazeera English, and Zeit Online, to build world class web apps for a large audience.

The challenge ends May 8th, so hurry and study up on the YouTube APIs. For Sunday’s deadline, all you need is a great idea, a rough sketch. If you proceed to the next phases, there will be plenty of time and support to further prototype and build out your idea. Mostly, we want to get to know you through this challenge. Happy hacking!