Copyright © 2007. All rights reserved.
This document describes the Engine API.
Any and all use of the Joost API is subject to the Joost API Terms of Use
The API may change and although we will try and keep these changes to a minimum, some API calls may be deprecated in the future.
The Engine interface provides access to information about the current state of the Joost engine, such as what is currently playing, whether the video is running or paused, how far into a given program we are, what the volume level is, etc. It also allows one to switch channels and control various aspects of playback.
The Engine interface
interface Engine { attribute boolean paused; attribute Number volume; attribute boolean mute; readonly attribute Entry currentEntry; readonly attribute Number currentChannelPosition; readonly attribute Channel currentChannel; readonly attribute Number currentTimeMS; readonly attribute Number currentDuration; readonly attribute Number numChannels; void play(in String channel, in Number entry, in Number position); void addListener(in EngineListener callback); void removeListener(in EventListener callback); void retrieveURL(in String url, in ChannelListener callback); void addVideoCallback(in Number time, in Function cb, in boolean once); boolean canSeek(); Number getMaxSeekTimeMS(); boolean seekToTimeMS(in Number ms, in Function cb); Sprite createSprite(in String url, in Number x, in Number y, in Number h, in Number w, in Number opacity); Subtitle createSubtitle(); };
currentChannel
of type
Channel, readonlyThe channel currently being watched.
currentChannelPosition
of type
Number, readonlyThe position of the entry currently playing in the current channel.
currentDuration
of type
Number, readonlyThe total length in milliseconds of the entry currently playing.
currentEntry
of type
Entry, readonly
The Entry that is currently playing, null when not
playing an entry.
currentTimeMS
of type
Number, readonlyThe current offset in milliseconds in the entry currently playing.
mute
of type
booleanGet or set the mute status.
numChannels
of type
Number, readonlyThe number of channels in the EPG.
paused
of type
booleanGet the paused status of the current entry; set to pause or resume the video.
volume
of type
Number
Get or set the volume, between 0 and 1. Note that setting the volume to 0 does not cause
the mute field to become true or the sound necessarily to be silent. Instead
it corresponds to the lowest volume level desired by the user.
addListenerAdd a callback listener for runtime information.
callback
of type
EngineListeneraddVideoCallbackAdd a callback that will be called when the given time offset in milliseconds in the current entry is passed.
time
of type
Numbercb
of type
Functiononce
of type
booleantrue, the callback will only be called the first time that the time
offset is reached, and will be discarded afterwards. Otherwise, it will be called
every time that the offset is passed for this entry.
canSeekIndicates whether the current entry is seekable or not.
| True or false depending on seekability. |
createSpriteCreate a 'sprite' - a small HTML document which can be positioned on the screen by a widget. Only 6 sprites can be created in one session, but they can be reused using hide() and navigate(). All sprites are released when enable / disable is toggled, which also removes all sprites from the screen.
url
of type
Stringx
of type
Numbery
of type
Numberh
of type
Numberw
of type
Numberopacity
of type
Number | A newly minted Sprite. |
createSubtitleCreates a subtitle object for use. A utility method that enables you to easily create sprites with text, by default placed at the bottom centre of the screen.
| A newly minted empty Subtitle. |
getMaxSeekTimeMSGet the maximal offset one can seek to, in milliseconds.
| The millisecond offset to which one can seek. |
playPlays an entry in a given channel, optionally at a given position in case the entry is repeated in the channel.
channel
of type
Stringentry
of type
Numberposition
of type
Numbernull to play the first occurrence
of that entry in that channel.
removeListenerRemove an existing EventListener.
callback
of type
EventListenerretrieveURLRetrieves a Joost Link URL, making information about the channel and the entry available. Use in conjunction with a listener to check if a Joost Links is playable, geo-restricted, or no longer available.
url
of type
Stringcallback
of type
ChannelListenerseekToTimeMSRequest that the engine seek to the given millisecond offset.
ms
of type
Numbercb
of type
Function | True if the seek was immediate, false otherwise. |
The EngineListener interface is a simple interface meant to be implemented
in Javascript code when one needs to be notified of events coming from the Engine,
through callbacks. All methods are optional, if a method is not implemented it is
simply not called. Details of the information that can be obtained by implementing
this interface and passing the resulting object to the Engine's
addListener are given below.
The EngineListener interface
interface EngineListener { void engineReady(); void engineStop(); void engineShutdown(); void playFailure(in String entryID, in String channelID, in Number errCode); void channelChange(in String channelID, in String entryID); void channelsChanged(in Array channels); void entryChange(in String entryID); void entryStart(in String entryID, in Number ms); void entryEnd(in String entryID, in Number ms); void entryPaused(in Number ms); void entryUnpaused(in Number ms); };
channelChangeThe viewer has request to switch to a new channel.
channelID
of type
StringentryID
of type
StringchannelsChangedThe channels in the EPG have been updated and changed.
channels
of type
Arraychannels is
null, all the channels in the EPG have been changed.
engineReadyNotification that the engine is ready. No useful information can be obtained from it before this stage.
engineShutdownNotification that the engine has shut down (i.e. the application is exiting).
engineStopNotification that the engine has been stopped.
entryChangeThe viewer requested to view another entry.
entryID
of type
StringentryEndAn entry has stopped playing.
entryID
of type
Stringms
of type
NumberentryPausedThe current asset has been paused.
ms
of type
NumberentryStartAn entry has started to play.
entryID
of type
Stringms
of type
NumberentryUnpausedThe current asset has been restarted.
ms
of type
NumberplayFailurePlaying has completely failed, something bad has happened.
entryID
of type
StringchannelID
of type
StringerrCode
of type
NumberThe Channel interface encapsulates information describing a channel, and allows one to listen to specific events on the channel.
The Channel interface
interface Channel { readonly attribute String id; readonly attribute String title; readonly attribute String description; readonly attribute String logo; readonly attribute boolean isSmartChannel; readonly attribute boolean isShownInEpg; readonly attribute Number numEntries; Entry getEntry(in Number lookup); };
description
of type
String, readonlyThe description of the channel.
id
of type
String, readonlyThe public identifier for the channel.
isShownInEpg
of type
boolean, readonlyA boolean indicating whether this channel is shown in the EPG, and that it is not empty.
isSmartChannel
of type
boolean, readonlyA boolean indicating whether this channel was created from a search or a hodgepodge channel.
logo
of type
String, readonlyThe URL of the logo of the channel.
numEntries
of type
Number, readonlyThe number of Entry objects in the channel.
title
of type
String, readonlyThe title of the channel.
getEntryGet an entry by its position in the channel in the local EPG.
lookup
of type
Number |
The corresponding Entry, or null if none is found at this offset.
|
The ChannelListener interface is implemented by objects that wish to be notified of events targeting a specific channel, or all channels.
The ChannelListener interface
interface ChannelListener { void updateSuccess(in Channel channel, in Entry entry); void updateFailure(in String code); };
updateFailureUpdating (or adding) the channel failed.
code
of type
StringupdateSuccessThe channel was successfully updated (or added). If the Joost Link points to a channel it returns the corresponding Channel object and the channel's first Entry object; if the Joost Link is an entry it returns the Channel object encapsulating the Joost Links virtual channel and the given Entry object.
The Entry interface encapsulates information describing an entry (i.e. an individual programme) in a channel.
The Entry interface
interface Entry { readonly attribute String id; readonly attribute String title; readonly attribute String description; readonly attribute String logo; readonly attribute Number duration; readonly attribute String thumbnail; readonly attribute boolean noThumbnailProvided; readonly attribute String joostLink; };
description
of type
String, readonlyThe description of the entry.
duration
of type
Number, readonlyThe duration of the entry, in milliseconds.
id
of type
String, readonlyThe public identifier for the entry.
joostLink
of type
String, readonlyThe Joost Link for this entry.
logo
of type
String, readonlyThe URL of the logo of the entry.
noThumbnailProvided
of type
boolean, readonlyTrue if there was no thumbnail and the default one is being used.
thumbnail
of type
String, readonlyThe URL of the thumbnail for the entry. If there is none, a default one is returned.
title
of type
String, readonlyThe title of the entry.
A sprite is a small HTML document which can be positioned on the screen by a widget. Only 6 sprites can be created in one session, but they can be reused using hide() and navigate(). All sprites are released when enable / disable is toggled, which also removes all sprites from the screen.
The Sprite interface
interface Sprite { void hide(); void navigate(in String url); void place(in Number x, in Number y, in String opacity); void moveTo(in Number x, in Number y, in Number duration); void fade(in Number opacity, in Number duration); void remove(); void captureClick(in Function cb, in boolean captureOnce); };
captureClickCaptures a click from the user that enables you to, for example draw a sprite in that place using the callback function
cb
of type
FunctioncaptureOnce
of type
booleanfadeFades away the display of the sprite.
opacity
of type
Numberduration
of type
NumberhideAllows you to reuse a sprite after creation. Use with navigate() and place() to change the content and position of an existing sprite.
moveToMoves a sprite visibly from its initial position to the x,y coordinates specified, taking the duration in milliseconds specified.
x
of type
Numbery
of type
Numberduration
of type
NumberChanges the content of the sprite.
url
of type
StringplaceThis places a sprite onscreen. Resizing the Joost window does not change the placement of the sprite relative to the size of the screen, so resizing may mean sprites go off the visible space.
x
of type
Numbery
of type
Numberopacity
of type
StringremoveRemoves the sprite completely. Sprite cannot be retrieved or reused until enable / disable of the widget has been toggled. Don't use this unless you really don't want to use it any more.
A Subtitle object for use, enabling you to quickly create sprites with text, by default placed at the bottom centre of the screen.
The Subtitle interface
interface Subtitle { attribute String text; attribute String verticalAlign; attribute String horizontalAlign; attribute String font; void show(); void hide(); };
font
of type
StringString as used in css, defaulting to "sans-serif".
horizontalAlign
of type
StringString as used in css, defaulting to "middle".
text
of type
StringThe text content of the subtitle.
verticalAlign
of type
StringString as used in css, defaulting to "bottom".
hideHides the subtitle from the screen. Can be used with setTimeout or Engine.addVideoCallback for example.
showDisplays the subtitle onscreen. Can be used with setTimeout or Engine.addVideoCallback for example.