YouTube JavaScript Player API: coding problems

The YouTube JavaScript Player API allows developers to use JavaScript to load videos from YouTube and display several related options. The official API's guide is located on this page. At first glance, the documentation provided here seems reasonably complete and accurate and, to be honest, it is. Problems start when you try to implement something on your own. First, to make everything work, you need the SWFObject script that has to be included before any other script call, like so:

 <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/swfobject/2.2/swfobject.js"></script>

Then you can use this object to run calls to the YouTube's API:

var params = { allowScriptAccess: "always" };
var atts = { id: "myytplayer" };
swfobject.embedSWF("http://www.youtube.com/v/8QRTkPrFbVQ?enablejsapi=1&playerapiid=ytplayer", 
                       "ytapiplayer", "425", "356", "8", null, null, params, atts);

The first part of this code is a params object literal with the various options that allow JavaScript to access the newly created HTML structure, which consists of an object element that, in turns, contains an embed element (to make it work in a cross-browser fashion). This object has an ID attribute that in this case is set to myytplayer and it's provided in the atts object literal. Everything is then passed to the embedSWF() method of the SWFObject library. The first parameter is an URL that contains the following data:

1. The video's ID (here 8QRTkPrFbVQ), taken from the video's page URL
2. enablejsapi=value for using JSONP
3. the ID of the player

You can find more information on the other parameters here. You can also see a live demo here. Now let' start seeing what are the real problems with this API.

Calling object methods

Calling object methods should be simple. As the documentation says:

In order to call the player API methods, you must first get a reference to the player object you wish to control. This can be done by calling getElementById() on the object or embed tag containing the player SWF if using SWFObject to embed the player SWF.

Operations

If you call directly getElementById() on the referenced ID of your object element, you actually get a reference to a normal HTML element on the page, not to a member of the underlying JavaScript library. For example, if you try something like this:

var player = document.getElementById('myytplayer');
alert(player.getVideoEmbedCode());

you get an error, because you're still referencing to a normal HTML element. If we continue reading the documentation, we'll find a couple of examples that show how to make this work. The most important for our problem is this: http://code.google.com/apis/youtube/js_api_reference.html#GettingReference, where you learn how to get a reference of the object. But now an innocent coder will probably say: "Where I should put this function?". The documentation doesn't say anything about that. We still wonder: "How should we use this function?".

Code examples

The live example attached to the main documentation page should provide some code snippets to developers in order to better understand what's really going on behind the scenes. But there are no code snippets! Further, viewing the source code of the sample page won't help because the sources of the examples are not there. So we have only a couple of short snippets to work with. This is not of much help.

Conclusion

Lack of practical examples, details and usability cause in this case a lot of coding problems. The best thing you can do is to find on the web some good tutorial on the subject.