Enables sites using the Ustream embed iframe to build and adapt on the embed live player.
The Ustream Embed API provides basic methods to control the live stream or recorded video playback, and enables the user to access essential events of the live stream or the played video.
The Ustream Embed API requires postMessage DOM API, it won't work in browsers that does not support the postMessage API.
Create an instance of the Embed API by providing the ID of the iframe, or the iframe DOM object itself:
<iframe id="UstreamIframe" src="//ustream.tv/embed/1524" width="640" height="480"></iframe>
var viewer = UstreamEmbed('UstreamIframe');
The Ustream Embed API provides the following methods:
- callMethod
- getProperty
- addListener
- removeListener
Calls a command method of the embed player, passing in any arguments.
Available commands through callMethod
:
Starts playing the currently loaded channel or video.
viewer.callMethod('play');
Pauses the live stream, or the playback of a video.
viewer.callMethod('pause');
Pauses the live stream, or stops the video and jumps back to the start.
viewer.callMethod('stop');
Loads a channel or a video in the player. Requires two additional arguments:
type
- the loaded content type (channel | video)id
- the loaded content id
viewer.callMethod('load', 'video', 5903947);
viewer.callMethod('load', 'channel', 1524);
Jumps to given position in played recorded video.
Requires one argument:
- position in seconds
viewer.callMethod('seek', 180);
Sets the playback sound volume
Requires one argument:
- volume percent between 0-100
viewer.callMethod('volume', 0); // mute
Sets the stream quality, if available.
Requires one argument:
- a
qualityID
key from received quality options inquality
event
viewer.callMethod('quality', 16); // set to high
Read a property of the embed player.
This method is asynchronous, the data will be passed to a callback function, given as argument.
Accessible properties by getProperty
:
Get the video duration in seconds.
viewer.getProperty('duration', function (duration) {
...
});
Get the current viewer count for the loaded live stream.
viewer.getProperty('viewers', function (viewerNumber) {
...
});
Get the current progress for recorded video playback, in seconds.
viewer.getProperty('progress', function (progress) {
...
});
Get the current content type and id as an array
viewer.getProperty('content', function (content) {
// content == ['channel', 1524]
// or
// content == ['recorded', 123456]
...
});
The embed player dispatches several events during playback. This method adds or removes event handlers to these events.
The event handler callback receives two arguments:
type
the type of the eventdata
optional data sent along the event
Available events for addListener
and removeListener
:
Called when the currently loaded offline channel becomes live.
viewer.addListener('live', callBack);
Called when the currently loaded live channel goes offline.
viewer.addListener('offline', callBack);
Called when the currently loaded and played recorded video reaches its end.
viewer.addListener('finished', callBack);
Called when the currently loaded content playback is started or stopped
Sends data along the event:
playing
(boolean)
viewer.addListener('playing', callBack);
Called when the stream size is available, or changed (changes reported only in flash mode)
Sent data is the size of the calculated embed iframe according to the player width, and the stream aspect ratio. The player bar height is included, if the controls are visible.
Sends data along the event:
size
(array) as [width
,height
] in pixels
viewer.addListener('size', callBack);
Fired when the stream quality options are available.
Receives an object, with the qualityID
as keys, and an object with two properties as values:
label
(string) label to show to users on control UI, eg.: "480p"active
(booelan) if this quality is used or set
viewer.addListener('quality', callBack);
// example quality object
{
"0":{"label":"240p","active":false},
"1":{"label":"360p","active":false},
"2":{"label":"480p","active":false},
"16":{"label":"BEST","active":true}
}
Called when a synced metadata has arrived on the stream/recorded. Used for keep presentations in sync with the live stream / recorded.
Received arguments: data (object)
viewer.addListener('syncedmeta', callBack);
Called when a the player content changes for some reason. Same data as received in getProperty('content')
Received arguments: data (array)
viewer.addListener('content', callBack);