Playback Events

These API calls are used to retrieve and change the current playback state of the player.


.on('autostartNotAllowed')

Fires when the player is configured to autostart but the browser's settings are preventing it

{
    "code": 303220,
    "error": "The play method is not allowed by the user agent or the platform in the current context, possibly because the user denied permission.",
    "reason": "autoplayDisabled",
    "type": "autostartNotAllowed"
}
Property Description
code number Identifier for the error

See: Player Errors Reference (Web Player)
error string Error message
reason string Reason why the player could not autostart

This value is always autoplayDisabled.
type string Category of player event

This value is always autostartNotAllowed.


.on('buffer')

Fires when one of the following events occurs:

  • Player starts playback
  • Player enters a buffering state
{
  "type": "buffer",
  "newstate": "buffering",
  "oldstate": "idle",
  "reason": "loading"
}
Value Description
newstate string State to which the player moved

Possible Values:
  • buffering
  • idle
  • playing
  • paused
  • stalled
oldstate string State from which the player moved

Possible Values:
  • buffering
  • idle
  • playing
  • paused
  • stalled
reason string Reason why the buffer event occurred

Possible Values:
  • paused
  • loading
  • complete
  • stalled
  • error
type string Category of the event

This value is always buffer.


.on('complete')

Fires when the end of a video is reached, but not when one of the following occurs:

  • The viewer advances playlist items prior to the end of a video.
  • next() is called.
{
  "type": "complete"
}
Value Description
type string Category of the event

This value is always complete.


.on('error')

Signals a critical error in the playback process.

Returns an object with the following:

ValueDescriptionType
codeIdentifier for the error
See JW Player Errors Reference for a list of possible errors.
Number
messageText for the detected error
See JW Player Errors Reference for a list of possible errors.
String
sourceErrorLower level error or event, caught by the player, which resulted in this errorObject or null
typeCategory of error
This will always return error.
String


.on('firstFrame')

Fires when a video's first frame event occurs or the instant an audio file begins playback

Use this to determine the period of time between a user pressing play and the same user viewing their content. This event pinpoints when content playback begins.

{
    "loadTime": 118,
    "type": "firstFrame"
}
Property Description
loadTime number Time in milliseconds that elapses while the player transitions from a play attempt to a firstFrame event
type string Category of player event

This value is always firstFrame.


.on('idle')

Fires when the player enters the idle state

{  
  "type": "idle",  
  "newstate": "idle",  
  "oldstate": "playing",  
  "reason": "complete"  
}  
Value Description
newstate string State to which the player moved

Possible values:
  • idle
  • playing
  • paused
oldstate string State from which the player moved

Possible values:
  • buffering
  • playing
  • paused
reason string Reason why an idle event occurred

Possible values:
  • complete
  • idle
  • error
  • pause
type string Category of the event

Possible value:
  • idle


.on('pause')

Fires when non-advertising media within the player is paused

πŸ“˜

To listen for an ad break pause event, use .on('adPause')

Value Description
newstate string State to which the player moved

Possible values:
  • buffering
  • idle
  • loading
  • paused
  • playing
  • stalled
oldstate string State from which the player moved

Possible values:
  • buffering
  • idle
  • loading
  • paused
  • playing
  • stalled
pauseReason string Reason for the pause

Possible values:
  • external
  • interaction
  • viewable
reason string Reason why the pause event occurred

Possible values:
  • autostart
  • clickthrough
  • external
  • interaction
  • paused
type string Category of the event

Possible value:
  • pause
viewable number Whether the player is viewable

Possible values:
  • 1
  • 0


.on('play')

Fires when non-advertising media within the player begins playback

To listen for an ad break play event, use .on('adPlay').

{
  "type": "play",
  "newstate": "playing",
  "oldstate": "buffering",
  "reason": "playing",
  "playReason": "interaction",
  "viewable": 1
}
Value Description
newstate string State to which the player moved

Possible Values:
  • buffering
  • idle
  • loading
  • paused
  • playing
  • stalled
oldstate string State from which the player moved

Possible Values:
  • buffering
  • idle
  • loading
  • paused
  • playing
  • stalled
playReason string Reason for the play

Possible Values:
  • autostart
  • external (API usage)
  • interaction: Click, touch, keyboard
  • playlist: Auto-advancing
  • related-audio: Auto-advancing JW Recommendations playlist
  • related-interaction: Interaction to go to a JW Recommendations playlist item
reason string Reason why the play event occurred

Possible Values:
  • autostart
  • clickthrough
  • external
  • interaction
type string Category of the event

This value is always play.
viewable number Whether the player is viewable

Possible Values:
  • 1
  • 0


.on('playAttemptFailed')

Fired when playback is aborted or blocked. A failed play attempt does not result in a play. Pausing the video or changing the media results in play attempts being aborted. In mobile browsers play attempts are blocked when not started by a user gesture.

Returns an object with the following:

ValueDescriptionType
errorThe error that resulted from the play promise.Object
itemReturns everything in the playlist item.Object
playReasonThe reason for the play, such as interaction, API, external, or a custom reason.String


.on('playbackRateChanged')

Fires when the playback rate has been changed

{
    "playbackRate": 1.25,
    "type": "playbackRateChanged"
}
Property Description
playbackRate number New playback rate
type string Category of player event

This value is always playbackRateChanged.


.on('warning')

Signals a failure that is not critical to the setup or playback process

{
    "code": 305001,
    "sourceError": {
        "stack": "Error: Failed to load https://playertest-cdn.longtailvideo.com/assets/404/jwpsrv.js\n    at scriptTag.onerror (https://player-develop-test-jenkins.longtailvideo.com/builds/lastSuccessfulBuild/archive/bin-debug/jwplayer.js:8349:30)",
        "message": "Failed to load https://playertest-cdn.longtailvideo.com/assets/404/jwpsrv.js"
    },
    "type": "warning"
}
Property Description
code number Identifier for the error

See: Player Errors Reference (Web Player)
sourceError object | null Lower level error or event, caught by the player, which resulted in this error

See: sourceError
type string Category of player event

This value is always warning.

sourceError

Property Description
message string Text for the detected warning

See: Player Errors Reference (Web Player)
stack string Stack trace of the error that occurred

This value provides a detailed account of the sequence of function calls and events that led to the error.