Player API Documentation

Overview

Enables sites using the IBM Video Streaming embed iframe to build and adapt on the embed live player.

The Player 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 Player API requires postMessage DOM API, it won't work in browsers that does not support the postMessage API.

Usage

First, a valid IBM Cloud Video embed iframe will be needed to use the Embed API. Log in to your managed IBM Cloud Video account as an administrator of your channel. Then navigate to the Embed Configurator page on your Dashboard by selecting the "Embed" option as seen below:

After selecting an option with the IBM Cloud Video Player, the Embed Configurator is displayed. The Configurator enables channel administrators to set the properties of the Player embed. When it's done, the proper iframe HTML element can be copied to the clipboard with the button which is highlighted in the next picture.

The next step is to include a unique ID in this iframe element. We will use "UstreamIframe".

Create an instance of the Embed API by providing the ID of the iframe. The iframe code should look like this:

<iframe id="UstreamIframe" src="https://video.ibm.com/embed/1524?html5ui" width="640" height="480" allowfullscreen webkitallowfullscreen></iframe>

var viewer = UstreamEmbed('UstreamIframe');

URL parameters

The default behaviour of the player can be modified by extending the src URL with any of the following parameters:

callMethod

Calls a command method of the embed player, passing in any arguments.
Available commands through callMethod:

play

Starts playing the currently loaded channel or video.

Example

viewer.callMethod('play');

pause

Pauses the live stream, or the playback of a video.

Example

viewer.callMethod('pause');

stop

Pauses the live stream, or stops the video and jumps back to the start.

Example

viewer.callMethod('stop');

load

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

Example

viewer.callMethod('load', 'video', 5903947);
viewer.callMethod('load', 'channel', 1524);

seek

Jumps to given position in played recorded video. Requires one argument:

• position in seconds

Example

viewer.callMethod('seek', 180);

volume

Sets the playback sound volume. Requires one argument:

• volume percent between 0-100

Example

viewer.callMethod('volume', 0); //mute

quality

Sets the stream quality, if available. Requires one argument:

• a qualityID key from received quality options in quality event

Example

viewer.callMethod('quality', 16); //set to high

cc (closed caption)

Enables the selected closed caption if available. Requires one argument:

• a ccIndex key from the received closed caption array in cc event

Example

viewer.callMethod('cc', 1); //enable the closed caption with index 1
viewer.callMethod('cc', -1); //disables the closed caption

getProperty

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:

duration

Get the video duration in seconds.

Example

viewer.getProperty('duration', function (duration) {
    ...
});

viewers

Get the current viewer count for the loaded live stream.

Example

viewer.getProperty('viewers', function (viewerNumber) {
    ...
});

progress

Get the current progress for recorded video playback, in seconds.

Example

viewer.getProperty('progress', function (progress) {
    ...
});

content

Get the current content type and id as an array.

Example

viewer.getProperty('content', function (content) {
    // content == ['channel', 1524]
    // or
    // content == ['recorded', 123456]
    ...
});

playingContent

Get the actual content type and id as an array. This will return the currently played offair video's id if the loaded content is an offair channel or with the channel id if the channel is live.

Example

viewer.callMethod('load', 'channel', 1524);

// ...

viewer.getProperty('playingContent', function (content) {
    // content == ['channel', 1524]
    //  - if it's live, or
    // content == ['recorded', 123456]
    //  - if it's offair and has offair video content, or
    // content == []
    //  - if it's offair and doesn't have offair video content
});

addListener & removeListener

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 event
• data optional data sent along the event

Available events for addListener and removeListener:

live

Called when the currently loaded offline channel becomes live.

Example

viewer.addListener('live', callBack);

offline

Called when the currently loaded live channel goes offline.

Example

viewer.addListener('offline', callBack);

finished

Called when the currently loaded and played recorded video reaches its end.

Example

viewer.addListener('finished', callBack);

playing

Called when the currently loaded content playback is started or stopped. Sends data along the event:

• playing (boolean)

Example

viewer.addListener('playing', callBack);

size

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

Example

viewer.addListener('size', callBack);

quality

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

Example

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

cc (closed caption)

Fired when there are closed captions available on the stream.

Returns an array containing closed captions as objects.

• index (integer) unique index of the closed caption
• label (string) label of the closed caption
• language (string) language code of the closed caption (en, etc.)
• active (booelan) if this closed caption is shown

Example

viewer.addListener('cc', callBack);

// example cc object
[
	{"index":0, "label":"English", "language":"en", "active":false}
]

content

Called when a the player content changes for some reason. Same data as received in getProperty('content')

Received arguments: data (object)

Example

viewer.addListener('content', callBack);

liveCtaUpdate

Fired when there is a live cta available on the stream.

Returns an object:

• buttonText (string) text of the button
• buttonUrl (string) URL of CTA
• description (string) description of CTA
• id (integer) id of CTA
• imageUrl (string) URL of the image
• title (string) title of CTA

Example

viewer.addListener('liveCtaUpdate', callBack);

// example cta object when activated:
{
    activate: {
        buttonText: "Click here!"
        buttonUrl: "https://video.ibm.com"
        description: "The Future of Video with Watson",
        id: 123,
        imageUrl: "URL of image",
        title: "IBM Video Streaming"
    }
}

// example cta object when removed:
{
    remove: {
        id: 123
    }
}