Media Player Event Handling

The KONtx.mediaplayer interface fires the following events to communicate the KONtx media player status with your app.

Media Player Events

The following events are sent by the KONtx.mediaplayer interface. Event-specific properties included in the event payload Object are described below:

Event

Description

onConnectionBandwidthChanged

Fired when the connection bandwidth is changed for the KONtx media player, for example, it is fired when you call the method KONtx.mediaplayer.setConnectionBandwidth(). The event.payload.bandwidth.previous.bitrate property is the previous bitrate. The event.payload.bandwidth.previous.margin property is the previous margin. The event.payload.bandwidth.current.bitrate property is the current bitrate. The event.payload.bandwidth.current.margin property is the current margin.

onControlFastForward

Fired when KONtx.mediaplayer.control.fastforward() is called. Calling the method event.preventDefault() will prevent the fast forward action from occurring. The event.payload.increment property is the speed increment as passed in to the fast forward method.

onControlPause

Fired when KONtx.mediaplayer.control.pause() is called. Calling the method event.preventDefault() will prevent the pause from occurring.

onControlPlay

Fired when KONtx.mediaplayer.control.play() is called. Calling the method event.preventDefault() will prevent the play action from occurring.

onControlRewind

Fired when KONtx.mediaplayer.control.rewind() is called. Calling the method event.preventDefault() will prevent the rewind action from occurring. The event.payload.increment property is the speed increment as passed in to the rewind method.

onControlSeek

Fired when KONtx.mediaplayer.control.seek() is called. Calling the method event.preventDefault() will prevent the seek action from occurring. The event.payload.offset property is the offset in seconds as provided to the KONtx.mediaplayer.control.seek() method as a float. The event.payload.absolute property is a Boolean of whether the offset is an absolute position (true) or is relative to the current playback position (false).

onControlStop

Fired when KONtx.mediaplayer.control.stop() is called. Calling the method event.preventDefault() will prevent the stop action from occurring.

onControlStreamSwitch

Fired when KONtx.mediaplayer.control.streamswitch() method is called. Calling the method event.preventDefault() will prevent the stream switch action from occurring. The event.payload.streamswitch.method property is the stream switch algorithm being used. The possible enum values are: KONtx.mediaplayer.constants.streamswitch.INDEX_CHANGE to shift bitrate up and down by a predetermined amount and KONtx.mediaplayer.constants.streamswitch.BANDWIDTH to specify a new bitrate and margin and to allow the media player to choose the best stream. The event.payload.streamswitch.config.direction property is the direction to change when the INDEX_CHANGE method is used. Possible valid values for direction are up and down, the default value is down. The event.payload.streamswitch.config.offset_amount property is the bitrate increment to increase or decrease when the INDEX_CHANGE method is used. This offset value can be more than the available stream bitrate. If you provide a direction but not an offset amount, then the offset amount is defaulted to 1. The event.payload.streamswitch.config.bitrate property is the specified bitrate when the BANDWIDTH method is used. The event.payload.streamswitch.config.margin property is the specified margin when the BANDWIDTH method is used.

onConvertToSpeed

Fired when an increment provided to rewind or fast forward is converted into a playback speed. If the increment is identical to 0, then the speed is set to 1. If the increment is not a valid number or is less than or equal to 2, then the speed is set to 2. If the increment is greater than 2 and less than or equal to 4, then the speed is set to 4. If the increment is greater than 4 and less than or equal to 8, then the speed is set to 8. If the increment is greater than 8, then the speed is set to 16.

onFastForwardRemoteKeyPress

Fired when the fast forward key is pressed on the remote control. No action is performed with this method. You must subscribe to this event and act on it for the key to respond. The event.payload.keyCode property is the code for the key which can be matched against the KONtx.mediaplayer.constants.keys enumeration.

onFindBestStream

Fired when the best stream from the list of available streams is being selected for this playlist entry. Calling the method event.preventDefault() will prevent the KONtx media player from attempting to find a stream.

onLoadNextPlaylistEntry

Fired when the playlist method KONtx.mediaplayer.playlist.nextEntry() is called. Calling the method event.preventDefault() will prevent the next entry from loading.

onLoadPlaylistEntry

Fired when a new playlist entry is loaded. Calling the method event.preventDefault() will prevent loading and playback from starting on this new entry. The event.payload.index property is the zero-based index of the playlist entry to be loaded.

onLoadPreviousPlaylistEntry

Fired when the playlist method KONtx.mediaplayer.playlist.previousEntry() is called. Calling the method event.preventDefault() will prevent the previous entry from loading.

onNewStreamSelected

Fired when a new stream of a playlist entry is selected. This could be fired on initial playback or after a stream switch has occurred.

onPauseRemoteKeyPress

Fired when the pause key is pressed on the remote control. To prevent the pause operation from being performed, subscribe to this event and call the method event.preventDefault() when it is fired. The event.payload.keyCode property is the code for the key which can be matched against the KONtx.mediaplayer.constants.keys enumeration.

onPlaybackBuffering

Fired when the media player starts buffering or rebuffering the current stream. Calling the method event.preventDefault() prevents the wait indicator display.

onPlaylistChange

Fired when the playlist is changed. Calling the method event.preventDefault() will prevent the playlist from being changed to the newly provided playlist. The event.payload.playlist is the playlist being set.

onPlaylistEnd

Fired when the end of the playlist is reached.

onPlaylistRepeat

Fired when the media player is repeating playback of the playlist if it has the KONtx.media.Playlist.repeatAll flag set. Calling the method event.preventDefault() will prevent restarting the playlist at the beginning. This does not fire an onPlaylistEnd event if the default is prevented.

onPlayPlaylistEntry

Fired when beginning playback of a new playlist entry. This is one of the first events fired when playback is started on a new entry. Calling the method event.preventDefault() will prevent playback from starting.

onPlayRemoteKeyPress

Fired when the play key is pressed on the remote control. To prevent the play operation from being performed, subscribe to this event and call the method event.preventDefault() when it is fired. The event.payload.keyCode property is the code for the key which can be matched against the KONtx.mediaplayer.constants.keys enumeration.

onProcessPlaylistEntry

Fired when a new playlist entry is picked to play. Calling the method event.preventDefault() will prevent playback from starting. The event.payload.entry is the playlist entry picked to start playback.

onRemoteKeyPress

Fired when any play control key is pressed on the remote control. If you call the method event.preventDefault() on this event, the specialized events for specific play control keys below will not be fired. This is a good way to handle all keys with a single handler. The event.payload.keyCode property is the code for the key which can be matched against the KONtx.mediaplayer.constants.keys enumeration.

onResetBufferingCount

Fired when the buffering count is reset. This is typically done when a new playlist entry is started. Calling the method event.preventDefault() will prevent the buffering count from being reset. The event.payload.bufferingCount property is the number of buffering attempts before the reset is performed.

onRewindRemoteKeyPress

Fired when the rewind key is pressed on the remote control. No action is performed with this method. You must subscribe to this event and act on it for the key to respond. The event.payload.keyCode property is the code for the key which can be matched against the KONtx.mediaplayer.constants.keys enumeration.

onSetPlaybackSpeed

Fired when the playback speed is changed, for example for the rewind or fast forward operation. Calling the method event.preventDefault() will prevent the playback speed from being changed. The event.payload.speed.previous property is the integer value for the previous speed. The event.payload.speed.current property is the integer value for the current speed. A negative value indicates the rewinding speed and a value greater than one indicates the fast forwarding speed.

onSetScreensaverMode

Fired when the state of the screensaver is changed. After a pause or stop event, the screensaver is set to activate after a time period of inactivity. In all other media player states the screensaver does not activate and cannot interrupt content playback. Calling the method event.preventDefault() will prevent the state of the screensaver from changing. The event.payload.mode property has the value on if the screensaver is allowed to activate and off if the screensaver is not allowed to activate.

onStartPlaylist

Fired when you call the method KONtx.mediaplayer.playlist.start() on a playlist. Calling the method event.preventDefault() will prevent playback from starting.

onStartStreamPlayback

Fired when the media player is about to start playback. Calling the method event.preventDefault() will prevent the KONtx media player from starting playback. The event.payload.selectedURL is the URL about to start playback. The event.payload.startIndex is the time index to start playback of the selected URL. The event.payload.callbackHandler is a callback to start playback yourself. This provides an alternative method to change the URL just before playback. By calling the method event.preventDefault() on the event and then calling event.payload.callbackHandler(url, timeIndex) you can provide an alternative url to play along with a new timeIndex. This is not a general use case. Instead you should use custom playlist entry Objects to change the URL.

onStateChange

Fired when the TV’s media player changes state. Match the states against the KONtx.mediaplayer.constants.states enumeration. Do not call the method event.preventDefault() on this event. The event.payload.newState property is the new state into which the player just transitioned. The event.payload.previousState property is the state the player was in before this event happened.

onStopRemoteKeyPress

Fired when the stop key is pressed on the remote control. To prevent the stop operation from being performed, subscribe to this event and call the method event.preventDefault() when it is fired. The event.payload.keyCode property is the code for the key which can be matched against the KONtx.mediaplayer.constants.keys enumeration.

onStreamLoadError

Fired when a stream is not available. Usually this event is fired because the playlist is empty or the current playlist entry does not contain any streams.

onTimeIndexChanged

Fired approximately once per second during content playback and provides the current time index. The event.payload.timeIndex property is the current position in the content playback in seconds. The event.payload.duration property is the length of the currently playing content in seconds. The event.payload.rawTimeIndex property is the current position in the content playback in milliseconds. The event.payload.rawDuration property is the length of the currently playing content in milliseconds.

onViewportBoundsChanged

Fired when the video playback viewport bounds are changed by calling the method setViewportBounds(). The event.payload.viewport.previous.x property is the previous horizontal coordinate of the top left corner of the viewport. The event.payload.viewport.previous.y property is the previous vertical coordinate of the top left corner of the viewport. The event.payload.viewport.previous.width property is the previous width of the viewport. The event.payload.viewport.previous.height property is the previous height of the viewport. The event.payload.viewport.current.x property is the current horizontal coordinate of the top left corner of the viewport. The event.payload.viewport.current.y property is the current vertical coordinate of the top left corner of the viewport. The event.payload.viewport.current.width property is the current width of the viewport. The event.payload.viewport.current.height property is the current height of the viewport.

Media Player Event Payload Properties

The KONtx media player events rely on the event payload Object, event.payload, for both default properties and event-specific properties. The default properties are available on all KONtx media player events while the event-specific properties are only available when a specific event has fired. The default properties and event-specific properties are described in the table below. The event-specific properties are also listed with each event description above.

Property

Type

Description

absolute

event-specific

A Boolean of whether the seek offset event.payload.offset is an absolute position (true) or is relative to the current playback position (false) as provided to the KONtx.mediaplayer.control.seek() method. Set by the onControlSeek event.

bandwidth.current.bitrate

event-specific

The current bitrate. Set by the onConnectionBandwidthChanged event.

bandwidth.current.margin

event-specific

The current margin. Set by the onConnectionBandwidthChanged event.

bandwidth.previous.bitrate

event-specific

The previous bitrate. Set by the onConnectionBandwidthChanged event.

bandwidth.previous.margin

event-specific

The previous margin. Set by the onConnectionBandwidthChanged event.

bufferingCount

event-specific

The number of buffering attempts since the last reset was performed. The bufferingCount property is reset following the onResetBufferingCount event being fired and is incremented each time a buffering event occurs.

callbackHandler( String url, int timeIndex)

event-specific

The callback to start playback in your code. This provides an alternative method to change the content’s URL just before playback. By calling event.preventDefault() and then event.payload.callbackHandler(String url, int timeIndex) you can provide an alternative url to play along with a new timeIndex. This is not a general use case. Instead you should use custom playlist entry Objects to change the URL. Set by the onStartStreamPlayback event.

duration

event-specific

The length of the currently playing content in seconds. Set by onTimeIndexChanged event.

entry

event-specific

The playlist entry picked to start playback. Set by the onProcessPlaylistEntry event.

increment

event-specific

The speed increment as passed to the KONtx.mediaplayer.control.fastforward() method. Set by the onControlFastForward and onControlRewind events.

index

event-specific

The zero-based index of the playlist entry to be loaded. Set by the onLoadPlaylistEntry event.

keyCode

event-specific

The code for the key that triggered the event which can be matched against the KONtx.mediaplayer.constants.keys enumeration. Set by the following events: onRemoteKeyPress, onPauseRemoteKeyPress, onStopRemoteKeyPress, onPlayRemoteKeyPress, onRewindRemoteKeyPress, and onFastForwardRemoteKeyPress.

mode

event-specific

The event property has a value of on if the screensaver is allowed to activate and off if the screensaver is not allowed to activate. Set by the onSetScreensaverMode event.

newState

event-specific

The new state into which the OEM-specific media player has transitioned. This state can be matched against the KONtx.mediaplayer.constants.states enumeration. Set by the onStateChange event.

offset

event-specific

The seek offset in seconds as provided to the KONtx.mediaplayer.control.seek() method as a float. The event.payload.absolute property is a Boolean of whether the seek offset is an absolute position (true) or is relative to the current playback position (false) . Set by the onControlSeek event.

previousState

event-specific

The state in which the OEM-specific media player was in before transitioning on an event. This state can be matched against the KONtx.mediaplayer.constants.states enumeration. Set by the onStateChange event.

player

default

KONtx Media Player event payload.

player.bandwidth

default

Hash which contains the following properties: bitrate and margin.

player.bandwidth.bitrate

default

The bitrate of the consumer’s connection as provided to the KONtx.mediaplayer interface.

player.bandwidth.margin

default

The margin to apply to the bitrate as provided to the KONtx.mediaplayer interface.

player.keys

default

Enumeration of the remote keys which can be pressed by the user. Use only these keys: PAUSE, STOP, REWIND, PLAY, and FASTFORWARD.

player.media

default

Hash containing the following properties: playlist, playlist_index, currentEntry, stream_index, stream_count, and buffering_count.

player.media.buffering_count

default

Numerical count of the number of times this entry has had a buffering event.

player.media.currentEntry

default

A reference to the current playlist entry which is loaded or playing.

player.media.playlist

default

A reference to the current playlist.

player.media.playlist_index

default

Zero based index of the current playlist item.

player.media.stream_count

default

Count of the number of streams in the current playlist entry.

player.media.stream_index

default

Zero based index of the stream selected in the current playlist entry.

player.states

default

Enumeration of all possible states of the player. Use only these keys: INIT, PLAY, PAUSE, FASTFORWARD, REWIND, STOP, BUFFERING, BUFFEREMPTY, INFOLOADED, EOF, UNKOWN, and ERROR.

player.tvapi

default

Hash containing the following properties: control, path, input, output, state, timeIndex, and mediaDuration.

player.tvapi.control

default

Reference to the TVControl Object. Not for general use.

player.tvapi.input

default

Reference to the TVNetworkInput Object. Not for general use.

player.tvapi.mediaDuration

default

Length of the currently playing stream in milliseconds. Read-only.

player.tvapi.output

default

Reference to the TVOutput Object. Not for general use.

player.tvapi.path

default

Reference to the TVPath Object. Not for general use.

player.tvapi.state

default

Integer from the KONtx.mediaplayer.constants.states enumeration of the current playback state. Read-only.

player.tvapi.timeIndex

default

Current time index in milliseconds. Read-only.

playlist

event-specific

The playlist being set. Set by the onPlaylistChange event.

rawDuration

event-specific

The length of the currently playing content in millisconds. Set by the onTimeIndexChanged event.

rawTimeIndex

event-specific

Current position in the content playback in milliseconds. Set by the onTimeIndexChanged event.

selectedURL

event-specific

The URL about to start playback. The event.payload.startIndex is the time index to start playback of the selected URL. Set by the onStartStreamPlayback event.

speed.current

event-specific

The integer value for the current speed. A negative value indicates the rewinding speed and a value greater than one indicates the fast forwarding speed. Set by the onSetPlaybackSpeed event.

speed.previous

event-specific

The integer value for the previous speed. A negative value indicates the rewinding speed and a value greater than one indicates the fast forwarding speed. Set by the onSetPlaybackSpeed event.

startIndex

event-specific

The time index to start playback of the event.payload.selectedURL. Set by the onStartStreamPlayback event.

streamswitch.config.bitrate

event-specific

The specified bitrate when the KONtx.mediaplayer.constants.streamswitch.BANDWIDTH algorithm is used to switch streams. Set by the onControlStreamSwitch event.

streamswitch.config.direction

event-specific

The direction to change (String values up or down, the default is down) when the stream switch algorithm is KONtx.mediaplayer.constants.streamswitch.INDEX_CHANGE. The event.payload.streamswitch.config.offset_amount property is the bitrate increment to increase or decrease. If you provide a direction but not an offset amount, then the offset amount is defaulted to 1. Set by the onControlStreamSwitch event.

streamswitch.config.margin

event-specific

The specified margin when the KONtx.mediaplayer.constants.streamswitch.BANDWIDTH algorithm is used to switch streams. Set by the onControlStreamSwitch event.

streamswitch.config.offset_amount

event-specific

The bitrate increment to increase or decrease when the stream switch algorithm is KONtx.mediaplayer.constants.streamswitch.INDEX_CHANGE. This offset amount can be more than the available stream bitrate.

The event.payload.streamswitch.config.direction is the direction to change (String values up or down, the default is down). If you provide a direction but not an offset amount, then the offset amount is defaulted to 1. Set by the onControlStreamSwitch event.

streamswitch.method

event-specific

The stream switch algorithm being used by the KONtx.mediaplayer.control.streamswitch() method. The possible enumeration values are: KONtx.mediaplayer.constants.streamswitch.INDEX_CHANGE to shift bitrate up and down by a predetermined amount and KONtx.mediaplayer.constants.streamswitch.BANDWIDTH to specify a new bitrate and margin and to allow the media player to choose the best stream. Set by the onControlStreamSwitch event.

timeIndex

event-specific

The current position in the content playback in seconds. Set by the onTimeIndexChanged event.

viewport.current.height

event-specific

The current height of the viewport. Set by the onViewportBoundsChanged event.

viewport.current.width

event-specific

The current width of the viewport. Set by the onViewportBoundsChanged event.

viewport.current.x

event-specific

The current horizontal coordinate of the top left corner of the viewport. Set by the onViewportBoundsChanged event.

viewport.current.y

event-specific

The current vertical coordinate of the top left corner of the viewport. Set by the onViewportBoundsChanged event.

viewport.previous.height

event-specific

The previous height of the viewport. Set by the onViewportBoundsChanged event.

viewport.previous.width

event-specific

The previous width of the viewport. Set by the onViewportBoundsChanged event.

viewport.previous.x

event-specific

The previous horizontal coordinate of the top left corner of the viewport. Set by the onViewportBoundsChanged event.

viewport.previous.y

event-specific

The previous vertical coordinate of the top left corner of the viewport. Set by the onViewportBoundsChanged event.

Table of Contents