How to use the Wowza Player JavaScript API

The Wowza™ Player JavaScript API is an extension of the Wowza Player embed code that allows you to interact with your player instance programmatically from inside your webpage or web application.

Contents


Getting ready to use the Wowza Player API Setter and getter instance methods Event instance methods
Stop a WowzaPlayer instance

Getting ready to use the Wowza Player API


WowzaPlayer is the object that Wowza Player places in the global DOM and provides access to the Wowza Player Javascript API. Use the WowzaPlayer.create static method (in your player embed code) to set up a new player or use the WowzaPlayer.get method to retrieve a player instance so you can make other Wowza Player API calls.

Note: You can use $wp as a shortcut for your WowzaPlayer global object. For example:
 
var myPlayer = $wp.get('playerElement');

Set up a WowzaPlayer instance

To make API calls, you must add a WowzaPlayer object instance to your webpage to interact with. Our Getting started with Wowza Player tutorial explains the steps for accessing and embedding Wowza Player in your webpage. Player embed code should resemble the sample code below.

<HEAD>
	<script type="text/javascript" src="//player.wowza.com/player/latest/wowzaplayer.min.js"></script>
</HEAD>
<BODY>
	<div id="playerElement" style="width:100%; height:0; padding:0 0 56.25% 0"></div>
	<script type="text/javascript">
	var myPlayer = WowzaPlayer.create('playerElement',{
               "license":"[wowza-player-license-key]",
               "sourceURL":"https%3A%2F%2F%5Bwowza-ip-address%5D%3A1935%2Fvod%2Fmp4%3Asample.mp4%2Fplaylist.m3u8"}
         );
	</script>
</BODY>
Note: Significant updates to Wowza Player may alter the API. To force your WowzaPlayer instance to use the latest stable version of a specific player release, replace latest in the player URL in your embed code to [version-number]-latest. For example:
 
<script type="text/javascript" src="//player.wowza.com/player/1.0-latest/wowzaplayer.min.js"></script>
For more information on previous updates to Wowza Player, see the Wowza Player release notes.

The WowzaPlayer.create static method in your player embed code creates an instance of WowzaPlayer and returns a reference to the new WowzaPlayer instance. If you call this static method after an embedded player has already been created, a new player is created to replace the previous player. This is useful for changing player configuration properties at runtime.

create ( PlayerElement : string, ConfigJSON : {} ) : WowzaPlayer

Where:

  • playerElement is the player ID defined in the <div> HTML element in your player embed code.
     
  • ConfigJSON is the JSON literal containing the configuration parameters for the WowzaPlayer instance.

The WowzaPlayer object is created and initiated asynchronously, so some playback method calls may not function until the player has entered the READY_TO_PLAY or PLAYING states. For more information about player states, see the list of WowzaPlayer.State values. To learn how to call an event listener when the WowzaPlayer instance is ready and playback method calls can be used, see the onLoad event instance method.

Retrieve an existing WowzaPlayer instance

The WowzaPlayer.get static method returns the WowzaPlayer instance that was created with the specified PlayerElement player ID.

get ( PlayerElement : string ) : WowzaPlayer

var myPlayer = WowzaPlayer.get('playerElement');

If no WowzaPlayer instance matches PlayerElement, the method returns null.

Setter and getter instance methods


Control playback and get information about the player and stream playback with Wowza Player API setter and getter methods.

Note: You can chain Wowza Player instance methods that return a reference to the method's own instance. For example:
 
myPlayer.setVolume(75).play();

Control playback

The following instance methods control playback in your player.

finish () : WowzaPlayer

Finishes stream playback and returns the current WowzaPlayer instance. For example:

myPlayer.finish();

mute ( isMuted : boolean ) : WowzaPlayer

Set isMuted to true to mute playback volume or set to false to unmute and return the playback volume to its previous level. Then, the method returns the current WowzaPlayer instance. For example:

myPlayer.mute(true);

pause () : WowzaPlayer

Pauses video playback (changes WowzaPlayer.State to PAUSED) and returns the current WowzaPlayer instance. For example:

myPlayer.pause();

play () : WowzaPlayer

Starts video playback (changes WowzaPlayer.State to PLAYING) and returns the current WowzaPlayer instance. For example:

myPlayer.play();

seek ( newTimeMS: number ) : WowzaPlayer

Seeks to newTimeMS milliseconds into stream playback and returns the current WowzaPlayer instance. For example:

myPlayer.seek(60000);

setVolume ( newVolume : number ) : WowzaPlayer

Sets the current playback volume to newVolume. Volume ranges from 0-100. For example:

myPlayer.setVolume(75);

Get playback status

The following playback instance methods retrieve information from your player instance.

getCurrentState () : number

Returns the current playback state. For example:

if (myPlayer.getCurrentState() == WowzaPlayer.State.PLAYBACK_COMPLETE) {
    console.log('Playback Complete');
}

For a list of all WowzaPlayer.State values and the states those numbers represent, see the table below.

Return value Player state
(0) WowzaPlayer.State.UNKNOWN
(1) WowzaPlayer.State.CREATED
(2) WowzaPlayer.State.INITIALIZED
(3) WowzaPlayer.State.PREPARING
(4) WowzaPlayer.State.READY_TO_PLAY
(5) WowzaPlayer.State.PLAYING
(6) WowzaPlayer.State.PAUSED
(7) WowzaPlayer.State.STOPPED
(8) WowzaPlayer.State.PLAYBACK_COMPLETE
(9) WowzaPlayer.State.SHUTDOWN
(10) WowzaPlayer.State.APP_STOPPED
(11) WowzaPlayer.State.ERROR

getCurrentTime () : number

Returns the current playhead time in milliseconds. For example:

console.log( 'Playhead time (ms): ' + myPlayer.getCurrentTime() );

getDuration () : number

Returns the duration of the current video asset in milliseconds. For example:

console.log( 'Video duration (ms): ' + myPlayer.getDuration() );

getVolume () : number

Returns the current playback volume. Volume ranges from 0-100. For example:

console.log('Volume: ' + myPlayer.getVolume() );

isLive () : boolean

Returns true if the current video asset is a live stream or nDVR stream. Returns false if the current video asset is VOD. For example:

console.log('Video is Live: ' + myPlayer.isLive() );

isMuted () : boolean

Returns true if the current playback is muted. Returns false otherwise. For example:

console.log('Video is muted: ' + myPlayer.isMuted() );

isPlaying () : boolean

Returns true if a stream is playing. Returns false if playback is paused or stopped. For example:

console.log('Video is playing: ' + myPlayer.isPlaying() );

Event instance methods


The WowzaPlayer class provides several methods for attaching and removing event listener functions. These event listener functions are called when certain events occur in the lifecycle of a WowzaPlayer instance. Event listeners may be wired and unwired at any time, independent of the state of the WowzaPlayer instance.

Notes: With the following exceptions, Wowza Player 1.0.08 or later is required to use the event instance methods on iOS devices:

  • The onLoad event method is supported on iOS in earlier versions of Wowza Player.
  • The onBitrateChanged event method isn't supported on iOS devices.
  • The onPlay, onPause, onResume, onStop, onCompleted, and onSeek event methods require Wowza Player 1.1 or later.

onLoad, removeOnLoad

onLoad ( callback : function () ) : WowzaPlayer

onLoad attaches an event listener that's called when the WowzaPlayer instance is loaded. If the WowzaPlayer is already loaded, the callback function is called immediately. Then, it returns the current WowzaPlayer instance. For example:

onLoadListener = function () {
    console.log('WowzaPlayer loaded');
}
myPlayer.onLoad(onLoadListener);

removeOnLoad ( callback : function () ) : WowzaPlayer

removeOnLoad removes the requested event listener function and returns the current WowzaPlayer instance. For example:

myPlayer.removeOnLoad( onLoadListener );

onReady, removeOnReady

onReady ( callback : function () ) : WowzaPlayer

onReady attaches an event listener that's called when the WowzaPlayer instance enters the READY_TO_PLAY state. If the player has already been in the READY_TO_PLAY state, the callback function will fire immediately. Then, it returns the current WowzaPlayer instance.

removeOnReady ( callback : function () ) : WowzaPlayer

removeOnReady removes the requested event listener function and returns the current WowzaPlayer instance. For example:

myPlayer.removeOnReady (readyListener);

onBitrateChange, removeOnBitrateChange

onBitrateChanged ( callback : function ( bitrateChangedEvent : {} ) ) : WowzaPlayer

Note: onBitrateChanged isn't supported on iOS devices.

onBitrateChanged attaches an event listener function that's called when the viewer switches between bitrate renditions in an adaptive bitrate stream. Then, the method returns the current WowzaPlayer instance.

callback is a function that receives a bitrateChangedEvent object literal with two properties:

bitrateChangedEvent : {
   oldBitrate : number,
   newBitrate : number
}

Where oldBitrate is the previous bitrate and newBitrate is the new bitrate selected by the viewer or player. For example:

bitrateChangedListener = function ( bitrateChangedEvent ) {
    console.log('Old bitrate: ' + bitrateChangedEvent.oldBitrate);
    console.log('New bitrate: ' + bitrateChangedEvent.newBitrate);
};
myPlayer.onBitrateChanged( bitrateChangedListener );

removeOnBitrateChanged ( callback : function ( bitrateChangedEvent : {} ) ) : WowzaPlayer

removeOnBitrateChanged removes the requested event listener function and returns the current WowzaPlayer instance. For example:

myPlayer.removeOnBitrateChanged( bitrateChangedListener );

onStats, removeOnStats

onStats ( callback : function ( statsEvent : {} ) ) : WowzaPlayer

onStats attaches an event listener function that's called when statistics become available. Then, the method returns the current WowzaPlayer instance.

callback is a function that receives a statsEvent object literal. statsEvent has various properties describing HLS stream playback stats:

Property Description
totalBytes The cumulative total number of downloaded bytes.
totalDroppedFrames The cumulative total number of dropped frames.
throughput Calculated as lastBytesDownloaded / (lastDownloadDuration + lastParseDuration) * 1000.
bandwidth Calculated as lastBytesDownloaded / (lastDownloadDuration * 1000).
bitrate The current stream bitrate.
lastBytesDownloaded The number of bytes in the last chunk.
lastDownloadDuration The time spent downloading the last chunk (in milliseconds).
lastParseDuration The time spent parsing the last chunk (in milliseconds).

For example:

statsListener = function ( statsEvent ) {
    console.log('Total bytes: ' + statsEvent.totalBytes);
    console.log('Total dropped frames: ' + statsEvent.totalDroppedFrames);
    console.log('Throughput: ' + statsEvent.throughput);
    console.log('Bandwidth: ' + statsEvent.bandwidth);
    console.log('Bitrate: ' + statsEvent.bitrate);
    console.log('last download duration: ' + statsEvent.lastBytesDownloaded);
    console.log('Last parse duration: ' + statsEvent.lastParseDuration);
};
myPlayer.onStats( statsListener );

removeOnStats ( callback : function ( statsEvent : {} ) ) : WowzaPlayer

removeOnStats removes the requested event listener function and returns the current WowzaPlayer instance. For example:

myPlayer.removeOnStats (statsListener);

onPlayheadTime, removeOnPlayheadTime

onPlayheadTime ( callback : function ( playheadTimeEvent : {} ) ) : WowzaPlayer

onPlayheadTime attaches an event listener function that's called at 500-millisecond intervals throughout playback. Then, the method returns the current WowzaPlayer instance.

callback is a function that receives a playheadTimeEvent object literal that has one property. 

playheadTimeEvent : { time : number }

The playheadTimeEvent object has a property, time, which is the current playhead time (in milliseconds). For example:

playheadTimeListener = function ( playheadTimeEvent ) {
    console.log('Time: ' + event.time);
};
myPlayer.onPlayheadTime( playheadTimeListener );

removeOnPlayheadTime ( callback : function ( playheadTimeEvent : {} ) ) : WowzaPlayer

removeOnPlayheadTime removes the requested event listener function and returns the current WowzaPlayer instance. For example:

myPlayer.removeOnPlayheadTime( playheadTimeListener );

onError, removeOnError

onError ( callback : function ( errorEvent : {} ) ) : WowzaPlayer

onError attaches an event listener function that's called when an error occurs, and then returns the current WowzaPlayer instance.

callback is a function that receives an errorEvent object literal that has one property.

errorEvent : { message : string }

Where message explains the error that occurred. For example:

errorListener = function ( errorEvent ) {
    console.log('Message: ' + errorEvent.error);
};
myPlayer.onError( errorListener );

removeOnError ( callback : function ( errorEvent : {} ) ) : WowzaPlayer

removeOnError removes the requested event listener function and returns the current WowzaPlayer instance. For example:

myPlayer.removeOnError( errorListener );

onStateChange, removeOnStateChange

onStateChanged ( callback : function ( stateChangedEvent : {} ) ) : WowzaPlayer

onStateChanged attaches an event listener function that's called when the WowzaPlayer changes state. Then, the method returns the current WowzaPlayer instance.

callback is a function that receives a stateChangedEvent object literal with two properties:

stateChangedEvent : { previousState : number, currentState : number }

Where previousState is the previous player state, and currentState is the new player state. For example:

onStateChangedListener = function ( stateChangedEvent ) {
if (stateChangedEvent.currentState == WowzaPlayer.State.PLAYING) {
console.log('Playing');
} else if (stateChangedEvent.currentState == WowzaPlayer.State.PAUSED) {
console.log('Paused');
}
}
myPlayer.onStateChanged( stateChangedListener );

removeOnStateChanged ( callback : function ( stateChangedEvent : {} ) ) : WowzaPlayer

removeOnStateChanged removes the requested event listener function and returns the current WowzaPlayer instance. For example:

myPlayer.removeOnStateChanged (stateChangedListener);

onVolume, removeOnVolume

onVolume ( callback : function ( volumeEvent : {} ) ) : WowzaPlayer

onVolume attaches an event listener function that's called when the volume changes. Then, the method returns the current WowzaPlayer instance.

callback is a function that receives a volumeEvent object literal with two properties:

volumeEvent : { volume : number, muted : boolean }

Where volume is the current volume (a value from 0-100). muted is true when playback is muted and is false otherwise. For example:

volumeListener = function ( volumeEvent ) {
    console.log('Volume: ' + volumeEvent.volume);
    console.log('True: ' + volumeEvent.muted);
};
myPlayer.onVolume( volumeListener );

removeOnVolume ( callback : function ( volumeEvent : {} ) ) : WowzaPlayer

removeOnVolume removes the requested event listener function and returns the current WowzaPlayer instance.

myPlayer.removeOnVolume (onVolumeListener);

onMetadata, removeOnMetadata

onMetadata ( callback : function ( metaDataEvent : {} ) ) : WowzaPlayer

onMetadata attaches an event listener function that's called when metadata is available. When the onMetadata event listener is attached, the method returns the current WowzaPlayer instance.

Note: To make metadata available, you must configure Wowza Streaming Engine to insert ID3 tags into the stream. Based on the format of your stream, see How to insert ID3 data events into MPEG-TS streams or How to convert onTextData events in a live of VOD stream to timed events (ID3 tags) in an Apple HLS stream for more information.

callback is a function that receives a single metaDataEvent object literal with several properties:

metaDataEvent : { time : number, type : string, [additional data varies by type] }

Property Description
time The playback time, in milliseconds, at which the event occurred.
type A string representing the type of metadata.
[additional data varies by type] Additional properties might be passed from Wowza Streaming Engine based on the type of metadata and how you've configured Wowza Streaming Engine to insert the metadata (such as ID3 tags).

For example:

metaDataListener = function ( metaDataEvent ) {
    console.log('Time: ' + metaDataEvent.time);
    console.log('Type: ' + metaDataEvent.type);
};
myPlayer.onBitrateChanged( bitrateChangedListener );

removeOnMetadata ( callback : function ( metaDataEvent : {} ) ) : WowzaPlayer

removeOnMetadata removes the requested event listener function and returns the current WowzaPlayer instance.

myPlayer.removeOnMetadata( metaDataListener );

onPlay, removeOnPlay

onPlay ( callback : function ( playEvent : {} ) ) : WowzaPlayer

onPlay attaches an event listener function that's called when the player starts playing and returns the current WowzaPlayer instance.

callback is a function that receives a playEvent object literal with one property:

playEvent : { time : number }

Where time is the current playhead time in milliseconds. For example:

playListener = function ( playEvent ) {
    console.log('Time: ' + playEvent.time);
};
myPlayer.onPlay( playListener );

removeOnPlay ( callback : function () ) : WowzaPlayer

removeOnPlay removes the requested event listener function and returns the current WowzaPlayer instance. For example:

myPlayer.removeOnPlay (pauseListener);

onPause, removeOnPause

onPause ( callback : function ( pauseEvent : {} ) ) : WowzaPlayer

onPause attaches an event listener function that's called when playback is paused and returns the current WowzaPlayer instance.

callback is a function that receives a pauseEvent object literal with one property:

pauseEvent : { time : number }

Where time is the current playhead time in milliseconds. For example:

pauseListener = function ( pauseEvent ) {
    console.log('Time: ' + pauseEvent.time);
};
myPlayer.onPause( pauseListener );

removeOnPause ( callback : function () ) : WowzaPlayer

removeOnPause removes the requested event listener function and returns the current WowzaPlayer instance. For example:

myPlayer.removeOnPause (pauseListener);

onResume, removeOnResume

onResume ( callback : function ( resumeEvent : {} ) ) : WowzaPlayer

onResume attaches an event listener function that's called when the player resumes playing from a paused state and returns the current WowzaPlayer instance.

callback is a function that receives a resumeEvent object literal with one property:

resumeEvent : { time : number }

Where time is the current playhead time in milliseconds. For example:

resumeListener = function ( resumeEvent ) {
    console.log('Time: ' + resumeEvent.time);
};
myPlayer.onResume( resumeListener );

removeOnResume ( callback : function () ) : WowzaPlayer

removeOnResume removes the requested event listener function and returns the current WowzaPlayer instance. For example:

myPlayer.removeOnPause (removeListener);

onStop, removeOnStop

onStop ( callback : function ( stopEvent : {} ) ) : WowzaPlayer

onStop attaches an event listener function that's called when the player stops playing, commonly after a user interacts with a live stream. Then, the method returns the current WowzaPlayer instance.

callback is a function that receives a stopEvent object literal with one property:

stopEvent : { time : number }

Where time is the current playhead time in milliseconds. For example:

stopListener = function ( stopEvent ) {
    console.log('Time: ' + stopEvent.time);
};
myPlayer.onStop( stopListener );

removeOnStop ( callback : function () ) : WowzaPlayer

removeOnStop removes the requested event listener function and returns the current WowzaPlayer instance. For example:

myPlayer.removeOnStop (stopListener);

onCompleted, removeOnCompleted

onCompleted ( callback : function ( completedEvent : {} ) ) : WowzaPlayer

onCompleted attaches an event listener function that's called when playback completes and returns the current WowzaPlayer instance.

callback is a function that receives a completedEvent object literal with one property:

completedEvent : { time : number }

Where time is the current playhead time in milliseconds. For example:

completedListener = function ( completedEvent ) {
    console.log('Time: ' + completedEvent.time);
};
myPlayer.onCompleted( completedListener );

removeOnCompleted ( callback : function () ) : WowzaPlayer

removeOnCompleted removes the requested event listener function and returns the current WowzaPlayer instance. For example:

myPlayer.removeOnCompleted (completedListener);

onSeek, removeOnSeek

onSeek ( callback : function ( seekEvent : {} ) ) : WowzaPlayer

onSeek attaches an event listener function that's called when the player seeks and returns the current WowzaPlayer instance.

callback is a function that receives a seekEvent object literal with two properties:

seekEvent : { oldTime : number, newTime : number }

Where oldTime is the previous playhead time in milliseconds. newTime is the new playhead time in milliseconds. For example:

seekListener = function ( seekEvent ) {
    console.log('Old time: ' + seekEvent.oldTime);
    console.log('New time: ' + seekEvent.newTime);
};
myPlayer.onSeek( seekListener );

removeOnSeek ( callback : function () ) : WowzaPlayer

removeOnSeek removes the requested event listener function and returns the current WowzaPlayer instance. For example:

myPlayer.removeOnSeek (seekListener);

Stop a WowzaPlayer instance

The WowzaPlayer.destroy static method deallocates the WowzaPlayer instance that was created with the specified PlayerElement player ID.

destroy ( PlayerElement : string ) : WowzaPlayer

var myPlayer = WowzaPlayer.destroy('playerElement');

Originally Published: For Wowza Player 1.0 on 12-19-2016.

If you're having problems or want to discuss this article, post in our forum.