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(string))

See Callback functions for details on setting up a Javascript callback function.

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:

boolean success <- retrieveAnnotations(function callback(string))

See Callback functions for details on setting up a Javascript callback function.

This is an asynchronous call; the plugin will create a new http connection to retrieve the annotations. The callback function will be invoked with the annotation string after the annotations have been retrieved.

This function will return false if a previous attempt at retrieving annotations is still being processed.

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(void))

See Callback functions for details on setting up a Javascript callback function.

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

registerOnMouseClickCallback

To have the plugin call a javascript method when user click in plugin area:

registerOnMouseClickCallback(function callback(void))

See Callback functions for details on setting up a Javascript callback function.

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 human-readable 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.

getPluginVersion

To retrieve a version string for the plugin alone ("a.b"):

string version <- getPluginVersion()

getAPIVersion

To retrieve a version string for the Javascript interface alone ("x.y"):

string version <- getAPIVersion()

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
• 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)
• retrieveAnnotations will retrieve the annotations for the current movie only
• registerEndPlayCallback will call back at the end of the playlist (i.e. at the end of the last movie) only. Use registerPlaylistCallback to receive notifications per movie.
• getMovieLength will retrieve the movie length for the current movie only. Use getMovieLengthAt to retrieve the 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(void))

See Callback functions for details on setting up a Javascript callback function.

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. The last track does not trigger a call; the end play callback, if registered, will be invoked instead.

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

suggested alteration have it be insertMovieBefore(string url, [pos])
so that the pos is optional and if missing just inserts before the current clip in the playlist 

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.

removeMovieAt

To remove a movie from the playlist:

boolean success <- removeMovieAt(int position)

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

playMovieAt

To start playing a movie at a specified position in the playlist:

boolean success <- playMovieAt(int position)

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

playlistNext

To start playing the next movie in the playlist:

boolean success <- playlistNext()

This function will return false if the the current movie is the last one in the playlist.

playlistPrev

To start playing the previous movie in the playlist:

boolean success <- playlistPrev()

This function will return false if the the current movie is the first one in the playlist.

retrieveAnnotationsAt

To retrieve all of the CMML annotations for a movie at a specified position in the playlist:

boolean success <- retrieveAnnotationsAt(int position, function callback(string))

See Callback functions for details on setting up a Javascript callback function.

As per retrieveAnnotations, this function is an asynchronous call and will not return any annotations if the server does not support out-of-band annotation retrieval.

This function will return false if a previous attempt at retrieving annotations is still being processed, or if the position points to a slot outside the bounds of the playlist.

getMovieLengthAt

This is currently unimplemented.

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.

Callback functions

Since Javascript functions are not first-class objects, you can't pass one directly to the plugin as a callback. You need to wrap your callback in an anonymous object with a single member, 'call':

// Use this form for callbacks with a string argument, shown as function callback(string):
plugin.registerCMMLCallback(
  {
    call: function(s) { yourCMLLCallback(s); }
  }
);

// Use this form for callbacks with no arguments, shown as function callback(void):
plugin.registerEndPlayCallback(
  {
    call: function() { yourEndPlayCallback(); }
  }
);

Technically, you can inline your callback handling code directly in the 'call' function, but it's much cleaner to just redirect to a stand-alone function for each callback, as shown above.

Deregistering a callback is quite simple:

plugin.registerPlaylistCallback(null);

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 a user hits play internally we store a separate state that reports as LOADING but is really LOAD_TO_PLAY state which uses 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. In a different instance 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.

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 Buffered 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)

• suggestion: Include audio capture (and Speex encoding) in the API

Kate streams

Kate is a codec carrying text to be overlayed on video, eg as subtitles.

A patch has been sent to the ogg-dev list with the following API:

long getNumKateTracks();

returns the number of Kate tracks found in the current stream.

long getCurrentKateTrack();

returns the index of the currently selected Kate track (-1 if none is)

string getKateTrackLanguage(in long track);

returns the language (eg, "en", or "en_GB") of the trackth Kate track in the current stream (may be empty if none specified in the stream)

string getKateTrackCategory(in long track);

returns the category (eg, "subtitles") of the trackth Kate track in the current stream (may be empty if none specified in the stream)

void selectKateTrack(in long track);

selects the trackth Kate track in the stream, -1 to select no track at all.

void registerKateCallback(in nsILibOggCallbackString callback);

sets a routine to be called with any Kate text from the currently selected track (if any) as its presentation time is reached.

void setKateFont(in string font);

sets the font to use for displaying text (a string, eg "arial"). This should be the name of a font without path and without ".ttf" appended. If such a font isn't found, a default font will be used.

string getKateFont();

returns the font being used - actually, this is what it should do, I just realized it returns the font you requested if you requested one, rather than the default if the requested one isn't found - I'll fix that.

void setKateFontSize(in float relsize);

sets a font size multiplier to be used. The default is to use a font size based on the size of the video, but all fonts do not appear as large with the same "point" size, so this can be used to increase/decrease font size - also useful for people who prefer larger fonts.

float getKateFontSize();

returns the current font size multiplier.

void setKateRendering(in long method);

sets how to render the currently selected Kate stream (if any): 0: do not render anything (if a callback is registered, text will still be sent to it, useful if one wants to not display anything but send the text to text-to-speech) 1: render as text 2: render as overlay (YUV data from liboggplay, not implemented yet)

long getKateRendering();

returns the current render method being used.

I thought of adding a setKateColor/getKateColor pair as well, as different colors would be better for different video backgrounds. Not sure about this.