Extending the VideoSnip Library v1.0.1

This document describes how to extend the functionality of the Video Snip library to support new video playback technologies, or to add new translations of the messages.

Overview

Because the API each extension implements will need to integrate with the wrapping API used by clients, this document outlines the expectations of the wrapping API. It uses the word MUST when the implementing API has to do something in a very specific way. If the behavior is optional, then the word SHOULD is used.

Constructor

The constructor for the provider will be given 3 arguments, which are all guaranteed to never be null:

element the DOM element object into which the player will need to embed itself.
reader the data model for the video playlist.
callback a function that MUST be called for all player events.

The constructor SHOULD setup all it needs to to prepare itself for the embed() invocation, but the player must not be embedded until then.

The playlist data model provides the following functions:

getCurrent() - returns the current video object that should be played, or null if there is no current video.
getIndex() - returns the index in the playlist of the current video object that should be played, or -1 if there is no current video.
advance() - advance the playlist to the next video.

Embedding

When the embed() method is called, the provider must put the player into the web page as either a child of the element object passed to the constructor, or as a replacement for it.

Player Status

getStatus() MUST return the current status of the player. Because of the differences between providers, the output of this method has some very specific definitions in order to create conformity.

The implementing function SHOULD not have a need to look at the model's current video object. All of the logic surrounding the transformation from player space to client space should be done by the base wrapping class.

If the provider is not available for retrieving information, then the following structure MUST be returned in place of real values.

return {
    ready: false,
    bufferTotal: -1,
    bufferBlocks: null,
    currentTime: -1,
    duration: -1,
    width: -1,
    height: -1,
    volume: 100,
    muted: false,
    loadedVideoURL: null,
    quality: "small",
    state: "not ready"
};

If the provider is available, then an object MUST be returned with the following attributes:

Attribute Name	Value Type	Description
`ready`	`boolean`	`true` if the player is ready for interaction from the scripts
`bufferTotal`	`int`	see Loaded Buffer Structure below for details
`bufferBlocks`	`array(int)`	see Loaded Buffer Structure below for details
`currentTime`	`float`	current position of the video in the player, in seconds; this will be calculated against the snip length to return the appropriate value to the client.
`duration`	`float`	full duration of the video being played, in seconds; this will be calculated against the snip length to return the appropriate value to the client.
`width`	`int`	width (in pixels) of the viewable player
`height`	`int`	height (in pixels) of the viewable player
`volume`	`int`	value between 0 and 100 (inclusive) describing the audio volume of the player; the local player value must be tranformed into this universal value.
`muted`	`boolean`	`true` if the audio is currently muted, otherwise `false`
`loadedVideoURL`	`string`	URL pointing to the current video, or `null` if not known or unavailable
`quality`	`string`	current quality of the video playing
`state`	`string`	textual description of the current state. Must be one of the values declared in `VideoSnipObj.getStatus`

Loaded Buffer Structure

In order to create a uniform structure to report the parts of the video buffer that have been loaded by the client, the implementation MUST conform to this standard. The buffer defines the buffer sizes in a numeric unit that is left up to the implementation (there is no requirement for correlating the units to seconds; it is usually in bytes loaded). The wrapping class uses these buffer values with the video object's start and end values to create a percentile loaded output value.

If the native player does not support buffer reporting, then the ret.bufferTotal value MUST be set to -1. The ret.bufferBlocks structure SHOULD be null.

The ret.bufferTotal value MUST equal the total number of buffer units that the video contains.

The ret.bufferBlocks value MUST be an array of integer pairs. Its length MUST be divisible by 2. This structure defines blocks of the video buffer loaded by the client. For block i, the value ret.bufferBlocks[i * 2] is the start unit for the block, and ret.bufferBlocks[i * 2 + 1] is the end unit for the block. Each block MUST have its start be less than its end. Furthermore, each block MUST NOT overlap other blocks.

Player Queries

The provider MUST support the following functions, which inform the client about the state of the player. None of these take argument values. Note that some of these match up with a corresponding Player Action.

Function Name	Return Type	Description
`isReady`	`boolean`	`true` if the player is ready for script interaction, or `false` if the player either hasn't been embedded, or isn't yet ready to be controlled by a script.
`getVolume`	`int`	The current player volume output, which must be between 0 and 100 (inclusive), where 100 is maximum volume, and 0 is no volume.
`isMute`	`boolean`	`true` if the player is currently muted, or `false` if it is not muted.

Player Actions

The provider MUST support the following functions, which tell the player to perform different actions.

Function Name	Arguments	Description
`play`	`()`	Begin playback of the video
`pause`	`()`	Pause playback of the video
`seekTo`	`(float position, boolean autoplay)`	Seek the current playback to the given absolute position (in seconds). If `autoplay` is `true`, then the player SHOULD begin playing after the seek completes.
`resize`	`(int width, int height)`	Change the viewable ize of the player to the given size, in pixels.
`setVolume`	`(int volume)`	Set the audio volume of the player, where `volume` is between 0 and 100 (inclusive).
`mute`	`()`	Mute the audio of the player.
`unmute`	`()`	Unmute the audio of the player.

Event Processing

The VideoSnip API has strict requirements around the kinds of events that need to be sent to the client. It is up to the provider to translate its events into those needed by the client. All such events MUST be passed to the callback function provided to the constructor.

Handling Start / End Times

Each video object to be played has the attributes start and end, which define the start and end position of the video clip (in seconds). It is the responsibility of the provider to correctly seek to the start position, and play the video until the end position is reached.

Registering The Provider

To register the provider implementation so that a page can use it, the script and its dependent scripts MUST be added to the snip.js page, in the dependencies variable structure. Multiple entries for the same provider can be added to allow for aliases. Clients can reference the provider by specifying the key name in the loadScripts function.