OggPlayJavascriptAPI

From XiphWiki

(Difference between revisions)
Jump to: navigation, search
m (play: typo)
m (Kate streams)
 
(8 intermediate revisions not shown)
Line 77: Line 77:
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):
To have the plugin call a javascript method as each CMML annotation is encountered (i.e. as movie playback reaches the point where the annotation needs to be inserted):
-
  registerCMMLCallback(function callback)
+
  registerCMMLCallback(function callback(string))
 +
 
 +
''See [[#Callback_functions|Callback functions]] for details on setting up a Javascript callback function.''
Use null if you want to deregister the callback without setting a new one.
Use null if you want to deregister the callback without setting a new one.
Line 85: Line 87:
To retrieve all of the CMML annotations for a movie:
To retrieve all of the CMML annotations for a movie:
-
  string CMML <- retrieveAnnotations()
+
  boolean success <- retrieveAnnotations(function callback(string))
 +
 
 +
''See [[#Callback_functions|Callback functions]] for details on setting up a Javascript callback function.''
 +
 
 +
This is an asynchronous call; the plugin will create a new http connection to retrieve the annotations. The callback function will be invoked with the annotation string after the annotations have been retrieved.
 +
 
 +
This function will return false if a previous attempt at retrieving annotations is still being processed.
Note that this won't return all annotations from some servers, e.g. if mod-annodex is not installed.  In this case, you will still be able to retrieve CMML as each annotation is encountered using registerCMMLCallback.
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.
Line 93: Line 101:
To have the plugin call a javascript method when the movie finishes:
To have the plugin call a javascript method when the movie finishes:
-
  registerEndPlayCallback(function callback)
+
  registerEndPlayCallback(function callback(void))
 +
 
 +
''See [[#Callback_functions|Callback functions]] for details on setting up a Javascript callback function.''
Use null if you want to deregister the callback without setting a new one.
Use null if you want to deregister the callback without setting a new one.
 +
 +
=== registerOnMouseClickCallback ===
 +
 +
To have the plugin call a javascript method when user click in plugin area:
 +
 +
registerOnMouseClickCallback(function callback(void))
 +
 +
''See [[#Callback_functions|Callback functions]] for details on setting up a Javascript callback function.''
 +
=== setVolume ===
=== setVolume ===
Line 135: Line 154:
=== getVersionString ===
=== getVersionString ===
-
To retrieve a version string:
+
To retrieve a human-readable version string:
  string version <- getVersionString()
  string version <- getVersionString()
Line 144: Line 163:
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.
Where a.b is the liboggplay version, and x.y is the API version.  Once accepted, this API will be version 1.0.  Minor changes of the API can add functions but not modify existing functions.
 +
 +
=== getPluginVersion ===
 +
 +
To retrieve a version string for the plugin alone ("a.b"):
 +
 +
string version <- getPluginVersion()
 +
 +
=== getAPIVersion ===
 +
 +
To retrieve a version string for the Javascript interface alone ("x.y"):
 +
 +
string version <- getAPIVersion()
== Playlists ==
== Playlists ==
Line 150: Line 181:
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback
* <tt>getCurrentState</tt> will not return FINISHED until the last movie in the playlist has completed playback
-
* <tt>restart</tt> will start from the beginning of the playlist, not the beginning of the current movie
 
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position
* <tt>getCurrentMovie</tt> retrieves the currently playing movie - i.e. the movie at the current playlist position
* <tt>setCurrentMovie</tt> sets the currently playing movie (and playback will begin from the beginning of the newly set movie, not the beginning of the playlist)
* <tt>setCurrentMovie</tt> sets the currently playing movie (and playback will begin from the beginning of the newly set movie, not the beginning of the playlist)
-
* <tt>getPlayPosition</tt> and <tt>setPlayPosition</tt> operate on the playlist as a whole - i.e. if a playlist consists of a 5 second, a 7 second and a 4 second movie, then setPlayPosition(6000) will start playing from 1 second into the 2nd movie.  In situations where the size of movies not yet encountered can not be determined (e.g. if mod-annodex is not installed on the server), then false will be returned if <tt>setPlayPosition</tt> requests a position past the furthest encountered position, and the furthest encountered position will be set.
 
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only
* <tt>retrieveAnnotations</tt> will retrieve the annotations for the current movie only
-
* <tt>registerEODCallback</tt> will call back at the end of the playlist (i.e. at the end of the last movie) only.  Use <tt>registerPlaylistCallback</tt> to recieve notifications per movie.
+
* <tt>registerEndPlayCallback</tt> will call back at the end of the playlist (i.e. at the end of the last movie) only.  Use <tt>registerPlaylistCallback</tt> to receive notifications per movie.
-
* <tt>getMovieLength</tt> will retrieve the movie length for the current movie only.  Use <tt>getMovieLengthAt</tt> to retrieve he movie length for movies in the playlist that are not currently playing.
+
* <tt>getMovieLength</tt> will retrieve the movie length for the current movie only.  Use <tt>getMovieLengthAt</tt> to retrieve the length for movies in the playlist that are not currently playing.
'''Note:''' The plugin does not actually recognise separate "single movie" and "playlist" modes - instead, single movies are actually just playlists with length 1.  The interface has been arranged so that the functions above "just work" for what looks like a single movie mode, but are also useful when multiple movies are inserted into the playlist.
'''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.
Line 176: Line 205:
=== registerPlaylistCallback ===
=== registerPlaylistCallback ===
-
  registerPlaylistCallback(function callback)
+
  registerPlaylistCallback(function callback(void))
-
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.
+
''See [[#Callback_functions|Callback functions]] for details on setting up a Javascript callback function.''
-
'''Note:''' the last track will also trigger a call.  In the following circumstance
+
Use this function to register a javascript function that will get called by the plugin at the end of each movie in the playlist - i.e. when the playlist changes tracks. The last track does '''not''' trigger a call; the end play callback, if registered, will be invoked instead.
-
 
+
-
// there are 3 movies in the playlist
+
-
registerPlaylistCallback(callbackA)
+
-
registerEODCallback(callbackB)
+
-
 
+
-
Then <tt>callbackA</tt> will be called 3 times, and <tt>callbackB</tt> will be called once
+
=== getPlaylistLength ===
=== getPlaylistLength ===
Line 227: Line 250:
=== insertMovieBefore ===
=== insertMovieBefore ===
 +
'''suggested alteration''' have it be insertMovieBefore(string url, [pos])
 +
so that the pos is optional and if missing just inserts before the current clip in the playlist
To insert a movie before a specified position in the playlist:
To insert a movie before a specified position in the playlist:
Line 234: Line 259:
This function will return false if the position points to a slot outside the bounds of the playlist.
This function will return false if the position points to a slot outside the bounds of the playlist.
-
=== getPlayPositionWithinMovie ===
+
=== removeMovieAt ===
-
int milliseconds <- getPlayPositionWithinMovie()
+
To remove a movie from the playlist:
-
This function retrieves the play position in milliseconds relative to the beginning of the current movie.
+
boolean success <- removeMovieAt(int position)
-
Use <tt>getPlayPosition</tt> to retrieve the play position relative to the beginning of the playlist.
+
This function will return false if the position points to a slot outside the bounds of the playlist.
 +
 
 +
=== playMovieAt ===
 +
 
 +
To start playing a movie at a specified position in the playlist:
 +
 
 +
boolean success <- playMovieAt(int position)
 +
 
 +
This function will return false if the position points to a slot outside the bounds of the playlist.
 +
 
 +
=== playlistNext ===
 +
 
 +
To start playing the next movie in the playlist:
 +
 
 +
boolean success <- playlistNext()
 +
 
 +
This function will return false if the the current movie is the last one in the playlist.
-
=== setPlayPositionWithinMovie ===
+
=== playlistPrev ===
-
boolean success <- setPlayPositionWithinMovie(int milliseconds)
+
To start playing the previous movie in the playlist:
-
This function sets the play position in milliseconds relative to the beginning of the current movie.
+
boolean success <- playlistPrev()
-
Use <tt>setPlayPosition</tt> to set the play position relative to the beginning of the playlist.
+
This function will return false if the the current movie is the first one in the playlist.
=== retrieveAnnotationsAt ===
=== retrieveAnnotationsAt ===
-
string CMML <- retrieveAnnotationsAt(int position)
+
To retrieve all of the CMML annotations for a movie at a specified position in the playlist:
-
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:
+
boolean success <- retrieveAnnotationsAt(int position, function callback(string))
-
* the movie at this position has no annotation
+
''See [[#Callback_functions|Callback functions]] for details on setting up a Javascript callback function.''
-
* the movie at this position is being served from a server that does not support out-of-band annotation retrieval
+
 
-
* the position is not a valid position (i.e. is outside the bounds of the playlist)
+
As per retrieveAnnotations, this function is an asynchronous call and will not return any annotations if the server does not support out-of-band annotation retrieval.
 +
 
 +
This function will return false if a previous attempt at retrieving annotations is still being processed, or if the position points to a slot outside the bounds of the playlist.
=== getMovieLengthAt ===
=== getMovieLengthAt ===
 +
 +
'''This is currently unimplemented.'''
  int milliseconds <- getMovieLengthAt(int position)
  int milliseconds <- getMovieLengthAt(int position)
This function retrieves the length of the movie at the specified position in the playlist.  The function will return -1 if the movie length can not be determined.
This function retrieves the length of the movie at the specified position in the playlist.  The function will return -1 if the movie length can not be determined.
 +
 +
== Callback functions ==
 +
 +
Since Javascript functions are not first-class objects, you can't pass one directly to the plugin as a callback. You need to wrap your callback in an anonymous object with a single member, 'call':
 +
 +
// Use this form for callbacks with a string argument, shown as ''function callback(string)'':
 +
plugin.registerCMMLCallback(
 +
  {
 +
    call: function(s) { yourCMLLCallback(s); }
 +
  }
 +
);
 +
 +
// Use this form for callbacks with no arguments, shown as ''function callback(void)'':
 +
plugin.registerEndPlayCallback(
 +
  {
 +
    call: function() { yourEndPlayCallback(); }
 +
  }
 +
);
 +
 +
Technically, you can inline your callback handling code directly in the 'call' function, but it's much cleaner to just redirect to a stand-alone function for each callback, as shown above.
 +
 +
Deregistering a callback is quite simple:
 +
 +
plugin.registerPlaylistCallback(null);
= Suggested modifications =
= Suggested modifications =
Line 284: Line 353:
a function to begin loading the current clip without playing it back.  
a function to begin loading the current clip without playing it back.  
-
== getDuration ==
+
 
-
  get the clips duration
+
 
-
+
== getBufferedTime ==
== getBufferedTime ==
Its unclear if get Buffered time gives you the milliseconds buffered from the beaning of the clip, but thats what it should do. To enable the display of a progress bar for the full clip. Ie getBufferedTime / getDuration
Its unclear if get Buffered time gives you the milliseconds buffered from the beaning of the clip, but thats what it should do. To enable the display of a progress bar for the full clip. Ie getBufferedTime / getDuration
Line 307: Line 375:
* suggestion: Include audio capture (and Speex encoding) in the API
* suggestion: Include audio capture (and Speex encoding) in the API
 +
 +
 +
==Kate streams==
 +
 +
[[Kate]] is a codec carrying text to be overlayed on video, eg as subtitles.
 +
 +
A patch has been sent to the ogg-dev list with the following API:
 +
 +
long getNumKateTracks();
 +
 +
returns the number of Kate tracks found in the current stream.
 +
 +
long getCurrentKateTrack();
 +
 +
returns the index of the currently selected Kate track (-1 if none is)
 +
 +
string getKateTrackLanguage(in long track);
 +
 +
returns the language (eg, "en", or "en_GB") of the trackth Kate track
 +
in the current stream
 +
(may be empty if none specified in the stream)
 +
 +
string getKateTrackCategory(in long track);
 +
 +
returns the category (eg, "subtitles") of the trackth Kate track in
 +
the current stream
 +
(may be empty if none specified in the stream)
 +
 +
void selectKateTrack(in long track);
 +
 +
selects the trackth Kate track in the stream, -1 to select no track at all.
 +
 +
void registerKateCallback(in nsILibOggCallbackString callback);
 +
 +
sets a routine to be called with any Kate text from the currently selected track
 +
(if any) as its presentation time is reached.
 +
 +
void setKateFont(in string font);
 +
 +
sets the font to use for displaying text (a string, eg "arial"). This
 +
should be the
 +
name of a font without path and without ".ttf" appended. If such a font isn't
 +
found, a default font will be used.
 +
 +
string getKateFont();
 +
 +
returns the font being used - actually, this is what it should do, I
 +
just realized
 +
it returns the font you requested if you requested one, rather than the default
 +
if the requested one isn't found - I'll fix that.
 +
 +
void setKateFontSize(in float relsize);
 +
 +
sets a font size multiplier to be used. The default is to use a font
 +
size based on
 +
the size of the video, but all fonts do not appear as large with the
 +
same "point"
 +
size, so this can be used to increase/decrease font size - also useful
 +
for people
 +
who prefer larger fonts.
 +
 +
float getKateFontSize();
 +
 +
returns the current font size multiplier.
 +
 +
void setKateRendering(in long method);
 +
 +
sets how to render the currently selected Kate stream (if any):
 +
0: do not render anything (if a callback is registered, text will
 +
still be sent to it,
 +
useful if one wants to not display anything but send the text to
 +
text-to-speech)
 +
1: render as text
 +
2: render as overlay (YUV data from liboggplay, not implemented yet)
 +
 +
long getKateRendering();
 +
 +
returns the current render method being used.
 +
 +
 +
I thought of adding a setKateColor/getKateColor pair as well, as different
 +
colors would be better for different video backgrounds. Not sure about this.

Latest revision as of 12:25, 9 May 2008

Contents

Introduction

This is a draft API for the OggPlay Firefox plugin.

We want the OggPlay plugin to support both a simple individual movie mode, and a more fully-featured playlist mode. All of the functions supported in individual movie mode are still useful in playlist mode; however additional functions also become useful.

Note that the amount of available information for an internet-cast Ogg stream depends upon the type of server providing that stream. In particular, an Apache server with mod_annodex installed provides the following information that is not available for live-streamed or raw file-streamed movies:

  • length of the movie
  • CMML annotations for the entire movie in advance

Furthermore, mod_annodex provides remote seeking functionality across the entire movie. Hence, OggPlay allows arbitrary seeking on mod_annodex supported movies. On the other hand, raw streams and live streams are only seekable within the region that has already been buffered by the player.

Individual movies

OggPlayState

enum OggPlayState { PAUSED = 0; PLAYING = 1; FINISHED = 2 };

These are fairly self-evident: the plugin begins in PAUSED or PLAYING state depending on the settings provided through the params tags, and changes to FINISHED state when the movie finishes playback.

getCurrentState

To retrieve the state:

int <- getCurrentState()

pause

pause()

This function will convert the PLAYING or FINISHED states to PAUSED.

play

play()

This function will convert the PAUSED state to PLAYING or FINISHED depending upon the current position within the movie.

restart

restart()

This function will convert any state to PLAYING, and start the movie again from the beginning

getCurrentMovie

To retrieve the currently playing (or just played, or about to play) movie:

string URL <- getCurrentMovie()

setCurrentMovie

To set a new movie:

setCurrentMovie(string URL)

This will automatically begin playing at the beginning if the state is PLAYING or FINISHED, but will remain paused ready to play at the beginning if the state is PAUSED.

getPlayPosition

To get the current play position (in milliseconds) from the movie:

int milliseconds <- getPlayPosition()

setPlayPosition

To set the current play position (in milliseconds):

boolean success <- setPlayPosition(int milliseconds)

Note that if you set a position past the end of the movie then the result will be a play position at the end of the movie, and the player in FINISHED mode.

Note also that certain servers (e.g. plain Ogg files, no mod-annodex installed, etc.) will prevent seeking from being able to occur past the buffered portion of the file; in this case, false will be returned and the play position will be updated as far forward as possible.

registerCMMLCallback

To have the plugin call a javascript method as each CMML annotation is encountered (i.e. as movie playback reaches the point where the annotation needs to be inserted):

registerCMMLCallback(function callback(string))

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

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

retrieveAnnotations

To retrieve all of the CMML annotations for a movie:

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

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

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

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

Note that this won't return all annotations from some servers, e.g. if mod-annodex is not installed. In this case, you will still be able to retrieve CMML as each annotation is encountered using registerCMMLCallback.

registerEndPlayCallback

To have the plugin call a javascript method when the movie finishes:

registerEndPlayCallback(function callback(void))

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

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

registerOnMouseClickCallback

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

registerOnMouseClickCallback(function callback(void))

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


setVolume

setVolume(float volume)

Use this function to set the playback volume. A value of 0.0 is equivalent to muting; a value of 1.0 is maximum volume.

getVolume

float volume <- getVolume()

Use this function to retrieve the current playback volume.

getWindowWidth

int width <- getWindowWidth()

Use this function to retrieve the width of the window in pixels (The width is determined by the Firefox render model)

getWindowHeight

int height <- getWindowHeight()

Use this function to retrieve the height of the window in pixels (The height is determined by the Firefox render model)

getBufferedTime

int milliseconds <- getBufferedTime()

Use this function to determine how many milliseconds of the current movie are buffered for display. Note that this is the amount downloaded past the currently playing point, not just the amount decoded past the currently playing point.

getMovieLength

int milliseconds <- getMovieLength()

Use this function to determine how long in milliseconds a movie is. Note that this value will not be available for some movies, depending on the server. If no value is available, then this function will return a length of -1.

getVersionString

To retrieve a human-readable version string:

string version <- getVersionString()

This string will be of the format:

"liboggplay (a.b) Annodex Media Plugin (API x.y)"

Where a.b is the liboggplay version, and x.y is the API version. Once accepted, this API will be version 1.0. Minor changes of the API can add functions but not modify existing functions.

getPluginVersion

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

string version <- getPluginVersion()

getAPIVersion

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

string version <- getAPIVersion()

Playlists

If you wish to use playlists instead of individual movies, then the above function calls still exist, with the following caveats:

  • getCurrentState will not return FINISHED until the last movie in the playlist has completed playback
  • getCurrentMovie retrieves the currently playing movie - i.e. the movie at the current playlist position
  • setCurrentMovie sets the currently playing movie (and playback will begin from the beginning of the newly set movie, not the beginning of the playlist)
  • retrieveAnnotations will retrieve the annotations for the current movie only
  • registerEndPlayCallback will call back at the end of the playlist (i.e. at the end of the last movie) only. Use registerPlaylistCallback to receive notifications per movie.
  • getMovieLength will retrieve the movie length for the current movie only. Use getMovieLengthAt to retrieve the length for movies in the playlist that are not currently playing.

Note: The plugin does not actually recognise separate "single movie" and "playlist" modes - instead, single movies are actually just playlists with length 1. The interface has been arranged so that the functions above "just work" for what looks like a single movie mode, but are also useful when multiple movies are inserted into the playlist.

The following additional functions are also available for manipulation of the playlist. These functions are also available when there is only one movie in the playlist, but don't provide much in the way of useful features.

freezePlaylistProgression

freezePlaylistProgression()

This function does not stop the current movie from playing, but does prevent the plugin from progressing to the next movie in the playlist. Use this and unfreezePlayPosition for "atomic" operations on the playlist.

unfreezePlaylistProgression

unfreezePlaylistProgression()

See documentation for freezePlaylistProgression.

registerPlaylistCallback

registerPlaylistCallback(function callback(void))

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

Use this function to register a javascript function that will get called by the plugin at the end of each movie in the playlist - i.e. when the playlist changes tracks. The last track does not trigger a call; the end play callback, if registered, will be invoked instead.

getPlaylistLength

To retrieve the length of the playlist:

int length <- getPlaylistLength()

getCurrentPlaylistPosition

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

int position <- getCurrentPlaylistPosition()

getMovieAt

To get the url of the movie at the specified position (0 is the first position):

string url <- getMovieAt(int position)

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

Remember that getCurrentMovie can be used to retrieve the movie at the current position.

setMovieAt

To set the url of the movie at the specified position (0 is the first position):

boolean success <- setMovieAt(int position, string url)

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

Remember that setCurrentMovie can be used to change the currently playing movie.

appendMovie

To append a movie to the end of the playlist:

appendMovie(string url)

insertMovieBefore

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

To insert a movie before a specified position in the playlist:

boolean success <- insertMovieBefore(int position, string url)

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

removeMovieAt

To remove a movie from the playlist:

boolean success <- removeMovieAt(int position)

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

playMovieAt

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

boolean success <- playMovieAt(int position)

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

playlistNext

To start playing the next movie in the playlist:

boolean success <- playlistNext()

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

playlistPrev

To start playing the previous movie in the playlist:

boolean success <- playlistPrev()

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

retrieveAnnotationsAt

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

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

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

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

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

getMovieLengthAt

This is currently unimplemented.

int milliseconds <- getMovieLengthAt(int position)

This function retrieves the length of the movie at the specified position in the playlist. The function will return -1 if the movie length can not be determined.

Callback functions

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

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

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

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

Deregistering a callback is quite simple:

plugin.registerPlaylistCallback(null);

Suggested modifications

Individual Movies

states

add state LOADING and NULL or uninitialized state 

play

 function play()

if current state is NULL set state to LOADING else if already in loading state than a second call to play will force playback of what is available.

when a user hits play internally we store a separate state that reports as LOADING but is really LOAD_TO_PLAY state which uses download rate control to predict when we should switch into playing mode. ie if the clip's duration is 60 seconds and after one second we have buffered 10 seconds of the clip we can safely immediately switch to play mode. In a different instance if after 10 seconds we have downloaded 5 seconds of the clip we should wait until we have buffered 40 seconds as it will take around 40 seconds to download the last 20 seconds of video.

if the clip is a LIVE stream then it will begin playback after a few seconds have been buffered. Controllable by:

 setLiveBuffer(ms) sets the amount of the clip to buffer for a live stream.

load

 function load() //possible options include NOCACHE (to load from server even if its cached locally) 

a function to begin loading the current clip without playing it back.


getBufferedTime

Its unclear if get Buffered time gives you the milliseconds buffered from the beaning of the clip, but thats what it should do. To enable the display of a progress bar for the full clip. Ie getBufferedTime / getDuration

if playing back a live stream it could report amount buffered ahead of current playback point

playlist

loadMovieAt

to start downloading/buffering a clip later in playlist

getBufferedTimeAt

to get the amount Buffered for a clip in the playlist.

Applications Preferences

How much disk space to use to store cached clips. Used for syncing and fast page reload on browser back. Also would be ideal if it looked for response headers that invalidate the cache. default 100megs or maybe use firefox preferences... It should uses last accessed first out cacheting.


  • another point of comparison: [1] (e.g. getDuration)
  • suggestion: Include audio capture (and Speex encoding) in the API


Kate streams

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

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

long getNumKateTracks();

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

long getCurrentKateTrack();

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

string getKateTrackLanguage(in long track);

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

string getKateTrackCategory(in long track);

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

void selectKateTrack(in long track);

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

void registerKateCallback(in nsILibOggCallbackString callback);

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

void setKateFont(in string font);

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

string getKateFont();

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

void setKateFontSize(in float relsize);

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

float getKateFontSize();

returns the current font size multiplier.

void setKateRendering(in long method);

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

long getKateRendering();

returns the current render method being used.


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

Personal tools


Main Page

Xiph.Org Projects

Audio—

Video—

Text—

Container—

Streaming—