XiphWiki - User contributions [en]

OggPlayJavascriptAPI

2007-07-09T12:39:18Z

Tahn: Added description for passing callback functions

== 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 [http://www.annodex.net/software/mod_annodex/index.html 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|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|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|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.

=== 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:

* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position
* <tt>setCurrentMovie</tt> sets the currently playing movie (and playback will begin from the beginning of the newly set movie, not the beginning of the playlist)
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only
* <tt>registerEndPlayCallback</tt> will call back at the end of the playlist (i.e. at the end of the last movie) only. Use <tt>registerPlaylistCallback</tt> to receive notifications per movie.
* <tt>getMovieLength</tt> will retrieve the movie length for the current movie only. Use <tt>getMovieLengthAt</tt> 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|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 <tt>getCurrentMovie</tt> 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 <tt>setCurrentMovie</tt> 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.

=== 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|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 =
==Individual Movies==
== 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.

== 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 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: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)

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

OggPlayJavascriptAPI

2007-07-09T12:14:05Z

Tahn: Updated to match the released liboggplay 1.0 api, plus some extra versioning functions that will be added real soon now

== 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 [http://www.annodex.net/software/mod_annodex/index.html 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 the "Callback functions" section 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 the "Callback functions" section 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 the "Callback functions" section for details on setting up a Javascript callback function.''

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

* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position
* <tt>setCurrentMovie</tt> sets the currently playing movie (and playback will begin from the beginning of the newly set movie, not the beginning of the playlist)
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only
* <tt>registerEndPlayCallback</tt> will call back at the end of the playlist (i.e. at the end of the last movie) only. Use <tt>registerPlaylistCallback</tt> to receive notifications per movie.
* <tt>getMovieLength</tt> will retrieve the movie length for the current movie only. Use <tt>getMovieLengthAt</tt> 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 the "Callback functions" section 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 <tt>getCurrentMovie</tt> 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 <tt>setCurrentMovie</tt> 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.

=== 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 the "Callback functions" section 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 ==

(to do)

= Suggested modifications =
==Individual Movies==
== 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.

== 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 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: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)

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

OggPlayJavascriptAPI

2007-06-28T01:59:08Z

Tahn: Added removeMovieAt

== 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 [http://www.annodex.net/software/mod_annodex/index.html 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:

* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position
* <tt>setCurrentMovie</tt> sets the currently playing movie (and playback will begin from the beginning of the newly set movie, not the beginning of the playlist)
* <tt>getPlayPosition</tt> and <tt>setPlayPosition</tt> 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 <tt>setPlayPosition</tt> requests a position past the furthest encountered position, and the furthest encountered position will be set.
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only
* <tt>registerEODCallback</tt> will call back at the end of the playlist (i.e. at the end of the last movie) only. Use <tt>registerPlaylistCallback</tt> to recieve notifications per movie.
* <tt>getMovieLength</tt> will retrieve the movie length for the current movie only. Use <tt>getMovieLengthAt</tt> 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 <tt>callbackA</tt> will be called 3 times, and <tt>callbackB</tt> 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 <tt>getCurrentMovie</tt> 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 <tt>setCurrentMovie</tt> 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.

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

=== getPlayPositionWithinMovie ===

int milliseconds <- getPlayPositionWithinMovie()

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

Use <tt>getPlayPosition</tt> 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 <tt>setPlayPosition</tt> 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 =
==Individual Movies==
== 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.

== 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 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: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)

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