Skip to main contentIBM Video Streaming Developers



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


First, a valid IBM Video Streaming embed iframe will be needed to use the Embed API. Log in to your managed IBM Video Streaming 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:

Embed Configurator Page Location

After selecting an option with the IBM Video Streaming 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.

Copy To Clipboard Button Location

The next step is to include a unique ID in this iframe element. We will use “PlayerIframe”.

Download the Player API from npm:

npm install ibm-video-streaming-web-player-api

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

<iframe id="PlayerIframe" src="" width="640" height="480" allowfullscreen webkitallowfullscreen referrerpolicy="no-referrer-when-downgrade"></iframe>
let viewer = PlayerAPI('PlayerIframe');

URL parameters

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

allowfullscreenEnables full-screen. False value makes the full-screen button inactive.true/falsetrue
api-target-originOrigin of the page where player api is included. Use encodeURIComponent to URL encode origin. This parameter is only required in case of SSO authentication.URL encoded origin e.g. output of encodeURIComponent('')N/A
autoplayStarts video playback automatically. Browser settings are stronger and may override the value of this parameter.true/falsefalse
controlsWhen set to false it hides all UI elements.true/falsetrue
forced-qualityTurns off the automatic quality selection and selects the appropriate quality. Low is the smallest available quality, high is the largest and med is the middlemost choice.low, med, highN/A
hideCTADisables CTA overlays. Use liveCtaUpdate event to build your own.true/falsefalse
initial-qualitySets the initial quality for the automatic quality selection. The quality selection logic is still turned on and can switch to another quality after playback is started.low, med, highN/A
showtitleShows title and viewer count information inside the player area.true/falsetrue
volumeSet volume for playback as a percentage of the max volume. Overrides the default volume (100).0-100100

Method Calls

Using the callMethod function one can call command methods on the player. Available commands:


Starts playing the currently loaded channel or video.



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



Pauses the live stream. For on demand videos it stops and jumps back to the start.



Loads a channel or a video in the player. Requires two additional arguments:

  • type - content type (‘channel’ or ‘video’)
  • id - media id
viewer.callMethod('load', 'video', 5903947);
viewer.callMethod('load', 'channel', 1524);


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

  • position - target time in seconds
viewer.callMethod('seek', 180);


Sets the playback sound volume. Requires one argument:

  • volume - percent between 0 and 100
viewer.callMethod('volume', 0); //mute


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

  • an id key from received quality options in quality event
viewer.callMethod('quality', 0); //set to highest quality

cc (closed caption)

Displays the selected closed caption if available. You can use the ‘None’ option by using -1 as the argument. Otherwise it requires this argument:

  • an index key from the received closed caption object in cc event
viewer.callMethod('cc', 1); //enables the closed caption with index 1
viewer.callMethod('cc', -1); //disables the closed caption


Retrieves 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.milliseconds precision.

viewer.getProperty('duration', function (duration) {
}); //passed value is e.g. 120.345


Get the current viewer count for the loaded live stream. Doesn’t return anything in case of recorded videos.

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


Get the accumulated total viewer number for the loaded channel. Doesn’t return anything in case of recorded videos.

viewer.getProperty('allTimeTotalViewers', function (allTimeTotalViewers) {


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', 12345678]


Get the actual content type and ID as an array. This will return the currently played off-air video’s ID if the loaded content is an off-air channel or with the channel ID if the channel is live.

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


Get the player volume. This will return the actual value of volume in percent.

viewer.getProperty('volume', function (volume) {
// volume == 0 for muted playback

addListener & removeListener

The embedded 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:


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 all metadata required to start playback is available.

viewer.addListener('contentAvailable', 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 a user or system initiated seek started.

  • from (number) - previous position in sec
  • to (number) - next position in sec
  • initiator (string) - user|system
viewer.addListener('seekStarted', callback);


Called when a user or system initiated seek completed.

viewer.addListener('seekCompleted', callback);


Called when the stream size is available. 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 the following array of quality based objects

  • id (number) the ID with which the quality method can be called
  • codec (string)
  • width (number) width of the quality version in pixels
  • height (number) height of the quality version in pixels
  • bitrate (number) actual bitrate value in kbps
  • transcoded (boolean) is this quality one of the transcoded versions or the original ingested quality
  • label (object): its text key has the text to show to users on control UI, eg.: “480p”
  • selected (boolean) is this quality set to display
viewer.addListener('quality', callback);

Example quality object from the quality array:

"id": 0,
"codec": "avc1.4d001f",
"bitrate": 1406,
"transcoded": false,
"width": 1280,
"height": 720,
"label": {
"text": "720p",


Fired when there are closed captions available on the stream.

Returns an array containing closed captions as objects.

  • index (number) unique index of the closed caption
  • label (string) displayed label of the closed caption
  • language (string) ISO language code of the closed caption
  • country (string) ISO code of country
  • active (boolean) height of the quality version in pixels
viewer.addListener('cc', callback);

Example cc object from the cc array:

"index": 0,
"label": "Spanish",
"language": "es",
"country": "00",
"active": true


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

Received arguments: data (object)

viewer.addListener('content', callback);


Fired when there is a live CTA (call to action) video overlay 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
viewer.addListener('liveCtaUpdate', callback);

Example CTA object when activated:

"activate": {
"buttonText": "Click here!",
"buttonUrl": "",
"description": "The Future of Video with Watson",
"id": 123,
"imageUrl": "URL of image",
"title": "IBM Video Streaming"


Fired when an unexpected event occures.

Returns an object:

  • name (string) error name
  • message (string) error message

Available error type(s):

  • autoplayRejected
viewer.addListener('error', function(event) {
switch ( {
case 'autoplayRejected':
// TODO: display fallback button
// no default

Example autoplayRejected error:

"name": "autoplayRejected",
"message": "detailed error message"