https://wiki.xiph.org/api.php?action=feedcontributions&feedformat=atom&user=ShansXiphWiki - User contributions [en]2026-05-15T03:52:08ZUser contributionsMediaWiki 1.45.1https://wiki.xiph.org/index.php?title=OggPlay&diff=7915OggPlay2007-11-30T01:34:51Z<p>Shans: /* MacOS */</p>
<hr />
<div>== Overview ==<br />
OggPlay is a library designed to allow drop-in playback of Xiph.Org media in an application. OggPlay handles demuxing and decoding, generates timestamps for raw data, maintains synchronisation across multiple streams, and provides a lock-free buffer implementation for easy multithreading.<br />
<br />
An example use of OggPlay library is OggPlay Mozilla Firefox plugin demonstrating how the library can be used to provide Ogg playback in a web browser. OggPlay plugin is implemented through Mozilla NPAPI. The target platforms for the plugin are: Linux/UNIX, Win200x/XP/Vista and MACOSX. The libary as much as the plugin are open source under triple<br />
MPL/GPL/LGPL license. For more details about Mozilla licesing refer to [http://www.mozilla.org/MPL/ Mozilla Code Licensing].<br />
<br />
OggPlay is a '''work in progress''': the first release should be availably by mid-2007. <br />
<br />
OggPlay is located on [http://www.annodex.net Annodex], which has been moved in March over to the Xiph.Org servers. SVN access to the source code is available through http://svn.annodex.net/liboggplay/trunk.<br />
<br />
== Developer's Guide ==<br />
<br />
=== Linux ===<br />
<br />
For instructions how to compile and install Linux version of OggPlay Mozilla plugin refer to [http://wiki.xiph.org/index.php/OggPlay/Linux Linux Developement and Intallation Guide].<br />
<br />
=== Windows ===<br />
<br />
The Win32 version of the plugin has been developed and tested on Win200x/XP platforms.<br />
<br />
For detailed instructions how to setup Mozilla plugin development environment and start hacking on Win32 version of OggPlay Mozilla Firefox plugin go to [http://wiki.xiph.org/index.php/OggPlay/Win32 Win32 Development and Installation Guide.]<br />
<br><br />
The same link provides links to the plugin binaries and instructions how to install and test Oggplay Mozilla plugin.<br />
<br />
=== MacOS ===<br />
<br />
Check out http://svn.annodex.net/liboggplay/trunk/plugin/mac/mac-annodex-dev-install.sh, put it in a working directory somewhere, run the script, and follow the directions.<br />
<br />
== Plugin Javascript API ==<br />
<br />
View the [[OggPlayJavascriptAPI | draft OggPlay plugin Javascript API]]</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6705OggPlayJavascriptAPI2007-05-16T01:20:14Z<p>Shans: </p>
<hr />
<div>== Introduction ==<br />
<br />
This is a '''draft API''' for the OggPlay Firefox plugin.<br />
<br />
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.<br />
<br />
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:<br />
* length of the movie<br />
* CMML annotations for the entire movie in advance<br />
<br />
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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
=== registerEndPlayCallback ===<br />
<br />
To have the plugin call a javascript method when the movie finishes:<br />
<br />
registerEndPlayCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== setVolume ===<br />
<br />
setVolume(float volume)<br />
<br />
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.<br />
<br />
=== getVolume ===<br />
<br />
float volume <- getVolume()<br />
<br />
Use this function to retrieve the current playback volume.<br />
<br />
=== getWindowWidth ===<br />
<br />
int width <- getWindowWidth()<br />
<br />
Use this function to retrieve the width of the window in pixels (The width is determined by the Firefox render model)<br />
<br />
=== getWindowHeight ===<br />
<br />
int height <- getWindowHeight()<br />
<br />
Use this function to retrieve the height of the window in pixels (The height is determined by the Firefox render model)<br />
<br />
=== getBufferedTime ===<br />
<br />
int milliseconds <- getBufferedTime()<br />
<br />
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.<br />
<br />
=== getMovieLength ===<br />
<br />
int milliseconds <- getMovieLength()<br />
<br />
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.<br />
<br />
=== getVersionString ===<br />
<br />
To retrieve a version string:<br />
<br />
string version <- getVersionString()<br />
<br />
This string will be of the format:<br />
<br />
"liboggplay (a.b) Annodex Media Plugin (API x.y)"<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
* <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.<br />
* <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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== registerPlaylistCallback ===<br />
<br />
registerPlaylistCallback(function callback)<br />
<br />
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.<br />
<br />
'''Note:''' the last track will also trigger a call. In the following circumstance<br />
<br />
// there are 3 movies in the playlist<br />
registerPlaylistCallback(callbackA)<br />
registerEODCallback(callbackB)<br />
<br />
Then <tt>callbackA</tt> will be called 3 times, and <tt>callbackB</tt> will be called once<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
=== getMovieLengthAt ===<br />
<br />
int milliseconds <- getMovieLengthAt(int position)<br />
<br />
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.<br />
<br />
= Suggested modifications =<br />
<br />
* another point of comparison: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6704OggPlayJavascriptAPI2007-05-16T01:14:42Z<p>Shans: </p>
<hr />
<div>== Introduction ==<br />
<br />
This is a '''draft API''' for the OggPlay Firefox plugin.<br />
<br />
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.<br />
<br />
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:<br />
* length of the movie<br />
* CMML annotations for the entire movie in advance<br />
<br />
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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
=== registerEODCallback ===<br />
<br />
To have the plugin call a javascript method when the movie finishes:<br />
<br />
registerEODCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== setVolume ===<br />
<br />
setVolume(float volume)<br />
<br />
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.<br />
<br />
=== getVolume ===<br />
<br />
float volume <- getVolume()<br />
<br />
Use this function to retrieve the current playback volume.<br />
<br />
=== getWindowWidth ===<br />
<br />
int width <- getWindowWidth()<br />
<br />
Use this function to retrieve the width of the window in pixels (The width is determined by the Firefox render model)<br />
<br />
=== getWindowHeight ===<br />
<br />
int height <- getWindowHeight()<br />
<br />
Use this function to retrieve the height of the window in pixels (The height is determined by the Firefox render model)<br />
<br />
=== getBufferedTime ===<br />
<br />
int milliseconds <- getBufferedTime()<br />
<br />
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.<br />
<br />
=== getMovieLength ===<br />
<br />
int milliseconds <- getMovieLength()<br />
<br />
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.<br />
<br />
=== getVersionString ===<br />
<br />
To retrieve a version string:<br />
<br />
string version <- getVersionString()<br />
<br />
This string will be of the format:<br />
<br />
"liboggplay (a.b) Annodex Media Plugin (API x.y)"<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
* <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.<br />
* <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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== registerPlaylistCallback ===<br />
<br />
registerPlaylistCallback(function callback)<br />
<br />
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.<br />
<br />
'''Note:''' the last track will also trigger a call. In the following circumstance<br />
<br />
// there are 3 movies in the playlist<br />
registerPlaylistCallback(callbackA)<br />
registerEODCallback(callbackB)<br />
<br />
Then <tt>callbackA</tt> will be called 3 times, and <tt>callbackB</tt> will be called once<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
=== getMovieLengthAt ===<br />
<br />
int milliseconds <- getMovieLengthAt(int position)<br />
<br />
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.<br />
<br />
= Suggested modifications =<br />
<br />
* another point of comparison: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6703OggPlayJavascriptAPI2007-05-16T01:00:29Z<p>Shans: </p>
<hr />
<div>== Introduction ==<br />
<br />
This is a '''draft API''' for the OggPlay Firefox plugin.<br />
<br />
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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
=== registerEODCallback ===<br />
<br />
To have the plugin call a javascript method when the movie finishes:<br />
<br />
registerEODCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== setVolume ===<br />
<br />
setVolume(float volume)<br />
<br />
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.<br />
<br />
=== getVolume ===<br />
<br />
float volume <- getVolume()<br />
<br />
Use this function to retrieve the current playback volume.<br />
<br />
=== getWindowWidth ===<br />
<br />
int width <- getWindowWidth()<br />
<br />
Use this function to retrieve the width of the window in pixels (The width is determined by the Firefox render model)<br />
<br />
=== getWindowHeight ===<br />
<br />
int height <- getWindowHeight()<br />
<br />
Use this function to retrieve the height of the window in pixels (The height is determined by the Firefox render model)<br />
<br />
=== getBufferedTime ===<br />
<br />
int milliseconds <- getBufferedTime()<br />
<br />
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.<br />
<br />
=== getMovieLength ===<br />
<br />
int milliseconds <- getMovieLength()<br />
<br />
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.<br />
<br />
=== getVersionString ===<br />
<br />
To retrieve a version string:<br />
<br />
string version <- getVersionString()<br />
<br />
This string will be of the format:<br />
<br />
"liboggplay (a.b) Annodex Media Plugin (API x.y)"<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
* <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.<br />
* <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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== registerPlaylistCallback ===<br />
<br />
registerPlaylistCallback(function callback)<br />
<br />
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.<br />
<br />
'''Note:''' the last track will also trigger a call. In the following circumstance<br />
<br />
// there are 3 movies in the playlist<br />
registerPlaylistCallback(callbackA)<br />
registerEODCallback(callbackB)<br />
<br />
Then <tt>callbackA</tt> will be called 3 times, and <tt>callbackB</tt> will be called once<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
=== getMovieLengthAt ===<br />
<br />
int milliseconds <- getMovieLengthAt(int position)<br />
<br />
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.<br />
<br />
= Suggested modifications =<br />
<br />
* another point of comparison: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)<br />
<br />
== mdale's email ==<br />
<br />
* getVideoLength calls<br />
<br />
* live vs onDemand streams</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6702OggPlayJavascriptAPI2007-05-16T00:56:25Z<p>Shans: </p>
<hr />
<div>== Introduction ==<br />
<br />
This is a '''draft API''' for the OggPlay Firefox plugin.<br />
<br />
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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
=== registerEODCallback ===<br />
<br />
To have the plugin call a javascript method when the movie finishes:<br />
<br />
registerEODCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== setVolume ===<br />
<br />
setVolume(float volume)<br />
<br />
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.<br />
<br />
=== getVolume ===<br />
<br />
float volume <- getVolume()<br />
<br />
Use this function to retrieve the current playback volume.<br />
<br />
=== getWindowWidth ===<br />
<br />
int width <- getWindowWidth()<br />
<br />
Use this function to retrieve the width of the window in pixels (The width is determined by the Firefox render model)<br />
<br />
=== getWindowHeight ===<br />
<br />
int height <- getWindowHeight()<br />
<br />
Use this function to retrieve the height of the window in pixels (The height is determined by the Firefox render model)<br />
<br />
=== getBufferedTime<br />
<br />
int milliseconds <- getBufferedTime()<br />
<br />
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.<br />
<br />
=== getVersionString ===<br />
<br />
To retrieve a version string:<br />
<br />
string version <- getVersionString()<br />
<br />
This string will be of the format:<br />
<br />
"liboggplay (a.b) Annodex Media Plugin (API x.y)"<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
* <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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== registerPlaylistCallback ===<br />
<br />
registerPlaylistCallback(function callback)<br />
<br />
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.<br />
<br />
'''Note:''' the last track will also trigger a call. In the following circumstance<br />
<br />
// there are 3 movies in the playlist<br />
registerPlaylistCallback(callbackA)<br />
registerEODCallback(callbackB)<br />
<br />
Then <tt>callbackA</tt> will be called 3 times, and <tt>callbackB</tt> will be called once<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
= Suggested modifications =<br />
<br />
* another point of comparison: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)<br />
<br />
== mdale's email ==<br />
<br />
* calls to get the buffered state or how much of a given clip is buffered<br />
<br />
* getVideoLength calls<br />
<br />
* live vs onDemand streams</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6692OggPlayJavascriptAPI2007-05-15T06:05:06Z<p>Shans: </p>
<hr />
<div>== Introduction ==<br />
<br />
This is a '''draft API''' for the OggPlay Firefox plugin.<br />
<br />
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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
=== registerEODCallback ===<br />
<br />
To have the plugin call a javascript method when the movie finishes:<br />
<br />
registerEODCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== setVolume ===<br />
<br />
setVolume(float volume)<br />
<br />
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.<br />
<br />
=== getVolume ===<br />
<br />
float volume <- getVolume()<br />
<br />
Use this function to retrieve the current playback volume.<br />
<br />
=== getWindowWidth ===<br />
<br />
int width <- getWindowWidth()<br />
<br />
Use this function to retrieve the width of the window in pixels (The width is determined by the Firefox render model)<br />
<br />
=== getWindowHeight ===<br />
<br />
int height <- getWindowHeight()<br />
<br />
Use this function to retrieve the height of the window in pixels (The height is determined by the Firefox render model)<br />
<br />
=== getVersionString ===<br />
<br />
To retrieve a version string:<br />
<br />
string version <- getVersionString()<br />
<br />
This string will be of the format:<br />
<br />
"liboggplay (a.b) Annodex Media Plugin (API x.y)"<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
* <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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== registerPlaylistCallback ===<br />
<br />
registerPlaylistCallback(function callback)<br />
<br />
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.<br />
<br />
'''Note:''' the last track will also trigger a call. In the following circumstance<br />
<br />
// there are 3 movies in the playlist<br />
registerPlaylistCallback(callbackA)<br />
registerEODCallback(callbackB)<br />
<br />
Then <tt>callbackA</tt> will be called 3 times, and <tt>callbackB</tt> will be called once<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
= Suggested modifications =<br />
<br />
* another point of comparison: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)<br />
<br />
== mdale's email ==<br />
<br />
* calls to get the buffered state or how much of a given clip is buffered<br />
<br />
* getVideoLength calls<br />
<br />
* live vs onDemand streams</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6691OggPlayJavascriptAPI2007-05-15T06:02:24Z<p>Shans: </p>
<hr />
<div>== Introduction ==<br />
<br />
This is a '''draft API''' for the OggPlay Firefox plugin.<br />
<br />
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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
=== registerEODCallback ===<br />
<br />
To have the plugin call a javascript method when the movie finishes:<br />
<br />
registerEODCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== setVolume ===<br />
<br />
setVolume(float volume)<br />
<br />
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.<br />
<br />
=== getVolume ===<br />
<br />
float <- getVolume()<br />
<br />
Use this function to retrieve the current playback volume.<br />
<br />
=== getVersionString ===<br />
<br />
To retrieve a version string:<br />
<br />
string version <- getVersionString()<br />
<br />
This string will be of the format:<br />
<br />
"liboggplay (a.b) Annodex Media Plugin (API x.y)"<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
* <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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== registerPlaylistCallback ===<br />
<br />
registerPlaylistCallback(function callback)<br />
<br />
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.<br />
<br />
'''Note:''' the last track will also trigger a call. In the following circumstance<br />
<br />
// there are 3 movies in the playlist<br />
registerPlaylistCallback(callbackA)<br />
registerEODCallback(callbackB)<br />
<br />
Then <tt>callbackA</tt> will be called 3 times, and <tt>callbackB</tt> will be called once<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
= Suggested modifications =<br />
<br />
* another point of comparison: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)<br />
<br />
* volume control<br />
<br />
* query for width and height<br />
<br />
== mdale's email ==<br />
<br />
* calls to get the buffered state or how much of a given clip is buffered<br />
<br />
* getVideoLength calls<br />
<br />
* live vs onDemand streams<br />
<br />
* disabling/enabling audio</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6690OggPlayJavascriptAPI2007-05-15T06:00:33Z<p>Shans: </p>
<hr />
<div>== Introduction ==<br />
<br />
This is a '''draft API''' for the OggPlay Firefox plugin.<br />
<br />
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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
=== registerEODCallback ===<br />
<br />
To have the plugin call a javascript method when the movie finishes:<br />
<br />
registerEODCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== getVersionString ===<br />
<br />
To retrieve a version string:<br />
<br />
string version <- getVersionString()<br />
<br />
This string will be of the format:<br />
<br />
"liboggplay (a.b) Annodex Media Plugin (API x.y)"<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
* <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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== registerPlaylistCallback ===<br />
<br />
registerPlaylistCallback(function callback)<br />
<br />
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.<br />
<br />
'''Note:''' the last track will also trigger a call. In the following circumstance<br />
<br />
// there are 3 movies in the playlist<br />
registerPlaylistCallback(callbackA)<br />
registerEODCallback(callbackB)<br />
<br />
Then <tt>callbackA</tt> will be called 3 times, and <tt>callbackB</tt> will be called once<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
= Suggested modifications =<br />
<br />
* ctford: a versionInfo() method like VLC<br />
<br />
* another point of comparison: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)<br />
<br />
* volume control<br />
<br />
* query for width and height<br />
<br />
== mdale's email ==<br />
<br />
* calls to get the buffered state or how much of a given clip is buffered<br />
<br />
* getVideoLength calls<br />
<br />
* live vs onDemand streams<br />
<br />
* disabling/enabling audio</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6689OggPlayJavascriptAPI2007-05-15T04:58:15Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
=== registerEODCallback ===<br />
<br />
To have the plugin call a javascript method when the movie finishes:<br />
<br />
registerEODCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
* <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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== registerPlaylistCallback ===<br />
<br />
registerPlaylistCallback(function callback)<br />
<br />
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.<br />
<br />
'''Note:''' the last track will also trigger a call. In the following circumstance<br />
<br />
// there are 3 movies in the playlist<br />
registerPlaylistCallback(callbackA)<br />
registerEODCallback(callbackB)<br />
<br />
Then <tt>callbackA</tt> will be called 3 times, and <tt>callbackB</tt> will be called once<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
= Suggested modifications =<br />
<br />
* ctford: a versionInfo() method like VLC<br />
<br />
* another point of comparison: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)<br />
<br />
* volume control<br />
<br />
* query for width and height<br />
<br />
== mdale's email ==<br />
<br />
* calls to get the buffered state or how much of a given clip is buffered<br />
<br />
* getVideoLength calls<br />
<br />
* live vs onDemand streams<br />
<br />
* disabling/enabling audio</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6688OggPlayJavascriptAPI2007-05-15T04:45:16Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
=== registerEODCallback ===<br />
<br />
To have the plugin call a javascript method when the movie finishes:<br />
<br />
registerEODCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
* <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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== registerPlaylistCallback ===<br />
<br />
registerPlaylistCallback(function callback)<br />
<br />
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.<br />
<br />
'''Note:''' the last track will also trigger a call. In the following circumstance<br />
<br />
// there are 3 movies in the playlist<br />
registerPlaylistCallback(callbackA)<br />
registerEODCallback(callbackB)<br />
<br />
Then <tt>callbackA</tt> will be called 3 times, and <tt>callbackB</tt> will be called once<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
= Suggested modifications =<br />
<br />
* kfish: a callback to specify what to do when reaching the end of playback (also for change of items)<br />
<br />
* ctford: a versionInfo() method like VLC<br />
<br />
* another point of comparison: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)<br />
<br />
* volume control<br />
<br />
* query for width and height<br />
<br />
== mdale's email ==<br />
<br />
* calls to get the buffered state or how much of a given clip is buffered<br />
<br />
* getVideoLength calls<br />
<br />
* live vs onDemand streams<br />
<br />
* disabling/enabling audio</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6687OggPlayJavascriptAPI2007-05-15T04:44:20Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
=== registerEODCallback ===<br />
<br />
To have the plugin call a javascript method when the movie finishes:<br />
<br />
registerEODCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
* <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.<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== registerPlaylistCallback ===<br />
<br />
registerPlaylistCallback(function callback)<br />
<br />
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.<br />
<br />
'''Note:''' the last track will also trigger a call. In the following circumstance<br />
<br />
// there are 3 movies in the playlist<br />
registerPlaylistCallback(callbackA)<br />
registerEODCallback(callbackB)<br />
<br />
Then <tt>callbackA</tt> will be called 3 times, and <tt>callbackB will be called once</tt><br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
= Suggested modifications =<br />
<br />
* kfish: a callback to specify what to do when reaching the end of playback (also for change of items)<br />
<br />
* ctford: a versionInfo() method like VLC<br />
<br />
* another point of comparison: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)<br />
<br />
* volume control<br />
<br />
* query for width and height<br />
<br />
== mdale's email ==<br />
<br />
* calls to get the buffered state or how much of a given clip is buffered<br />
<br />
* getVideoLength calls<br />
<br />
* live vs onDemand streams<br />
<br />
* disabling/enabling audio</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6686OggPlayJavascriptAPI2007-05-15T03:09:03Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
= Suggested modifications =<br />
<br />
* 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<br />
<br />
* kfish: a callback to specify what to do when reaching the end of playback (also for change of items)<br />
<br />
* ctford: a versionInfo() method like VLC<br />
<br />
* another point of comparison: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)<br />
<br />
* volume control<br />
<br />
* query for width and height<br />
<br />
== mdale's email ==<br />
<br />
* calls to get the buffered state or how much of a given clip is buffered<br />
<br />
* getVideoLength calls<br />
<br />
* live vs onDemand streams<br />
<br />
* disabling/enabling audio</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6663OggPlayJavascriptAPI2007-05-13T13:43:15Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
= Suggested modifications =<br />
<br />
* 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<br />
<br />
* kfish: a callback to specify what to do when reaching the end of playback (also for change of items)<br />
<br />
* ctford: a versionInfo() method like VLC<br />
<br />
* another point of comparison: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)<br />
<br />
* volume control<br />
<br />
* query for width and height</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6662OggPlayJavascriptAPI2007-05-13T13:33:40Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
= Suggested modifications =<br />
<br />
* 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<br />
<br />
* kfish: a callback to specify what to do when reaching the end of playback (also for change of items)<br />
<br />
* ctford: a versionInfo() method like VLC<br />
<br />
* another point of comparison: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)<br />
<br />
* volume control</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6661OggPlayJavascriptAPI2007-05-13T13:15:40Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
= Suggested modifications =<br />
<br />
* 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<br />
<br />
* kfish: a callback to specify what to do when reaching the end of playback (also for change of items)<br />
<br />
* ctford: a versionInfo() method like VLC<br />
<br />
* another point of comparison: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup] (e.g. getDuration)</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6660OggPlayJavascriptAPI2007-05-13T13:15:21Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
= Suggested modifications =<br />
<br />
* 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<br />
<br />
* kfish: a callback to specify what to do when reaching the end of playback (also for change of items)<br />
<br />
* ctford: a versionInfo() method like VLC<br />
<br />
* another point of comparison: [http://mplayerplug-in.cvs.sourceforge.net/mplayerplug-in/mplayerplug-in/DOCS/tech/javascript.txt?view=markup]</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6659OggPlayJavascriptAPI2007-05-13T13:09:48Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
= Suggested modifications =<br />
<br />
* 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<br />
<br />
* kfish: a callback to specify what to do when reaching the end of playback (also for change of items)<br />
<br />
* ctford: a versionInfo() method like VLC</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6658OggPlayJavascriptAPI2007-05-13T13:08:02Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)<br />
<br />
= Suggested modifications =<br />
<br />
* 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<br />
<br />
* kfish: a callback to specify what to do when reaching the end of playback (also for change of items)</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6642OggPlayJavascriptAPI2007-05-11T05:34:34Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
<br />
'''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.<br />
<br />
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.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6641OggPlayJavascriptAPI2007-05-11T05:30:28Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
<br />
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. <tt>getPlaylistLength</tt> will return 1.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlaylistProgression ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6640OggPlayJavascriptAPI2007-05-11T05:30:05Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
<br />
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. <tt>getPlaylistLength</tt> will return 1.<br />
<br />
=== freezePlaylistProgression ===<br />
<br />
freezePlaylistProgression()<br />
<br />
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.<br />
<br />
=== unfreezePlayPosition ===<br />
<br />
unfreezePlaylistProgression()<br />
<br />
See documentation for freezePlaylistProgression.<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6639OggPlayJavascriptAPI2007-05-11T05:24:45Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
<br />
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. <tt>getPlaylistLength</tt> will return 1.<br />
<br />
=== freezePlayPosition ===<br />
<br />
freezePlayPosition()<br />
<br />
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.<br />
<br />
=== unfreezePlayPosition ===<br />
<br />
unfreezePlayPosition()<br />
<br />
See documentation for freezePlayPosition.<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPlaylistPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPlaylistPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6638OggPlayJavascriptAPI2007-05-11T04:56:23Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean success <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie<br />
* <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)<br />
* <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.<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
<br />
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. <tt>getPlaylistLength</tt> will return 1.<br />
<br />
=== freezePlayPosition ===<br />
<br />
freezePlayPosition()<br />
<br />
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.<br />
<br />
=== unfreezePlayPosition ===<br />
<br />
unfreezePlayPosition()<br />
<br />
See documentation for freezePlayPosition.<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean success <- setMovieAt(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.<br />
<br />
=== appendMovie ===<br />
<br />
To append a movie to the end of the playlist:<br />
<br />
appendMovie(string url)<br />
<br />
=== insertMovieBefore ===<br />
<br />
To insert a movie before a specified position in the playlist:<br />
<br />
boolean success <- insertMovieBefore(int position, string url)<br />
<br />
This function will return false if the position points to a slot outside the bounds of the playlist.<br />
<br />
=== getPlayPositionWithinMovie ===<br />
<br />
int milliseconds <- getPlayPositionWithinMovie()<br />
<br />
This function retrieves the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.<br />
<br />
=== setPlayPositionWithinMovie ===<br />
<br />
boolean success <- setPlayPositionWithinMovie(int milliseconds)<br />
<br />
This function sets the play position in milliseconds relative to the beginning of the current movie.<br />
<br />
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.<br />
<br />
=== retrieveAnnotationsAt ===<br />
<br />
string CMML <- retrieveAnnotationsAt(int position)<br />
<br />
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:<br />
<br />
* the movie at this position has no annotation<br />
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval<br />
* the position is not a valid position (i.e. is outside the bounds of the playlist)</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6637OggPlayJavascriptAPI2007-05-11T04:44:29Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean error <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie<br />
* <tt>getCurrentMovie</tt> retrieves the currently playing movie<br />
* <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)<br />
* <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<br />
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only<br />
<br />
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. <tt>getPlaylistLength</tt> will return 1.<br />
<br />
=== freezePlayPosition ===<br />
<br />
freezePlayPosition()<br />
<br />
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.<br />
<br />
=== unfreezePlayPosition ==<br />
<br />
unfreezePlayPosition()<br />
<br />
See documentation for freezePlayPosition.<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getCurrentPosition ===<br />
<br />
To retrieve the position in the playlist of the current movie:<br />
<br />
int position <- getCurrentPosition()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position (0 is the first position):<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
This function will return null if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>getCurrentMovie</tt> can be used to retrieve the movie at the current position.<br />
<br />
=== setMovieAt ===<br />
<br />
To set the url of the movie at the specified position (0 is the first position):<br />
<br />
boolean error <- setMovieAt(int position, string url)<br />
<br />
This function will return true if the position points to a slot outside the bounds of the playlist.<br />
<br />
Remember that <tt>setCurrentMovie</tt> can be used to change the currently playing movie.</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6636OggPlayJavascriptAPI2007-05-11T04:35:55Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean error <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback<br />
* restart will start from the beginning of the playlist, not the beginning of the current movie<br />
* getCurrentMovie retrieves the currently playing movie<br />
* setCurrentMovie sets the currently playing movie (and playback will begin from the beginning of the newly set movie, not the beginning of the playlist)<br />
* 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<br />
* retrieveAnnotations will retrieve the annotations for the current movie only<br />
<br />
In addition, the following additional functions are available for manipulation of the playlist<br />
<br />
=== freezePlayPosition ===<br />
<br />
freezePlayPosition()<br />
<br />
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.<br />
<br />
=== unfreezePlayPosition ==<br />
<br />
unfreezePlayPosition()<br />
<br />
See documentation for freezePlayPosition.<br />
<br />
=== getPlaylistLength ===<br />
<br />
To retrieve the length of the playlist:<br />
<br />
int length <- getPlaylistLength()<br />
<br />
=== getMovieAt ===<br />
<br />
To get the url of the movie at the specified position:<br />
<br />
string url <- getMovieAt(int position)<br />
<br />
Remember that</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6635OggPlayJavascriptAPI2007-05-11T03:59:07Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean error <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:<br />
<br />
* getCurrentState will not return FINISHED until the last movie in the playlist has completed playback<br />
* restart will start from the beginning of the playlist, not the beginning of the current movie<br />
* getCurrentMovie retrieves the currently playing movie<br />
* setCurrentMovie sets the currently playing movie (and playback will begin from the beginning of the newly set movie, not the beginning of the playlist)<br />
* 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<br />
* retrieveAnnotations will retrieve the annotations for the current movie only</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6634OggPlayJavascriptAPI2007-05-11T03:51:02Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean error <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAnnotations ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAnnotations()<br />
<br />
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.<br />
<br />
== Playlists ==<br />
<br />
If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6633OggPlayJavascriptAPI2007-05-11T03:49:14Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean error <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.<br />
<br />
=== registerCMMLCallback ===<br />
<br />
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):<br />
<br />
registerCMMLCallback(function callback)<br />
<br />
Use null if you want to deregister the callback without setting a new one.<br />
<br />
=== retrieveAllCMML ===<br />
<br />
To retrieve all of the CMML annotations for a movie:<br />
<br />
string CMML <- retrieveAllCMML()<br />
<br />
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.</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6632OggPlayJavascriptAPI2007-05-11T02:07:21Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.<br />
<br />
=== getPlayPosition ===<br />
<br />
To get the current play position (in milliseconds) from the movie:<br />
<br />
int milliseconds <- getPlayPosition()<br />
<br />
=== setPlayPosition ===<br />
<br />
To set the current play position (in milliseconds):<br />
<br />
boolean error <- setPlayPosition(int milliseconds)<br />
<br />
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.<br />
<br />
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.</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlayJavascriptAPI&diff=6631OggPlayJavascriptAPI2007-05-11T01:59:37Z<p>Shans: </p>
<hr />
<div>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.<br />
<br />
== Individual movies ==<br />
<br />
=== OggPlayState ===<br />
<br />
enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };<br />
<br />
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.<br />
<br />
=== getCurrentState ===<br />
<br />
To retrieve the state:<br />
<br />
int <- getCurrentState()<br />
<br />
=== pause ===<br />
<br />
pause()<br />
<br />
This function will convert the PLAYING or FINISHED states to PAUSED.<br />
<br />
=== play ===<br />
<br />
play()<br />
<br />
This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.<br />
<br />
=== restart ===<br />
<br />
restart()<br />
<br />
This function will convert any state to PLAYING, and start the movie again from the beginning<br />
<br />
=== getCurrentMovie ===<br />
<br />
To retrieve the currently playing (or just played, or about to play) movie:<br />
<br />
string URL <- getCurrentMovie()<br />
<br />
=== setCurrentMovie ===<br />
<br />
To set a new movie:<br />
<br />
setCurrentMovie(string URL)<br />
<br />
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.</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlay&diff=6630OggPlay2007-05-11T01:46:46Z<p>Shans: </p>
<hr />
<div>OggPlay is a library designed to allow drop-in playback of Xiph.Org media in an application. OggPlay handles demuxing and decoding, generates timestamps for raw data, maintains synchronisation across multiple streams, and provides a lock-free buffer implementation for easy multithreading.<br />
<br />
OggPlay is a '''work in progress''': the first release should be availably by mid-2007.<br />
<br />
OggPlay is currently hosted by [http://www.annodex.net Annodex], although there are plans to move hosting over to the Xiph.Org servers. SVN access is available through http://svn.annodex.net/liboggplay/trunk.<br />
<br />
View the [[OggPlayJavascriptAPI | draft OggPlay plugin Javascript API]]</div>Shanshttps://wiki.xiph.org/index.php?title=Summer_of_Code_2008&diff=6487Summer of Code 20082007-03-20T08:00:56Z<p>Shans: /* Ogg and Annodex integration into open source web Content Management Systems */</p>
<hr />
<div>== Current Ideas ==<br />
<br />
This is our ideas page for [http://code.google.com/soc/ Google Summer of Code] projects with [http://xiph.org Xiph.org] and [http://annodex.net/ Annodex]. The two projects are participating jointly this year under Xiph's name.<br />
<br />
We need a primary and backup mentor volunteer for any project that is to become an official proposal, but submit something and we'll see who we can round up. :)<br />
<br />
note: Google Summer of Code 2007, mentoring organizations to apply between March 5 and March 12, students March 14 - March 24<br />
<br />
'''Students''' please use the template at [[Summer of Code Applications]] when applying for a GSoC position.<br />
<br />
'''Mentors''' for details of our mentor application and plan, please see [[Summer of Code 2007]].<br />
<br />
Students should also check out projects related to the [http://wiki.elphel.com/index.php?title=SoC Elphel Open Source cameras].<br />
<br />
=== Optimize Theora encoding/decoding speed, SSE/SSE2 ===<br />
Work on MMX, SSE/SSE2 implementations of the crucial encoding and<br />
decoding elements in [http://svn.xiph.org/trunk/theora/ libtheora] and/or [http://svn.xiph.org/trunk/theora-exp theora-exp].<br />
This could include porting the vp3 mmx and altivec code to the libtheora decoder, and writing sse improvements on the<br />
mmx work that has already been done. The results must still build cleanly on other archs and do <br />
run-time capability detection.<br />
<br />
You could start improving this [http://lists.xiph.org/pipermail/theora-dev/2005-August/002838.html MMX loop filter patch for theora-exp] that was never completed nor merged in current theora-exp (see all list thread).<br />
<br />
''Mentor: Ralph Giles, Timothy Terriberry, backup: Jan Gerber, Mike Smith''<br />
<br />
=== Encode support in theora-exp ===<br />
Implement a rate-distortion optimized encoding mode for [http://svn.xiph.org/trunk/theora-exp/ theora-exp],<br />
including R-D optimzed mode decision and quantization (e.g., constant<br />
lambda). Then, use the above routines to implement a medium-latency ABR<br />
encoding mode (e.g., varying lambda), with a default target buffer size<br />
of approximately 2 seconds.<br />
<br />
''Mentor: Timothy "Derf" Terriberry, backup: Mike Smith, Ralph Giles''<br />
<br />
=== Development assistant for the "Ghost" audio codec ===<br />
Designing a cutting edge perceptual codec is a very daunting task. Xiph<br />
is in the research stage on a new low-latency, general purpose audio codec,<br />
code-named "Ghost". This is basically a "code assistant" position, where you<br />
will be asked to implement, test, and give feedback on ideas from Christopher<br />
Montgomery, designer of the Ogg Vorbis format. Be prepared to learn a lot about<br />
audio coding, or apply what you already know. While there's less "ownership"<br />
potential in this project proposal, it will be a great opportunity to learn<br />
about compression algorithm design, practice your programming chops, and learn<br />
to work in team.<br />
<br />
''Mentor: Christopher "Monty" Montgomery, backup: Jean-Marc Valin''<br />
<br />
=== OggMNG implementation ===<br />
Implement the OggMNG decode support in [http://gstreamer.freedesktop.org/dev/ gstreamer] and/or [http://www.illiminable.com/ogg/ illi's dshow filters].<br />
Implement encoding support in based on [http://www.advogato.org/person/company/diary.html?start=18 byzanz] or [http://live.gnome.org/Istanbul Istanbul]. Bonus points for<br />
overlay support. Details on the OggMNG specifications [http://wiki.xiph.org/index.php/OggMNG here]<br />
<br />
''Mentors: Mike Smith, Ralph Giles''<br />
<br />
=== Theora reference encoder quality optimization ===<br />
The [http://theora.org/download.html libtheora] encoder could make more use of some features present in the spec<br />
but not currently implemented in the encoder. This is a little open ended, but<br />
suggestions are: quant matrix tuning, per-block qi choice, 4:2:2 and 4:4:4 chroma<br />
support.<br />
<br />
''Mentor: Ralph Giles, backup: Timothy Terriberry''<br />
<br />
=== Subtitle Definition ===<br />
There has been a long-standing need for the introduction of subtitles into Ogg. Several means have been suggested and various implementations exist. However, there has been no standard way that is supported by Xiph at this stage.<br />
<br />
The [http://annodex.net/TR/draft-pfeiffer-cmml-03.html CMML] format with its time-aligned means of interleaving text into Ogg bitstreams is a platform on which we would very much like to define a standard means of including subtitles.<br />
<br />
In this project, a standard means of interleaving subtitles (as found on DVDs or in srt files) into Ogg will be defined using CMML.<br />
<br />
The project requires to make changes to the CMML definition and extend it in several ways. CMML needs to have a valid XML schema or DTD definition associated with it, so that standard XML tools will parse it. The associated documentation should then be updated and software written to put e.g. a srt file into CMML inside Ogg. If there is enough time, it would also be good to implement support for this format in a media player such as vlc or mplayer or xine.<br />
<br />
''Mentor: Silvia Pfeiffer, backup: Conrad Parker''<br />
<br />
=== Theora support in ekiga ===<br />
Implement support for Theora as a video codec in the [http://www.gnomemeeting.org/ ekiga] chat application.<br />
Overlaps with [http://live.gnome.org/SummerOfCode2006/Ideas GNOME].<br />
<br />
''Mentor: Ralph Giles''<br />
<br />
=== MXF support in gstreamer ===<br />
Implement an [http://www.digitalpreservation.gov/formats/fdd/fdd000013.shtml MXF] mux/demux for [http://gstreamer.freedesktop.org/dev/ gstreamer], with mappings for [http://xiph.org/vorbis/ Vorbis] and [http://xiph.org/theora Theora].<br />
<br />
''Mentors: Christian Schaller, Mike Smith''<br />
<br />
=== Cascading Style Sheet support for CMML in GStreamer ===<br />
<br />
Implement support for [http://www.w3.org/Style/CSS/ Cascading Style Sheets] to add styling and positioning hints to<br />
[http://annodex.net/TR/draft-pfeiffer-cmml-03.html CMML] text overlays on [http://xiph.org/theora Theora] video. Doing so allows for advanced titling features visually similar to TV-style news headlines, sports scores, and scrolling text. The advantage over conventional "burnt-in" titling is that the stylesheet-driven approach is machine-readable, allowing indexing for search and improved accessibility.<br />
<br />
The project involves:<br />
# YUV compositing support in the [http://gstreamer.freedesktop.org/data/doc/gstreamer/0.10.1/gst-plugins-base-plugins/html/gst-plugins-base-plugins-textoverlay.html textoverlay] plugin in [http://gstreamer.freedesktop.org/dev/ gstreamer] in order to complete the low-level support for color and font attributes. Textoverlay already includes partial support for [http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html pango text], but lacks the necessary colorspace conversions. This portion of the project necessarily involves C programming.<br />
# Implementation of a test application to playback video marked up with CSS titling hints. It is recommended that this portion of the project be implemented in a higher-level language for which GStreamer support and CSS parsing libraries exist, such as Python, Ruby or Haskell.<br />
<br />
Further work could include support for style sheets in liboggplay / Firefox, or direct support for style sheet retrieval and rendering in GStreamer (via the [http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-good-plugins/html/gst-plugins-good-plugins-cmmldec.html cmmldec] plugin and/or a new style-sheet-aware textoverlay plugin).<br />
<br />
''Mentor: Conrad Parker, backup: Mike Smith, Silvia Pfeiffer''<br />
<br />
=== Hardware implementation of Theora decoding ===<br />
Working on a hardware theora decoder, that can be used in embedded<br />
devices, dvd players and video pods. Presumedly GPL verilog source<br />
to run on an FPGA. See http://sourceforge.net/projects/elphel/ for a rough encoder implementation. This was a successful project in 2006.<br />
<br />
=== Intel to AT&T x86 assembly translation ===<br />
There is a general need for cross platform projects to be able to compile the same asm accelleration code on both GCC and MSVC. Unfortunately, at least of x86, they have incompatible assembly formats. Currently people either convert one to the other by hand (a maintenance nightmare) or require an external compile/assemble step on one or the other platform.<br />
<br />
Start with the (unmaintained?) [http://www.niksula.hut.fi/~mtiihone/intel2gas/ intel2gas] script. Spruce it up to support all of recent MMX, SSE, SSE2, SSE3 instructions. Then implement the reverse translation. Once both are working, write some glue code so it can be easily used as part of a GNU autotools build to derive one set of source from the other at build or package time.<br />
<br />
=== Speex and FLAC encoders in Xiph QuickTime Components ===<br />
Implement Speex and FLAC [http://developer.apple.com/documentation/MusicAudio/Reference/CoreAudio/index.html Core Audio] encoders.<br />
<br />
[http://xiph.org/quicktime/ XiphQT] has a Vorbis encoder component that could be used as a reference and starting point.<br />
<br />
''Mentor: Arek Korbik''<br />
<br />
=== New vocoder for Speex ===<br />
Speex currently has a very low bit-rate (2.15 kbps) mode that is implemented as a trivial vocoder. This mode has four "reserved" bits per frame, which means it would be possible to transmit more information. The idea of this project would be to make use of these bits to improve the quality of the 2.15 kbps mode. Changes to both the encoder and the decoder are allowed, provided that they are compatible with older version. This means that the new bit-stream should be decodable by the old decoder with only minor loss in quality. This still leaves plenty of room for improvement. Requires signal processing knowledge.<br />
<br />
''Mentor: Jean-Marc Valin''<br />
<br />
=== New Speex VAD/VBR code ===<br />
The current Speex VAD/VBR code is a quick hack, put together a long time ago. This project would consist of rewriting it to perform much better under all kinds of conditions. Requires signal processing knowledge.<br />
<br />
''Mentor: Jean-Marc Valin''<br />
<br />
<br />
=== rehuff: a tool to losslessly compress Vorbis files ===<br />
Would be nice to have an updated version of "rehuff", a tool to losslessly compress Vorbis files. There were an experimental version of it (see [http://lists.xiph.org/pipermail/vorbis-dev/2006-August/018522.html rehuff status]), but had some limits:<br />
* it's not free software;<br />
* it has a bug causing the rehuffed file can't correctly seek;<br />
* it works only with stereo files.<br />
<br />
Would be nice to have an updated rehuff, without the previous limits, and with a library part that will be included in libvorbisenc, so all encoders could use it (rehuff binary, oggenc, ...).<br />
''Not an official Xiph.org project, only a user proposed idea.''<br />
<br />
=== Ogg and Annodex integration into open source web Content Management Systems ===<br />
The goal of this project is to make the use of ogg theora video in existing CMSs as easy as possible. <br />
The project would consist of integrating in browser playback and structured cmml metadata into existing CMSs like mediaWiki, drupal or wordpress. <br />
<br />
In browser playback support will be handled by vlc or java cortado plugin and then liboggplay & native browser decoding as that project matures. [http://metavid.ucsc.edu/wiki/index.php/Mv_embed mv_embed] may be a starting point for client plugin detection. <br />
The extension package should also handle thumbnail generation via mplayer or ffmpeg, and ideally support transcodeing via shell calls to ffmpeg2theora. Meta data attributes for the video in the CMS could be exportable as CMML. (a standardized xml format for tagging continues video)<br />
<br />
''Mentor: Michael Dale'', ''backup: Silvia Pfeiffer''<br />
<br />
=== OggPlay: Time Offset Acceleration ===<br />
<br />
OggPlay is a new library that enables developers to drop ogg media support into applications. OggPlay will be used to implement native Ogg/Annodex support in Firefox, and supports a range of features including playing Oggs provided in TCP streams.<br />
<br />
This project involves adding time offset optimisation support to OggPlay in TCP mode. Upon successful completion, applications will be able to notify the library of "interesting" time regions of the file, either at the current time point or in the past or future. The library in turn will ensure that these regions are pinned in local memory or on disk using a combination of compressed stream and uncompressed frames. If the application later attempts to seek to a pinned time region, then access to the stream at that point will be much faster than other regions.<br />
<br />
Time offset acceleration will be useful to projects such as Annodex, which allows annotation of time regions ('clips') in Ogg, as well as direct access to individual clips over the WWW, URL-based naming of clips, and linking between clips.<br />
<br />
''Mentor: Shane Stephens'', ''backups: Marcin Lubonski, Michael Martin''<br />
<br />
== Guidelines for Applying ==<br />
<br />
Remember that many people will apply to work on the Summer of Code.<br />
<br />
Keep in mind that those of us evaluating your application do not know you, we do not know what kind of <br />
experience you have, we do not know what you have done in the past and we have to pick the best people <br />
suited for a particular task.<br />
<br />
Hence, it is very important that you tell us in your email why you should be considered to implement a <br />
particular project. Please use the application template at [[Summer of Code Applications]] as a starting point.<br />
<br />
== See Also ==<br />
*[[CodingGuidelines]]<br />
*[[MIT approach to design and implementation]]</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlay&diff=6420OggPlay2007-03-06T22:51:11Z<p>Shans: /* OggPlay */</p>
<hr />
<div>OggPlay is a library designed to allow drop-in playback of Xiph.Org media in an application. OggPlay handles demuxing and decoding, generates timestamps for raw data, maintains synchronisation across multiple streams, and provides a lock-free buffer implementation for easy multithreading.<br />
<br />
OggPlay is a '''work in progress''': the first release should be availably by mid-2007.<br />
<br />
Currently, OggPlay is hosted [http://www.annodex.net here], although there are plans to move hosting over to the Xiph.Org servers. SVN access is available through http://svn.annodex.net/liboggplay/trunk.</div>Shanshttps://wiki.xiph.org/index.php?title=OggPlay&diff=6419OggPlay2007-03-06T22:50:46Z<p>Shans: </p>
<hr />
<div>= OggPlay =<br />
<br />
OggPlay is a library designed to allow drop-in playback of Xiph.Org media in an application. OggPlay handles demuxing and decoding, generates timestamps for raw data, maintains synchronisation across multiple streams, and provides a lock-free buffer implementation for easy multithreading.<br />
<br />
OggPlay is a '''work in progress''': the first release should be availably by mid-2007.<br />
<br />
Currently, OggPlay is hosted [http://www.annodex.net here], although there are plans to move hosting over to the Xiph.Org servers. SVN access is available through http://svn.annodex.net/liboggplay/trunk.</div>Shanshttps://wiki.xiph.org/index.php?title=Main_Page&diff=6418Main Page2007-03-06T22:41:04Z<p>Shans: /* Software */</p>
<hr />
<div>In an effort to bring open-source ideals to the world of multimedia the [[Xiph.Org Foundation]] develops a multitude of amazing products. This wiki describes our free and open protocols and software.<br />
<br />
= Demonstrations of Xiph technologies =<br />
<br />
Want to hear or see Xiph in action? These projects are using our codecs, formats, or libraries.<br />
<br />
* [[VorbisStreams]]: Stations streaming with the [[Vorbis]] codec<br />
* [[Games that use Vorbis]]: Games using the Vorbis codec for music or sound effects<br />
* [[VorbisHardware]]: Hardware players using the Vorbis codec<br />
* [[VorbisSoftwarePlayers]]: list of media players with out-of-box support for Ogg Vorbis<br />
* [[List of Theora videos]]: Available videos encoded with [[Theora]]<br />
<br />
= Projects/Formats =<br />
<br />
== Container Formats ==<br />
<br />
* [[Ogg]]: Media container. This is our native format and the recommended container for Xiph codecs.<br />
* [[Ogg Skeleton]]: Skeleton information on all logical content bitstreams in Ogg.<br />
* [[SpeexRTP]]: RTP payload format for voice<br />
* [[VorbisRTP]]: RTP payload format for general audio<br />
* [[TheoraRTP]]: RTP payload format for video<br />
* [[XSPF]]: XML playlist format<br />
<br />
== Codecs ==<br />
<br />
* '''Compressed Audio/Video Codecs:'''<br />
** [[Vorbis]]: Audio codec with a [[Tremor|fixed point decoder]]<br />
** [[Theora]]: Video codec<br />
** [[FLAC]]: Free Lossless Audio Codec<br />
** [[Speex]]: Speech codec<br />
* '''Timed Text/Metadata Codecs:'''<br />
** [[CMML]]: Continuous Media Markup Language, used for [http://www.annodex.net/ Annodex] and subtitles (xine, vlc, gstreamer, and DirectShow support)<br />
<br />
== Software ==<br />
<br />
* '''Software for distributing media'''<br />
** [[Icecast]]: Streaming server<br />
** [[Ices]]: Source client for Icecast servers<br />
<br />
* '''Libraries'''<br />
** [[OggPlay]]: library for synchronised xiph media playback<br />
<br />
* '''Other software'''<br />
** [[OggComponent/VorbisComponent]]: Wrappers to integrate Ogg-Vorbis into Mac OS X (does not yet support encoding)<br />
<br />
== Promotional campaigns/events ==<br />
<br />
*[[MailOgging]]: project that provides templates for anyone willing to contact a company requesting them to add support for Xiph formats.<br />
<br />
== Work in Progress ==<br />
* [[Work In Progress]]: codecs and software still in the research and development stages.<br />
* [[Todo]]: To-do list for various Xiph.Org project.<br />
<br />
= Project management =<br />
<br />
* [[AdminProcesses]]<br />
* [[MonthlyMeeting]]: page with information on Xiph's MonthlyMeeting<br />
* [[MailingLists]]: list of Xiph's mailing lists<br />
* [[Bounties]]: list of bounties that you can take to improve Xiph's projects<br />
* [[HyperFish]]<br />
<br />
= Resources for Video and Audio programmers =<br />
<br />
* [[Ambisonics]]: page with technical information on Ambisonics<br />
* [[Resources and papers on Audio, Music and Speech|Courses and papers on Audio, Music and Speech]]: page with links to MIT and other University's content<br />
<br />
= Wiki internal =<br />
<br />
* [[Sandbox]]: Testbed for testing editing skills<br />
* [[Translations]]: What about some translation work<br />
* [[XiphWiki:Copyrights]]: License used for content on this wiki (i.e. CC-BY-SA)</div>Shans