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 NameField TypeRead Only?Description
VideoSnip.versionstringYesThe API version of the VideoSnip library
VideoSnip.fullVersionstringYesThe specific version, including patch-level, of the VideoSnip library

Global Functions

VideoSnip.loadScripts(string provider)

ParameterTypeDescription
providerstringname 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)

ParameterTypeDescription
elementIdstringID for the div in the HTML document for the element to contain the constructed video snip object.
callbackfunctionfunction 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)

ParameterTypeDescription
elementIdstringID 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 NameField TypeRead Only?Description
elementIdstringYesThe element ID that contains the player.

VideoSnipObj - Methods

VideoSnipObj.addEventListener(string evtName, function callback)

ParameterTypeDescription
evtNamestringname of the event to register the callback to
callbackfunctionfunction 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 NameValue TypeDescription
namestringstring name of the event type
idintinteger identifier for the event type; useful for case statements
msgstringtextual description of the event, suitable for displaying to the user
iserrorbooleantrue if this is an error event
sourcestringsource 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.

evtNameidDescription
videoadded200 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
videoremoved201 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
nextvideochanged202 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
videoswap203 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)
videoadvanced300 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
endoflist301 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.
videoloading302 The current video is being loaded by the player.
videowaiting303 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
videostartplay304 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:

  1. warn - something unexpected happened, but the system could correct itself
  2. error - an error occurred. The user or web page may wish to continue, as it may self-correct.
  3. 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:

evtNameidDescription
nosuchelement100The elementId passed on creation doesn't exist on the web page.
notvalidvideo101The video object could not be loaded because it isn't valid.
apiusage102The snip API was used incorrectly.
noplayerdef103No player definition could be found.
invalidstate104The internal state of the player is invalid.
invalidstatetransition105The internal state of the player is invalid.
invalidstatetransitionstate106The internal state of the player is invalid.
novideo107No video was specified.
videoseekerror108There was a problem trying to seek to a position in the video.
requiredscript109A script required by the player wasn't correctly loaded.
videonotfound110The requested video could not be found.
videonotallowed111Access to the video is not allowed.
unknownprovidererror112The provider reported an unknown error.
fetchaborted113The fetching of data for the video was aborted.
networkerror114There was a network error that prevented the video from loading.
videodecodeerror115The video could not properly be decoded.
videotypenotsupported116The 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)

ParameterTypeDescription
evtNamestringname of the event to stop listening to events
callbackfunctioncallback 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)

ParameterTypeDescription
autoplaybooleantrue 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)

ParameterTypeDescription
videoObjectvideo 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 NameValue TypeDescription
vIdstringYouTube video ID of the video to show
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.
widthfloatsets 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.
heightfloatsets 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.
qualitystringrequests 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 SettingMeaning
defaultUse the default player quality
small
medium
large
hd720HighDef 720p
hd1080HighDef 1080p

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

VideoSnipObj.addVideos(Object[] videoList)

ParameterTypeDescription
videoListObject[]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)

ParameterTypeDescription
indexintindex in the playlist to insert the video
videoObjectvideo 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)

ParameterTypeDescription
indexintindex 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)

ParameterTypeDescription
index1intindex in the playlist of one video
index2intindex 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)

ParameterTypeDescription
indexintvideo 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 NameValue TypeDescription
readybooleanalways set to false
statestringalways set to 'not initialized'

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

Attribute NameValue TypeDescription
readybooleanthe ready state of the player
widthintvideo player width in pixels
heightintvideo player height in pixels
volumeintaudio playback volume, between 0 and 100 inclusive
mutedbooleantrue if the audio is muted, otherwise false
qualitystringvideo playback quality
statestringcurrent playback state of the player

The state attribute can be one of the following values:

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)

ParameterTypeDescription
autostartbooleantrue 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)

ParameterTypeDescription
autostartbooleantrue 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:

ParameterTypeDescription
vIdstringvideo ID
loadedVideoURLstringthe URL of the video (if any), as reported by the player
startfloatseconds from start of video
endfloatseconds into the video to stop, or -1 for end
bufferLoadedfloatpercent of the plyable video buffer that has been loaded by the player, or -1 if not known
absDurationfloattotal time for the video, in seconds
absCurrentTimefloatcurrent position from the start of the video, in seconds
durationfloattotal time that the playlist will play the video, in seconds
currentTimefloatcurrent position from the playlist start time of the video, in seconds
indexintcurrent video index
qualitystringthe video quality being played by the video player
widthintplayer current width
heightintplayer 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)

ParameterTypeDescription
secondsfloatposition, in seconds, to seek to
autostartbooleantrue 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)

ParameterTypeDescription
volumeintvalue 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)

ParameterTypeDescription
widthintnew width of the player
heightintnew 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.