This document covers the v1.0.1 release of the Web Video Snip , and is intended to complement the Snip API reference documentation. This guide assumes that you know some HTML and a bit of JavaScript. If you have questions or comments, you can e-mail the author, Matt Albrecht (groboclown@gmail.com) .

Preparing Your Web Page

To embed the playlist, you must first prepare it for embedding the video player in your web page. Start by adding a <div> in the body of your page, marked with a unique ID, so that the embedding tools can find the right place to insert the player:

        <div id="videoplayer" style="width: 425px; height: 356px";>
            <a href="http://www.adobe.com/go/getflashplayer">Get
            flash</a> to see this player, or enable Flash + JavaScript,
            if your browser has them disabled.
        </div></pre>

Note how the size of the video player is defined in the CSS stylesheet. However, it is possible to resize the player per video (this is described below).

Next, you will need to include the correct JavaScript file in the <head> section of your page. This needs to be accompanied by declaring what kind of embedded player to use.

<html>
  <head>
    <script
      src="http://ytsnip.sf.net/snip.js"
      type="text/javascript"></script>
    <script
      type="text/javascript">
VideoSnip.loadScripts("youtube");
    </script>

Currently, the script only supports YouTube and HTML 5 videos. For most of this guide, we will use YouTube videos. We'll discuss embedding HTML 5 compatible videos at the end.

Loading The Player

We must trigger the player to embed itself after the page finishes loading. The standard method in use for modern browsers to trigger an on-page-load action is through script, something like this:

function addEvent(obj, evType, fn) {
    if (obj.addEventListener) { 
        obj.addEventListener(evType, fn, false); 
    } else if (obj.attachEvent) { 
        obj.attachEvent("on" + evType, fn); 
    }
}

Your web site may already have a similar method for adding event listeners, so use that with which you're comfortable.

Next, we need to create and embed the player in our page load event listener function. We'll store the player object in a global variable in this example.

var vidSnip;
function onPageLoad() {
    vidSnip = VideoSnip.createVideoSnip("videoplayer");
    vidSnip.embed();
}
addEvent(window, 'load', onPageLoad);

This declares the function onPageLoad, and registers it to execute once the browser finishes loading the web page. When it executes, it will create the video snip object, and then embed the player into the <div> tag with id "videoplayer".

This code can be seen in action in this page.

Adding Videos To The Playlist

The above snippet of code will create our player and show it in the web page, but we won't have any videos available for the playlist. You should see a YouTube player widget with a black screen and no controls. Not very interesting.

The vidSnip object has the method VideoSnipObj.addVideos(Object[]) , which takes an array of objects that describe the different videos to play. Alternatively, you can add them one at a time with the VideoSnipObj.addVideo(Object) method. This playlist is usually constructed something like this:

var videoList = [
  { vId: "ZM85Ola_FCY" }, { vId: "CnB-9ZTajS8" } ];

Again, this is for a YouTube video player, where each ID corresponds to a YouTube video ID. You can put as many values into each object as you please, but there are some reserved keys, in particular:

Attribute NameValue TypeDescription
vIdstringThe unique ID for the video. Usually, this corresponds to the player provider's ID for the video.
startfloatoffset (in seconds) from the start of the video, for where the video should begin playing. If not specified, this defaults to 0.
endfloatoffset (in seconds) from the start of the video, for where the video should stop playing. Any value less than the start value means the video will play to the end. If not specified, this defaults to -1.
qualitystringquality of the video to display.

"Quality" here describes the quality of the video. For YouTube videos, this corresponds to the size of the video. Supported values are default, small, medium, large, hd720, and hd1080.

The other keywords are described in detail on the API page.

In order to have our example play these videos upon loading the page, we'll need to add the videos to the player before embedding it.

var videoList = [
    {
        title: "BMW X3 TV commercial",
        vId: "ZM85Ola_FCY",
        start: 0.0,
        end: 15.0
    },
    {
        title: "BMW 3-Series 2007",
        vId: "CnB-9ZTajS8",
        start: 4.2,
        end: 10
    }
];
var vidSnip;
function onPageLoad() {
    vidSnip = VideoSnip.createVideoSnip("videoplayer");
    vidSnip.addVideos(videoList);
    vidSnip.embed();
}
addEvent(window, 'load', onPageLoad);

Our advancing web page has developed into this.

Adding Controls

You now have a YouTube player that can play a series of video clips! However, since this is the chrome-free player, your users have no way to control the video, even for something as simple as muting the volume.

You will need to implement these controls yourself by connecting JavaScript to HTML visual controls. However, the Snip API provides simple methods to implement the most common of control functions. Here's some examples of the JavaScript used for the common player controls.

function play() {
    if (vidSnip) vidSnip.play();
}
function pause() {
    if (vidSnip) vidSnip.pause();
}
function nextVid() {
    if (vidSnip) vidSnip.nextVideo(true);
}
function prevVid() {
    if (vidSnip) vidSnip.prevVideo(true);
}
function toggleMute() {
    if (vidSnip) vidSnip.toggleMute();
}
function increaseVolume() {
    if (vidSnip) vidSnip.setVolume(vidSnip.getVolume() + 10);
}
function decreaseVolume() {
    if (vidSnip) vidSnip.setVolume(vidSnip.getVolume() - 10);
}

For these, we had to put the vidSnip into a page-wide global variable. You'll also notice some protection to keep the buttons from causing errors if the player hasn't been initialized yet. The ever-growing sample web-page can be found here. The example is passible, but a real site should add better looking controls.

If you look at the source for the example, you'll notice that it simplifies the calls for the controls even more, by registering the button click functions when it knows that the vidSnip object has been allocated.

Responding To Events

The VideoSnip object will generate events as the videos are loaded and played. It may also generate an event if different error situations arise. Your web page may react to these events by registering a listener.

There are two approaches to handling these events: listen to all the events, or register to listen to individual events.

In both cases, the callback function takes an object argument, called the "message object." It contains many fields with relevant information about the event. The contents of this object are detailed in the method VideoSnipObj.addEventListener(string, function) .

Listen To All Events

If you want to listen to all events, then you need to add a callback function when creating the VideoSnip object:

var vidSnip;
function myCallback(msgObj) {
    // respond to event
}
function onPageLoad() {
    vidSnip = VideoSnip.createVideoSnip("videoplayer", myCallback);
    ...
}

Then, whenever an event occurs, your callback method will receive it. This is useful for ensuring that everything that happens will be caught. However, it also makes the method confusing by adding "if" statements when checking for each kind of event.

Listen To Individual Events

Alternatively, you may only listen for the events you care about. Commonly, you'll want to listen for the "error" message (for any error event). This is done by calling VideoSnipObj.addEventListener(string, function) :

function onPageLoad() {
    var vidSnip = VideoSnip.createVideoSnip("videoplayer");
    vidSnip.addEventListener("error", function (msgObj) {
            // respond to error events
        });
    vidSnip.addEventListener("endoflist", function (msgObj) {
            // end-of-list reached
        });
}

This allows your code to be less cluttered, but also means that your code must explicitly declare all the different kinds of events. These events are outlined with the documentation for VideoSnipObj.addEventListener(string, function) .

Our example has now developed into this. With some clean-up, it could become a usable page.

Resizing The Player

At any time, you can resize the player in the web page by running the following code, obviously replacing newWidth and newHeight with the appropriate values:

vidSnip.resize(newWidth, newHeight);

Also, the playlist allows for auto-sizing the player on a per-video basis. If any video object has set width and height values in their object, then, when the video is loaded for playback, the player will attempt to resize itself on the page to match the video's desired dimensions.

Playing HTML 5 Videos

To use HTML 5 embedded videos instead of YouTube, the process is very similar. There are only two specific areas of differences that you need to be aware of.

Firstly, the loadScripts invocation must be done differently:

VideoSnip.loadScripts("html5");

Next, the way the videos are constructed must be different. Because HTML 5 video has incompatible video support from browser to browser, a webpage should provide different formats and codecs, so that all HTML 5 browsers can play the video.

Instead of using the vId to describe the video, the HTML 5 provider requires multiple URLs describing all the different formats of the video. These are added as an array on the available attribute.

Each video file object (inside the array attached to the video object; yeah, it's getting confusing) should provide the url attribute for the location of the video file, the mime attribute containing the mime type of the video file, and codecs attribute containing the array of codecs in the video file. A fully defined video object can look something like this:

vidSnip.addVideo({
        vId: "http://videos.mozilla.org/firefox/3.5/meet",
        available: [
            {
                url: "http://videos.mozilla.org/firefox/3.5/meet/meet.ogv",
                mime: "video/ogg",
                codecs: [ "theora", "vorbis" ]
            },
            {
                url: "http://videos.mozilla.org/firefox/3.5/meet/meet.mp4",
                mime: "video/m4v",
                codecs: [ "mp4a", "avc1" ]
            }
        ],
        start: 0.0,
        end: 15.0
    });

Details are provided in the providers description page for discovering the mime and codecs of a video file.

Here you'll find the HTML 5 version of the previous sample. Because this isn't YouTube videos, the list of videos is different.