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 Name | Value Type | Description |
---|---|---|
vId | string | The unique ID for the video. Usually, this corresponds to the player provider's ID for the video. |
start | float | offset (in seconds) from the start of the video, for where the video should begin playing. If not specified, this defaults to 0. |
end | float | offset (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. |
quality | string | quality 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.