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.
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.
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>
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()
}
}
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.
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.
Fullscreen Access
[player].requestEnterFullscreen()
Ask the player to enter fullscreen mode, if not already in fullscreen mode. Note that browsers are strict about fullscreen requests and they may not always succeed.
[player].requestLeaveFullscreen()
Ask the player to leave fullscreen mode, if already in fullscreen mode. Note that browsers are strict about fullscreen requests and they may not always succeed.
[player].getFullScreen()
Retrieves whether the player is currently in fullscreen mode or not. Fullscreen mode can change by user action or by one of the above function calls.
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:
[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 stream, 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:
[player].setCaption(label)
Sets the currently enabled caption file to the provided label. If no label is sent, closed captions will be disabled.
[player].isTranscriptChanged()
If the transcript editor is active and the user has made, but not saved, changes, this function will return true. Otherwise
it will return false. If the editor is not active or there is no transcript, it will also return false. See also the
notes below for the onTranscriptChanged() event.
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.
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:
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:
onTranscriptChanged
Fires when the transcript in the interactive transcript editor has changed from its pristine state, or when the transcript returns to its pristine state. It does not fire when the transcript is changed further after leaving its pristine state. In practice, during an edit session, this event will fire when the user first makes a change to a cue. Subsequent changes do not result in this event firing. The event will fire again when the user saves their changes, when the user cancels their changes, or if the user should manually undo their changes such that the transcript returns to the pristine state.
onFullscreenChanged
Fires when the player enters or leaves fullscreen mode. The data property of the event object will be a boolean indicating whether the player is now in fullscreen mode or not.
onTimeUpdate
Fires when the the current time of the player updates. The data property of the event object will contain the current play time in seconds since the start of the video.
