OggPlayJavascriptAPI

Introduction

This is a draft API for the OggPlay Firefox plugin.

We want the OggPlay plugin to support both a simple individual movie mode, and a more fully-featured playlist mode. All of the functions supported in individual movie mode are still useful in playlist mode; however additional functions also become useful.

Note that the amount of available information for an internet-cast Ogg stream depends upon the type of server providing that stream. In particular, an apache server with mod-annodex installed provides the following information that is not available for live-streamed or raw file-streamed movies:

• length of the movie
• CMML annotations for the entire movie in advance

Furthermore, mod-annodex provides remote seeking functionality across the entire movie. Hence, Oggplay allows arbitrary seeking on mod-annodex supported movies. On the other hand, raw streams and live streams are only seekable within the region that has already been buffered by the player.

Individual movies

OggPlayState

enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };

These are fairly self-evident: the plugin begins in PAUSED or PLAYING state depending on the settings provided through the params tags, and changes to FINISHED state when the movie finishes playback.

getCurrentState

To retrieve the state:

int <- getCurrentState()

pause

pause()

This function will convert the PLAYING or FINISHED states to PAUSED.

play

play()

This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.

restart

restart()

This function will convert any state to PLAYING, and start the movie again from the beginning

getCurrentMovie

To retrieve the currently playing (or just played, or about to play) movie:

string URL <- getCurrentMovie()

setCurrentMovie

To set a new movie:

setCurrentMovie(string URL)

This will automatically begin playing at the beginning if the state is PLAYING or FINISHED, but will remain paused ready to play at the beginning if the state is PAUSED.

getPlayPosition

To get the current play position (in milliseconds) from the movie:

int milliseconds <- getPlayPosition()

setPlayPosition

To set the current play position (in milliseconds):

boolean success <- setPlayPosition(int milliseconds)

Note that if you set a position past the end of the movie then the result will be a play position at the end of the movie, and the player in FINISHED mode.

Note also that certain servers (e.g. plain Ogg files, no mod-annodex installed, etc.) will prevent seeking from being able to occur past the buffered portion of the file; in this case, false will be returned and the play position will be updated as far forward as possible.

registerCMMLCallback

To have the plugin call a javascript method as each CMML annotation is encountered (i.e. as movie playback reaches the point where the annotation needs to be inserted):

registerCMMLCallback(function callback)

Use null if you want to deregister the callback without setting a new one.

retrieveAnnotations

To retrieve all of the CMML annotations for a movie:

string CMML <- retrieveAnnotations()

Note that this won't return all annotations from some servers, e.g. if mod-annodex is not installed. In this case, you will still be able to retrieve CMML as each annotation is encountered using registerCMMLCallback.

registerEndPlayCallback

To have the plugin call a javascript method when the movie finishes:

registerEndPlayCallback(function callback)

Use null if you want to deregister the callback without setting a new one.

setVolume

setVolume(float volume)

Use this function to set the playback volume. A value of 0.0 is equivalent to muting; a value of 1.0 is maximum volume.

getVolume

float volume <- getVolume()

Use this function to retrieve the current playback volume.

getWindowWidth

int width <- getWindowWidth()

Use this function to retrieve the width of the window in pixels (The width is determined by the Firefox render model)

getWindowHeight

int height <- getWindowHeight()

Use this function to retrieve the height of the window in pixels (The height is determined by the Firefox render model)

getBufferedTime

int milliseconds <- getBufferedTime()

Use this function to determine how many milliseconds of the current movie are buffered for display. Note that this is the amount downloaded past the currently playing point, not just the amount decoded past the currently playing point.

getMovieLength

int milliseconds <- getMovieLength()

Use this function to determine how long in milliseconds a movie is. Note that this value will not be available for some movies, depending on the server. If no value is available, then this function will return a length of -1.

getVersionString

To retrieve a version string:

string version <- getVersionString()

This string will be of the format:

"liboggplay (a.b) Annodex Media Plugin (API x.y)"

Where a.b is the liboggplay version, and x.y is the API version. Once accepted, this API will be version 1.0. Minor changes of the API can add functions but not modify existing functions.

Playlists

If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:

• getCurrentState will not return FINISHED until the last movie in the playlist has completed playback
• restart will start from the beginning of the playlist, not the beginning of the current movie
• getCurrentMovie retrieves the currently playing movie - i.e. the movie at the current playlist position
• setCurrentMovie sets the currently playing movie (and playback will begin from the beginning of the newly set movie, not the beginning of the playlist)
• getPlayPosition and setPlayPosition operate on the playlist as a whole - i.e. if a playlist consists of a 5 second, a 7 second and a 4 second movie, then setPlayPosition(6000) will start playing from 1 second into the 2nd movie. In situations where the size of movies not yet encountered can not be determined (e.g. if mod-annodex is not installed on the server), then false will be returned if setPlayPosition requests a position past the furthest encountered position, and the furthest encountered position will be set.
• retrieveAnnotations will retrieve the annotations for the current movie only
• registerEODCallback will call back at the end of the playlist (i.e. at the end of the last movie) only. Use registerPlaylistCallback to recieve notifications per movie.
• getMovieLength will retrieve the movie length for the current movie only. Use getMovieLengthAt to retrieve he movie length for movies in the playlist that are not currently playing.

Note: The plugin does not actually recognise separate "single movie" and "playlist" modes - instead, single movies are actually just playlists with length 1. The interface has been arranged so that the functions above "just work" for what looks like a single movie mode, but are also useful when multiple movies are inserted into the playlist.

The following additional functions are also available for manipulation of the playlist. These functions are also available when there is only one movie in the playlist, but don't provide much in the way of useful features.

freezePlaylistProgression

freezePlaylistProgression()

This function does not stop the current movie from playing, but does prevent the plugin from progressing to the next movie in the playlist. Use this and unfreezePlayPosition for "atomic" operations on the playlist.

unfreezePlaylistProgression

unfreezePlaylistProgression()

See documentation for freezePlaylistProgression.

registerPlaylistCallback

registerPlaylistCallback(function callback)

Use this function to register a javascript function that will get called by the plugin at the end of each movie in the playlist - i.e. when the playlist changes tracks.

Note: the last track will also trigger a call. In the following circumstance

// there are 3 movies in the playlist
registerPlaylistCallback(callbackA)
registerEODCallback(callbackB)

Then callbackA will be called 3 times, and callbackB will be called once

getPlaylistLength

To retrieve the length of the playlist:

int length <- getPlaylistLength()

getCurrentPlaylistPosition

To retrieve the position in the playlist of the current movie:

int position <- getCurrentPlaylistPosition()

getMovieAt

To get the url of the movie at the specified position (0 is the first position):

string url <- getMovieAt(int position)

This function will return null if the position points to a slot outside the bounds of the playlist.

Remember that getCurrentMovie can be used to retrieve the movie at the current position.

setMovieAt

To set the url of the movie at the specified position (0 is the first position):

boolean success <- setMovieAt(int position, string url)

This function will return false if the position points to a slot outside the bounds of the playlist.

Remember that setCurrentMovie can be used to change the currently playing movie.

appendMovie

To append a movie to the end of the playlist:

appendMovie(string url)

insertMovieBefore

To insert a movie before a specified position in the playlist:

boolean success <- insertMovieBefore(int position, string url)

This function will return false if the position points to a slot outside the bounds of the playlist.

getPlayPositionWithinMovie

int milliseconds <- getPlayPositionWithinMovie()

This function retrieves the play position in milliseconds relative to the beginning of the current movie.

Use getPlayPosition to retrieve the play position relative to the beginning of the playlist.

setPlayPositionWithinMovie

boolean success <- setPlayPositionWithinMovie(int milliseconds)

This function sets the play position in milliseconds relative to the beginning of the current movie.

Use setPlayPosition to set the play position relative to the beginning of the playlist.

retrieveAnnotationsAt

string CMML <- retrieveAnnotationsAt(int position)

This function retrieves the CMML annotations from the movie at the specified position in the playlist. The function will return an empty string in the following cases:

• the movie at this position has no annotation
• the movie at this position is being served from a server that does not support out-of-band annotation retrieval
• the position is not a valid position (i.e. is outside the bounds of the playlist)

getMovieLengthAt

int milliseconds <- getMovieLengthAt(int position)

This function retrieves the length of the movie at the specified position in the playlist. The function will return -1 if the movie length can not be determined.

Suggested modifications

states

add state LOADING and NULL or uninitialized state 

play

 function play()

if current state is NULL set state to LOADING else if already in loading state than a second call to play will force playback of what is available.

when in a LOADING state after hitting play the plug in should use download rate control to predict when we should switch into playing mode. ie if the clip's duration is 60 seconds and after one second we have buffered 10 seconds of the clip we can safely immediately switch to play mode. If after 10 seconds we have downloaded 5 seconds of the clip we should wait until we have buffered 40 seconds as it will take around 40 seconds to download the last 20 seconds of video.

if the clip is a LIVE stream then it will begin playback after a few seconds have been buffered. Controllable by:

 setLiveBuffer(ms) sets the amount of the clip to buffer for a live stream. 

load

 function load() //possible options include NOCACHE (to load from server even if its cached locally) 

a function to begin loading the current clip without playing it back.

getDuration

 get the clips duration 

getBufferedTime

Its unclear if get Buffered time gives you the milliseconds buffered from the beaning of the clip, but thats what it should do. To enable the display of a progress bar for the full clip. Ie getBufferedTime / getDuration

if playing back a live stream it could report amount buffered ahead of current playback point

playlist

loadMovieAt

to start downloading/buffering a clip later in playlist

getBufferedTimeAt

to get the amount which a clip for a clip in the playlist.

Applications Preferences

How much disk space to use to store cached clips. Used for syncing and fast page reload on browser back. Also would be ideal if it looked for response headers that invalidate the cache. default 100megs or maybe use firefox preferences... It should uses last accessed first out cacheting.

• another point of comparison: [1] (e.g. getDuration)