Documentation of Video Player Providers for VideoSnip v1.0.1

This document describes the video player providers supported by default with snip.js, and their specific needs or quirks.

YouTube
HTML 5
Extended HTML 5

You can find out how to create your own custom provider here.

YouTube

This provider uses the embedded YouTube player to play videos.

Loading The YouTube Provider

To use the YouTube player, your web page should start with something like this:

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

Adding YouTube Videos

The VideoSnipObj.addVideo(object) call use the vId attribute for the YouTube ID, like so:

vidSnip.addVideo({
        vId: "ZM85Ola_FCY",
        start: 0.0,
        end: 15.0
    });

This provider uses the HTML 5 <video> tag to display videos. Due to complications with incompatible browser video format support, this method requires a bit more work to add videos than with the YouTube method.

Loading The HTML 5 Provider

To use HTML 5 video, your web page should start with something like this:

<html>
  <head>
    <script src="snip.js" type="text/javascript"></script>
    <script type="text/javascript">
VideoSnip.loadScripts("html5");
    </script>

Adding HTML 5 Videos

Due to the complications with different browsers supporting incompatible video formats, the VideoSnipObj.addVideo(object) call uses the available attribute. This attribute must be an array of objects that describe different formats and URLs of the same video. These objects should also be listed in order of preference.

Each object in the available attribute array should add these attributes:

Attribute Name	Value Type	Description
`url`	`string`	URL of the video file
`mime`	`string`	mime type of the video (optional)
`codecs`	`array of strings`	all the codecs used by the video (optional). There is commonly more than one, because a video contains an encoded audio and video, each having a different codec.

The objects in the array must have a url attribute, where the video should be loaded from, and a mime attribute to describe the kind of video referenced by the URL. Additionally, an optional codecs attribute can provide an array of codecs used by the video.

The "vId" of the video is not as critical to the operation as with a YouTube video, but each vId should still be distinct from each other.

Here's an example on how to load 2 different HTML 5 videos.

var videoList = [
    {
        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" ]
            }
        ],
        title: "Firefox Meet",
        start: 0.0,
        end: 15.0
    },
    {
        vId: "http://www.youtube.com/demo/google_main.mp4",
        available: [
            {
                url: "http://www.youtube.com/demo/google_main.mp4?2",
                mime: "video/x-m4v",
                codecs: [ "mp4a", "avc1" ]
            }
        ],
        title: "Google Demo video",
        start: 0.0,
        end: 15.0
    }
];
vidSnip.addVideos(videoList);

FIXME: Describe how to discover the mime and codec for a video

Extended HTML 5

HTML 5 has a limitation where all the video files, and their meta-data (mime type and codecs) must be known by the embedding web page. The custom Extended HTML 5 specification eliminates this by instead loading an XML or JSON file which contains this information, and then shows the appropriate video using the HTML 5 <video> tag.

The Extended HTML 5 Video File

The HTML 5 video information can be contained in either a JSON file or an XML file. The provider assumes that the information is an XML file, unless the url ends in ".json", in which case it will be parsed as a JSON file.

For security reasons, at the moment, each video URL contained in the extended HTML 5 file must be relative to the requested file - that is, it is considered either in the same directory or a sub-directory of the requested file.

The JSON format for the file should essentially match the available structure in the above HTML 5 section above:

{
    videos: [
        {
            url: "meet.ogv",
            mime: "video/ogg",
            codecs: [ "theora", "vorbis" ]
        },
        {
            url: "meet.mp4",
            mime: "video/m4v",
            codecs: [ "mp4a", "avc1" ]
        }
    ]
}

The XML format is, again, similar, but uses tags for the data. Note that each codec part is in its own tag.

<?xml version="1.0" encoding="UTF-8"?>
<videos>
  <video>
    <url>meet.ogv</url>
    <mime-type>video/ogg</mime-type>
    <codec>theora</codec>
    <codec>vorbis</codec>
  </video>
  
  <video>
    <url>meet.mp4</url>
    <mime-type>video/mp4v</mime-type>
    <codec>mp4a</codec>
    <codec>avc1</codec>
  </video>
</videos>

Loading The Extended HTML 5 Provider

To use the Extended HTML 5 player, your web page should start with something like this:

<html>
  <head>
    <script src="snip.js" type="text/javascript"></script>
    <script type="text/javascript">
VideoSnip.loadScripts("html5x");
    </script>

Adding YouTube Videos

The VideoSnipObj.addVideo(object) call use the vId attribute to point to the URL of the HTML 5 extention file, like so:

vidSnip.addVideo({
        vId: "http://videos.mozilla.org/firefox/3.5/meet/meet.xml",
        start: 0.0,
        end: 15.0
    });