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

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

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.

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)

Suggested modifications

• ctford: it might make sense to divide the methods up and give them to separate object. the most recent version of the VLC api for example has a playlist, an audio, a video, an input and a log object

• kfish: a callback to specify what to do when reaching the end of playback (also for change of items)

• ctford: a versionInfo() method like VLC

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

• volume control