Skip Navigation

Warpwire Player API

The Warpwire Player API allows you to embed a Warpwire video on your website, and then interact with it via JavaScript.

With the Warpwire Player API, you can play, pause, and seek within videos; adjust player volume; or query information about the video currently playing. Additionally, you can set up event listeners which will be called whenever certain events, such as player state change, occur.

The purpose of this guide is to explain how to use the Warpwire Player API to interact with Warpwire media on your own site, via listening to events that will be sent from embedded Warpwire content as well as controlling embedded Warpwire media through available JavaScript functions.

Player API: Requirements

The user's browser must be on the approved list of supported browsers for Warpwire.

Any web page that uses the Warpwire Player API must also implement the following JavaScript function:

onWarpwirePlayerAPIReady - The loaded Warpwire Player API will call this function when the JavaScript for the Warpwire Player API has been downloaded and successfully registered. This will allow you to interact with Warpwire embedded IFrames on the page.

Player API: Getting Started

Below is a sample HTML page which locates and registers a Warpwire media embed with the Warpwire Player API, plays the video for 5 seconds, and then pauses playback.

<!DOCTYPE html>
<html>
  <body>
    <!-- 1. The <iframe> (and video player) will replace this <div> tag. -->
    <iframe id="wwvideo1" height="360" width="640" data-ww-id="apiTestFrame" src="https://bootstrap.warpwire.com/w/ABCDEF/" frameborder="0" scrolling="0" allowfullscreen></iframe>

    <script>
      // 2. This code loads the IFrame Player API code asynchronously.
      var tag = document.createElement('script');

      tag.src = "https://www.warpwire.com/player_api/";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // 3. This variable is a global that can be used to interact with Warpwire Player APIs
      var wwPlayerApi = null;

      // 4. This function listens for the player api to be registered, and then sets up the player processing
      function onWarpwirePlayerAPIReady() {
        var done = false;

        // 5. This code creates a new instance of the Warpwire API on the current page
        wwPlayerApi = new wwIframeApi();

        wwPlayerApi('apiTestFrame').onStateChange = function(event) {
          if (event.data == WWIRE.PLAYERSTATES.PLAYING && !done) {
            setTimeout(event.target.pause, 5000);
            done = true;
          }
        }

        // 6. This function waits until the player api is ready for the given iframe, then calls the play event
        wwPlayerApi('apiTestFrame').onReady = function(event) {
          event.target.play()
        }
      }
    </script>

    <!-- 7. These buttons show how to interact with a global Warpwire Player API -->
    <button onclick="wwPlayerApi('apiTestFrame').play()">Play</button>
    <button onclick="wwPlayerApi('apiTestFrame').pause()">Pause</button>
  </body>
</html>

Player API: Loading a Media Player

After the Warpwire Player API is successfully loaded, it will call the onWarpwirePlayerAPIReady function, after which you will be able to interact with Warpwire media embeds on your page. Note that the _playerApis parameter is an object whose keys are unique identifiers for individual Warpwire Player API references, and values are the corresponding Warpwire Player API object, which is denoted by [player] in the documentation below.

The code snippet below shows how the the data-ww-id attribute is used in the IFrame embed code:

<iframe id="wwvideo" height="360" width="640" data-ww-id="apiTestFrame" src="https://example.warpwire.com/w/SUQAAA/" frameborder="0" scrolling="0" allowfullscreen></iframe>

The code snippet below shows how the onWarpwirePlayerAPIReady function is implemented in the example code:

function onWarpwirePlayerAPIReady() {
  var done = false;

  // 5. This code creates a new instance of the Warpwire API on the current page
  wwPlayerApi = new wwIframeApi();

  wwPlayerApi('apiTestFrame').onStateChange = function(event) {
    if (event.data == WWIRE.PLAYERSTATES.PLAYING && !done) {
      //setTimeout(event.target.pause, 5000);
      done = true;
    }
  }

  // 6. This function waits until the player api is ready for the given iframe, then calls the play event
  wwPlayerApi('apiTestFrame').onReady = function(event) {
    event.target.play()
  }
}

Player API: Operations

The Warpwire Player API will return an object of references to Warpwire media embeds, each of which can utilize the Warpwire Player API methods and event listeners. This process is further explained in the Getting Started and Loading a Media Player sections.

Player API: Functions

Access a Warpwire IFrame API

The following functions utilize the _playerApis variable, which is the returned parameter of the onWarpwirePlayerAPIReady function:

_playerApis(uniqueId)

Returns the Warpwire Player API corresponding to the provided uniqueId. This parameter is equal to the data-ww-id attribute of the embedded IFrame.

_playerApis.getByUrl(frameUrl)

Returns the Warpwire Player API corresponding to the provided frameUrl. This url is the src attribute of the embedded IFrame. If two or more IFrames on the page have the same URL attribute, the Warpwire Player API will return the last discovered IFrame URL.

_playerApis.list()

Returns an array of Warpwire Player API objects, which correspond to Warpwire embeds on the page.

Playback Controls and Player Settings

Note that in the following sections, the [player] object is a reference to a Warpwire media embed. It is possible to have multiple Warpwire Embeds on the same page, and therefore possible to have multiple Warpwire Player API references.

Playing a Video

[player].play()

Plays the referenced media asset. This will result in the player state changing to playing (1).

[player].pause()

Pauses the referenced media asset. This will result in the player state changing to paused (2).

[player].seekTo(seconds)

Seeks to the time specified in the media asset. This action will not change the player's state - if the media is currently paused, it will still be paused after seeking, and if currently playing, it will continue to play after the seek is completed.

Changing the player volume

[player].mute()

Mutes the player.

[player].unMute()

Unmutes the player.

[player].isMuted()

Returns whether or not the player is muted (true for muted, false if not)

[player].setVolume(volume)

Sets the volume to the supplied volume parameter. Only accepts an integer between 0 and 100. This operation may not be supported on mobile platforms.

[player].getVolume()

Returns the current volume of the player, which will be an integer value between 0 and 100.

Setting the Playback Rate

[player].getPlaybackRate()

Retrieves the playback rate of the media being played. Possible values: 0.25, 0.5, 1, 1.5, and 2. The default playback rate is 1.

[player].setPlaybackRate(rate)

Sets the playback rate for the currently playing media. This does not guarantee that the playback rate will change, but if the function call is successful, the playback rate change event will be fired.

[player].getAvailablePlaybackRates()

Returns an array of the available playback rates.

Playback Status

[player].getMediaLoadedValue()

Returns the percentage of media that has been buffered. The value is a between 0 and 1, and signifies a percentage.

[player].getPlayerState()

Returns the current state value of the player. The list of possible values are below:

  • -1 – unstarted
  • 0 – ended
  • 1 – playing
  • 2 – paused
  • 3 – buffering

[player].getCurrentTime()

Returns the current media playhead position (in seconds). This is a float value.

Retrieving Media Asset Information

[player].getId()

Returns the id for the media asset.

[player].getTitle()

Returns the title for the media asset.

[player].getDuration()

Returns the duration (in seconds) of the media being played. This function will return a value of 0 if the media has not yet been loaded. For live broadcasts, the value for the duration will be -1.

[player].getSavedPlaybackPosition()

Returns the saved playback position (in seconds) of the media being played for the current user. This function will return a value of 0 if the user has not yet played the media, or if the media was played to completion during the user's last viewing session.

[player].getMediaUrl()

Returns the permalink for the media asset.

Retrieving Session Analytics

[player].getSessionAnalytics()

Returns a JavaScript object of player interactions, indexed by the session start time (the unix timestamp for the event occurrence). A sample of the data returned from this function is as follows:

[
  1122334455: {
    start: 0,
    end: 6
  },
  1122334466: {
    start: 11,
    end: 15
  }
]

In the above example, the user watched the first 6 seconds of the media asset, paused playback, seeked to the 11 second mark, resumed playback, and then paused playback at the 15 second mark.

Closed Captions

[player].getCaptions()

Returns an array of available closed caption objects. The caption objects contain the following properties:

  • label - the title of the caption
  • location - the url of the caption file
  • enabled - a boolean value that indicates whether or not this caption object is currently enabled in the player

[player].setCaption(label)

Sets the currently enabled caption file to the provided label. If no label is sent, closed captions will be disabled.

Adding or removing an event listener

[player].addEventListener(event, listener)

Adds a listener function for the specified event. The available events to listen for are specified in the Events section below.

[player].removeEventListener(event, listener)

Removes a listener function for the given event.

Accessing and modifying DOM nodes

[player].getIframe()

Returns the DOM node of the <iframe> corresponding to the [player] reference.

[player].destroy()

Removes the <iframe> DOM node to which the [player] reference corresponds.

Player API: Events

The Warpwire Player API fires events that inform subscribed listeners of changes occurring in the [player] reference object.

The sent event object will contain 2 properties: the event target and event data. The event target corresponds to the [player] object, and can be used as a sanity check to ensure that the expected [player] object is being interacted with. The event data property is an optional JavaScript value which provides relevant data for the given event type.

The following list defines the events that the API fires:

onReady

This event is fired when a [player] object has finished loading, and is ready to begin receiving API calls.

onStateChange

Fires when the state of the player changes. The data property of the event object passed will specify a value corresponding to the player state, as listed below:

  • -1 – unstarted
  • 0 – ended
  • 1 – playing
  • 2 – paused
  • 3 – buffering

onPlaybackRateChange

Fires when the playback rate of the embedded Media Asset is changed. The data property of the event object will be the new playback rate.

onError

Fires when an error is encountered in the player. The data property of the event object will be the error code of the error that was encountered. The list of error codes is below:

  • -1 - player not loaded
  • 400 - a bad request was made

View Developer APIs page