File Under: APIs, Multimedia

YouTube Tutorial Lesson 1 – The Player API

Dozens of video sharing sites may offer streaming video that plays back in higher quality than YouTube, but if you want eyeballs (and millions of them), then Google’s monstrously popular YouTube is the place to be.

For a long time, all you could do with YouTube as a web publisher was embed its hosted videos on your site. But thanks to a recent overhaul to the YouTube API, you can now do much more.

YouTube recently unveiled a new and improved Player API that allows developers to do things like re-skin the video player or create their own custom controls. In fact, if your scripting chops are up for it, you could build your own uploading interface for YouTube and then simultaneously post videos to YouTube and your site with one click of the mouse.

There are actually two different YouTube APIs — there’s the aforementioned Player API for skinning your embedded players and adding custom controls, plus the Data API for grabbing information about movies. Each API has a number of different functions.

We’re going to take a look at both the Data API and Player API on Webmonkey in this tutorial, but we’ll start with the Player API since it’s a little bit simpler to interact with.

Note: Many of the Player API’s new functions can be accessed through both JavaScript and ActionScript. We’ll take a look at the JavaScript controls, but the ActionScript API is very similar, so if you prefer ActionScript, you can convert this code without too much trouble.


Contents

  1. Getting Started
  2. Using SWFObject
  3. Controlling the Player with JavaScript
  4. Conclusion

Getting Started

When it come to embedding Flash, YouTube recommends using SWFObject, which is a JavaScript library for embedding Flash movies. Grab a copy of SWFObject and put it in your public web folder. Now include this line at the top of your page where you want to do your embedding:

<script type="text/javascript" src="/path/to/swfobject.js"></script>

Now let’s embed a movie and start playing with the new API.

Using SWFObject

If you’ve never encountered SWFObject, you’re in for a treat. SWFObject greatly simplifies the process of embedding Flash movies, taking care of various cross-browser issues and other problems.

All you need to do is define a tag for SWFObject to replace with a Flash movie. Here’s some example HTML code you can use for this tutorial:

<body>

<div id="ytplayer">



<p>You will need Flash 8 or better to view this content.</p>

</div>





<script type="text/javascript">

	var params = { allowScriptAccess: "always" };

	swfobject.embedSWF(

		"http://www.youtube.com/v/tFI7JAybF6E&enablejsapi=1&playerapiid=ytplayer", "ytplayer", "425", "365", "8", null, null, params);

</script>

</body>




OK, here’s how it works.

First of all we create a div container to hold our embedded movie. If the user doesn’t have Flash 8 or better, they’ll see our plain paragraph text (note that SWFObject offers far more sophisticated ways of handling this, like auto-updating the users Flash player. See the documentation for full details).

The next step is to write the JavaScript and embed the movie. We’ve defined a params argument to tell Flash that it’s OK to let the YouTube domain load scripts, and then we call the embedSWF function.

The parameters passed to embedSWF include the location of the .swf file, the id of the tag we want to replace, the width and height of the video, the Flash Player version to require (the YouTube API requires version 8 or above) two parameters we’re not using and finally our params value.

Now let’s take a look at that URL was passed to embedSWF. For the most part, it’s an ordinary YouTube URL. But notice we’ve added two additional bits of data. We’ve told YouTube that we want to use the JavaScript API and we’ve given our player an API name.

The API name — in this case, “ytplayer” — is important because if you ever embed two movies on the same page and want to control them separately, each one needs to have a unique name.


Controlling the Player with JavaScript

If you load the above code in a browser, you’ll notice that you just Rickrolled yourself. Face! But more importantly, you’ll notice that the movie file doesn’t look any different than a normal embedded movie.

Let’s start adding some outside controls to our page so you can see how the Player API works. Go ahead and paste this function into your HTML, just below the SWFObject function:

function play() {

  if (ytplayer) {

	ytplayer.playVideo();

  }

}



function pause() {

  if (ytplayer) {

	ytplayer.pauseVideo();

  }

}



function stop() {

  if (ytplayer) {

	ytplayer.stopVideo();

  }

}




Now just below the div element that we’re replacing, add this HTML code:

 <a href="javascript:void(0);" onclick="play();">Play</a>

 <a href="javascript:void(0);" onclick="pause();">Pause</a>

 <a href="javascript:void(0);" onclick="stop();">Stop</a>




If you reload the page you’ll see that our HTML links can now control the player.

Now you might be thinking, what’s the point? After all the player already has controls. But if you’re trying to make embedded movies more closely match the look and feel of your site’s design, these tools make it easy to create your own controls.

So how to get rid of YouTube’s controls? Well, to do that we’ll need to use the “chromeless” player.

To use the chromeless player, our URL parameter inside the embedSWF function becomes something like:

http://www.youtube.com/apiplayer?enablejsapi=1&playerapiid=ytplayer


Notice that we haven’t passed an actual movie id in this case. To do that with the chromeless player, we have to use the loadNewVideo function. So add this code below our other JavaScript functions:

function loadNewVideo(id, startSeconds) {

  if (ytplayer) {

	ytplayer.loadVideoById(id, startSeconds);

  }

}




There are a number of ways we can call this function — through a drop down list of options, a text input box, etc. — but for simplicity’s sake, let’s just add another link button:

<a href="javascript:void(0);" onclick="loadNewVideo('tFI7JAybF6E', 0);">load</a>


And there you have it — a custom, chromeless movie player that you can control with JavaScript!

Conclusion

Now you know how to control and customize the basic YouTube movie player. Hopefully, you’ll also feel comfortable customizing the player to fit your own site.

If JavaScript isn’t your forte, there’s also a very similar (in function) ActionScript API that you can use to build your own controls and load chromeless players onto your pages.

Now you may be wondering, how can I get some YouTube movie data to display on my site? For instance, maybe you’d like to grab all the movies you’ve marked as favorites and display them on your blog? Or maybe you want to grab your own movies for display elsewhere.

We’ll cover those topics in our next installment when we tackle the other half of the YouTube API — The Data API.

Look for that tutorial on Webmonkey in just a few days.