OggPlayJavascriptAPI

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.

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 error <- 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, an error flag 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.

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
• 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
• retrieveAnnotations will retrieve the annotations for the current movie only

In addition, the following additional functions are available for manipulation of the playlist. These functions are also available when operating in individual movie mode, and reduce to the case of a playlist with only one entry - e.g. getPlaylistLength will return 1.

freezePlayPosition

freezePlayPosition()

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.

= unfreezePlayPosition

unfreezePlayPosition()

See documentation for freezePlayPosition.

getPlaylistLength

To retrieve the length of the playlist:

int length <- getPlaylistLength()

getCurrentPosition

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

int position <- getCurrentPosition()

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 error <- setMovieAt(int position, string url)

This function will return true 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.