VideoSnip JavaScript Public API Documentation v1.0.1

This document describes the API provided by the JavaScript file snip.js. For a tutorial, see How To Embed The Playlist In Your Web Page.

Required Files

snip.js loads the dependent files as necessary. However, some video-provider implementations require third-party libraries which you may not have installed on the site. In this case, you must explicitly load them with the <script> tag.

Global Fields

Field Name	Field Type	Read Only?	Description
`VideoSnip.version`	`string`	Yes	The API version of the VideoSnip library
`VideoSnip.fullVersion`	`string`	Yes	The specific version, including patch-level, of the VideoSnip library

Global Functions

`VideoSnip.loadScripts(string provider)`

Parameter	Type	Description
`provider`	`string`	name of the video provider to use

Loads the required script files for the specified provider. If the given provider is not known or supported, an error will be thrown. Note that this means, with this version, VideoSnip can only allow one kind of video provider per web page. Future versions may change this limitation.

This must be called before any other function.

A list of built-in providers, along with details for using them, can be found here.

You can create your own support for a different video provider by following this guide.

`VideoSnip.createVideoSnip(string elementId, function callback)`

Parameter	Type	Description
`elementId`	`string`	ID for the div in the HTML document for the element to contain the constructed video snip object.
`callback`	`function`	function called on events generated by the library

Returns: the VideoSnipObj instance created by this call

Creates a new VideoSnipObj instance. If the callback function is not provided, then the VideoSnipObj.addEventListener(string, function) and VideoSnipObj.removeEventListener(string, function) methods can be used. If the callback method is provided, then it will be invoked for all events. See the VideoSnipObj.addEventListener(string, function) method for details on the events and usage of the callback function.

Note that the size of the embedded video player is dependent upon the size of the containing page element (marked with id elementId). After embedding, the player may be resized.

`VideoSnip.findVideoSnip(string elementId)`

Parameter	Type	Description
`elementId`	`string`	ID used to create the VideoSnipObj

Returns: the VideoSnipObj instance created with the ID, or null if never created

Retrieves the VideoSnipObj instance constructed by the VideoSnip.createVideoSnip(string, function) call, or null if no such ID was used in the call.

VideoSnipObj - Class

The VideoSnipObj class is returned by VideoSnip.createVideoSnip(string, function) and by VideoSnip.findVideoSnip(string) .

VideoSnipObj - Fields

Field Name	Field Type	Read Only?	Description
`elementId`	`string`	Yes	The element ID that contains the player.

VideoSnipObj - Methods

`VideoSnipObj.addEventListener(string evtName, function callback)`

Parameter	Type	Description
`evtName`	`string`	name of the event to register the callback to
`callback`	`function`	function that is called on evtName events

Adds a listener to a specific event type. Multiple callback functions can register themselves with the event. Event names are either "error" (for all error messages), or the specific events.

The callback function takes a message object as its argument, which has the following properties for all events:

Attribute Name	Value Type	Description
`name`	`string`	string name of the event type
`id`	`int`	integer identifier for the event type; useful for case statements
`msg`	`string`	textual description of the event, suitable for displaying to the user
`iserror`	`boolean`	`true` if this is an error event
`source`	`string`	source of the event; useful for debugging

Note that the message string (attribute msg) should be translated into the client's language. Details on adding custom translations can be found in this guide.

The following is a list of all non-error events that can be registered for listening. These may have additional attributes set in the message object beyond the above list.

evtName	id	Description
`videoadded`	200	A video was added to the playlist. The message object will include these additional attributes: index - playlist index of the added video video - video object added
`videoremoved`	201	A video was removed from the playlist. The message object will include these additional attributes: index - playlist index where the video was removed video - video object removed
`nextvideochanged`	202	The next video to play was changed. The playlist contents itself were not altered, but the reference to the next video position within the playlist changed. The message object will include these additional attributes: index - playlist index for the next video to play video - video object that will play next previndex - playlist index of the previous "next" video prevvideo - previously "next" video object
`videoswap`	203	Two videos swapped their order in the playlist. The message object will include these additional attributes: index1 - playlist index for the first of the swapped videos video1 - video object for the first of the swapped videos (BEFORE the swap occurs) index2 - playlist index for the second of the swapped videos video2 - video object for the second of the swapped videos (BEFORE the swap occurs)
`videoadvanced`	300	The playlist has advanced to the next video. The video will immediately begin loading after this. The message object will include these additional attributes: index - playlist index for the now current video video - video object that is now current
`endoflist`	301	The playlist has reached the end of the list. This will occur when the player attempts to advance to the next video, but there are no more videos to play.
`videoloading`	302	The current video is being loaded by the player.
`videowaiting`	303	The video is loaded in the player, and waiting for the user to start playing it. It can happen if "autostart" is set to `false`, or if the user pauses the playback. The message object will include these additional attributes: video - currently loaded video object
`videostartplay`	304	The currently loaded video has started playing. The message object will include these additional attributes: video - currently loaded video object

The web page can also register to listen to "error" events (with the registered evtName value "error"). When an error event is triggered, it indicates that an error occurred either in the JavaScript API usage, or in the provider's video player. The severity of the error is in the message object's level attribute. The severity list is as follows, from least severe to most:

warn - something unexpected happened, but the system could correct itself
error - an error occurred. The user or web page may wish to continue, as it may self-correct.
fatal - the player encountered an error, which prevents it from working at all.

The page may also listen to each individual error event, which are listed below:

evtName	id	Description
`nosuchelement`	100	The elementId passed on creation doesn't exist on the web page.
`notvalidvideo`	101	The video object could not be loaded because it isn't valid.
`apiusage`	102	The snip API was used incorrectly.
`noplayerdef`	103	No player definition could be found.
`invalidstate`	104	The internal state of the player is invalid.
`invalidstatetransition`	105	The internal state of the player is invalid.
`invalidstatetransitionstate`	106	The internal state of the player is invalid.
`novideo`	107	No video was specified.
`videoseekerror`	108	There was a problem trying to seek to a position in the video.
`requiredscript`	109	A script required by the player wasn't correctly loaded.
`videonotfound`	110	The requested video could not be found.
`videonotallowed`	111	Access to the video is not allowed.
`unknownprovidererror`	112	The provider reported an unknown error.
`fetchaborted`	113	The fetching of data for the video was aborted.
`networkerror`	114	There was a network error that prevented the video from loading.
`videodecodeerror`	115	The video could not properly be decoded.
`videotypenotsupported`	116	The video format or codec is not supported by the player.

Note that a custom video provider may include additional errors not listed here (though this is frowned upon). They will be picked up by any "error" listener.

`VideoSnipObj.removeEventListener(string evtName, function callback)`

Parameter	Type	Description
`evtName`	`string`	name of the event to stop listening to events
`callback`	`function`	callback to remove

Removes the registered event listener that has the given callback function listening to the given event name. If the listener isn't registered, then the function safely ignores the request.

`VideoSnipObj.embed(boolean autoplay)`

Parameter	Type	Description
`autoplay`	`boolean`	`true` if the video should start playing as soon as the player becomes embedded, and the video is loaded

Embeds the video into the div tag (passed in at object creation time). This starts the initialization process for the VideoSnipObj instance.

`VideoSnipObj.isReady()`

Returns: true if the player is embedded and ready to play a video

Checks if the player is ready to start playing a video. Web pages should use an event listener to know when the player is ready, rather than looping over this call.

`VideoSnipObj.addVideo(Object video)`

Parameter	Type	Description
`video`	`Object`	video description

Appends a single video description to the playlist. The "video" here is described by the parameter object, which can have any attributes the user may need to support the website and the specific video provider. For use with the VideoSnip API, it must provide the vId attribute. The following attributes are recognized and reserved for the VideoSnip API:

Attribute Name	Value Type	Description
`vId`	`string`	YouTube video ID of the video to show
`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.
`width`	`float`	sets the width of the video player when the video is played; the player will only be resized if this and the `height` attribute are set.
`height`	`float`	sets the height of the video player when the video is played; the player will only be resized if this and the `width` attributes are set.
`quality`	`string`	requests a video quality / resolution size to playback

The quality setting is highly dependent upon the video player provider. The player should attempt to choose the closest quality (scaling downward) based on the supported video formats. The supported quality values are listed in the VideoSnipVideo.supportedQuality constant array:

Quality Setting	Meaning
`default`	Use the default player quality
`small`
`medium`
`large`
`hd720`	HighDef 720p
`hd1080`	HighDef 1080p

This call does not affect the state of the video player.

`VideoSnipObj.addVideos(Object[] videoList)`

Parameter	Type	Description
`videoList`	`Object[]`	Array of videos to load

Appends a list of videos to the playlist. Each video object added must conform to the specifications listed in VideoSnipObj.addVideo(object) .

This call does not affect the state of the video player.

`VideoSnipObj.insertVideoAt(int index, Object video)`

Parameter	Type	Description
`index`	`int`	index in the playlist to insert the video
`video`	`Object`	video description

Inserts the video to the given index in the playlist. If index is outside the bounds of the playlist (less than 0 or greater than the current length), it will be changed to the boundary. A null video will be safely ignored.

`VideoSnipObj.removeVideoAt(int index)`

Parameter	Type	Description
`index`	`int`	index in the playlist to remove

Removes the video at the given index. If the index is out of bounds, the removal will be ignored. The playlist order may be affected depending upon the current video index value in relationship to the removed video index:

Current Video Index is less than Removed Video Index	The removed video will not be played when the current video index advances to that point.
Current Video Index is equal to Removed Video Index	The current video will continue to be loaded in the player. The next played video will be the correct next video, but switching to the "previous" video will skip a video.
Current Video Index is greater than Removed Video Index	The current video index will be adjusted to correctly play the next video in the list from the currently playing video. The currently loaded video will not change.
There are no more videos after removal	The currently loaded video will continue its playback.

Note the issue in the situation where the current video is being removed on the "previous" action. In all situations, the currently loaded video will not be affected by this action.

`VideoSnipObj.swapVideos(int index1, int index2)`

Parameter	Type	Description
`index1`	`int`	index in the playlist of one video
`index2`	`int`	index in the playlist of another video

Swaps the position in the playlist of two videos. If the video index1 or index2 are outside the bounds of the playlist (less than 0 or greater than the current length), it will be changed to the boundary.

The currently playing video will be changed to reflect the swap. The next video to play will only be changed if the next video index is one of the swapped indicies. Attempts are made to force the "next" index to point to an actual video after this call, so be aware that this call can affect both the "next" and "current" playing index. Specifically, when the last video in the list is currently playing, and is swapped to an earlier position in the playlist, then the "next" video will now point to the video after the new current position.

This has an advantage over two separate calls to VideoSnipObj.removeVideoAt(int) and VideoSnipObj.insertVideoAt(int, object) because it preserves the correct state for which video is currently loaded and playing, as well as the "next" order. It also minimizes the number of callbacks performed. This allows for easier implementations of changing the order of videos in the playlist.

`VideoSnipObj.removeAllVideos()`

Removes all videos in the playlist. This will not affect the currently playing video.

`VideoSnipObj.hasNextVideo()`

Returns: true if there is another video to play, or false if the playlist has ended, or will end after the current video

Checks whether there is another video that can be played after the current video.

`VideoSnipObj.hasCurrentVideo()`

Returns: true if there is a video loaded, either playing or ready to play, or false if the playlist has ended, or if it has not started playing

Retrieves the current state of the playlist, whether there is a video currently loaded or not. That is, if the player has a video that's playing or paused, then this will return true.

`VideoSnipObj.setNextVideoIndex(int index)`

Parameter	Type	Description
`index`	`int`	video index

Sets the next video index to play. If the index is out of range to the current video list, the index will be bounded - if the index is less than zero, the first video in the list to be played next, and above the list size the playlist will end when the current one finishes.

`VideoSnipObj.getVideos()`

Returns: copy of the current playlist array of videos

Returns a copy of the current playlist of videos. Altering this list will not affect the play order. However, each video within the list may be altered to affect its playback.

`VideoSnipObj.getVideoCount()`

Returns: number of videos in the playlist

Returns the total number of videos in the playlist, both before and after the current playing position.

`VideoSnipObj.getStatus()`

Returns: an object/dictionary that contains information describing the object's state

Retrive the current state of the player. For information about the state of the currently playing video, see VideoSnipObj.getCurrentVideoInfo() .

Before checking the contents of the returned object, you should always check for the ready flag. If the player is not ready (false), then only the following attributes are returned:

Attribute Name	Value Type	Description
`ready`	`boolean`	always set to `false`
`state`	`string`	always set to 'not initialized'

If the player is ready, then the returned object has the following attributes:

Attribute Name	Value Type	Description
`ready`	`boolean`	the ready state of the player
`width`	`int`	video player width in pixels
`height`	`int`	video player height in pixels
`volume`	`int`	audio playback volume, between 0 and 100 inclusive
`muted`	`boolean`	`true` if the audio is muted, otherwise `false`
`quality`	`string`	video playback quality
`state`	`string`	current playback state of the player

The state attribute can be one of the following values:

seeking - the video player is seeking to a specific position within the video
paused - the video player has paused playback
not playing - the video player is not playing, possibly due to either no video loaded, or the playlist is at the end
playing - the video player is playing the current video
buffering - the video player is downloading the video, to buffer up enough data to allow for playback

`VideoSnipObj.play()`

Plays the currently loaded video if the player is initialized and a video is loaded, otherwise does nothing.

`VideoSnipObj.pause()`

Pauses the currently playing video if the player is initialized and a video is loaded, otherwise does nothing.

`VideoSnipObj.nextVideo(boolean autostart)`

Parameter	Type	Description
`autostart`	`boolean`	true if the next video should start playing upon being loaded, otherwise the video will not start when loaded

Loads the next video, and plays it after being loaded if the argument is provided and true.

`VideoSnipObj.prevVideo(boolean autostart)`

Parameter	Type	Description
`autostart`	`boolean`	true if the previous video should start playing upon being loaded, otherwise the video will not start when loaded

Loads the previous video, and plays it after being loaded if the argument is provided and true.

`VideoSnipObj.getCurrentVideo()`

Returns: the current video object, or null if none is active.

Retrieve the currently loaded video object, as passed into the playlist. If no video is loaded, or if the instance is not initialized, null.

`VideoSnipObj.getCurrentVideoIndex()`

Returns: -1 if at the beginning of the playlist, size if at the end of the playlist, or the actual index.

Returns -1 if at the beginning of the playlist, size if at the end of the playlist, or the actual index.

`VideoSnipObj.getCurrentVideoInfo()`

Returns: copy of the current video object, along with additional information, or null if nothing is playing

Returns a copy of the currently playing video object, augmented with additional information on its playing state. The expected fields will include:

Parameter	Type	Description
`vId`	`string`	video ID
`loadedVideoURL`	`string`	the URL of the video (if any), as reported by the player
`start`	`float`	seconds from start of video
`end`	`float`	seconds into the video to stop, or -1 for end
`bufferLoaded`	`float`	percent of the plyable video buffer that has been loaded by the player, or -1 if not known
`absDuration`	`float`	total time for the video, in seconds
`absCurrentTime`	`float`	current position from the start of the video, in seconds
`duration`	`float`	total time that the playlist will play the video, in seconds
`currentTime`	`float`	current position from the playlist start time of the video, in seconds
`index`	`int`	current video index
`quality`	`string`	the video quality being played by the video player
`width`	`int`	player current width
`height`	`int`	player current height

Details about the quality attribute can be found at VideoSnipObj.addVideo(object) . If the video object included custom fields, they will be added to this list.

The bufferLoaded attribute tells the client how much of the video, between the start/end times, is loaded. Because each player implementation may have different capabilities, this should only be a rough estimate, and useful only for user feedback. The player itself should know whether it needs to buffer more data.

`VideoSnipObj.seekTo(float seconds, boolean autostart)`

Parameter	Type	Description
`seconds`	`float`	position, in seconds, to seek to
`autostart`	`boolean`	true if the video should start playing after seeking, otherwise the video will not start after seeking

Seek to a position in the video relative to the video's start parameter (or 0 if not specified). If the seconds argument is after the end of the video (either absolute, or the end parameter of the current video), then the player will advance to the next video in the playlist.

`VideoSnipObj.mute()`

Asks the player to stop audio playback of the video. This will have no effect if the player isn't initialized yet.

`VideoSnipObj.unmute()`

Asks the player to restore audio playback of the video. This will have no effect if the player isn't initialized yet.

`VideoSnipObj.toggleMute()`

Toggles the current mute state of the player. This call wraps the VideoSnipObj.mute() and VideoSnipObj.unmute() calls, for easier support of a mute toggle button on the page.

`VideoSnipObj.setVolume(int volume)`

Parameter	Type	Description
`volume`	`int`	value between 0 (silent) and 100 (full loudness)

Asks the player to set its volume to the given value. Volume values should be an integer between 0 and 100 (inclusive), where "0" means the lowest volume, and "100" means the highest volume. If the volume is outside that range, then it will be trimmed to be within bounds (it will not cause an error).

Note that the player may not actually use this value. If you display to the user the current player volume, any call to this function should be followed by a call to VideoSnipObj.getVolume() to ensure that the user sees the correct value. For example, a muted player may not recognize any setVolume call.

`VideoSnipObj.getVolume()`

Returns: the current volume value (0 to 100)

Retrieves the current volume of the player. Volume values will be an integer between 0 and 100 (inclusive), where "0" means the lowest volume, and "100" means the highest volume.

Note that explicitly calling VideoSnipObj.setVolume(int) does not guarantee the same return value from this function. If the player is not yet initialized, or if the player internally alters the volume, then this function may return a different value.

`VideoSnipObj.isMute()`

Returns: true if the player is muted

Retrieves the state of "mute" in the player. If the player is not initialized, this will return false.

`VideoSnipObj.setSize(int width, int height)`

Parameter	Type	Description
`width`	`int`	new width of the player
`height`	`int`	new height of the player

Attempts to change the display size of the player in the web page. This can be changed later if a video specifies the height and width.