Media Player API

The following sections provided the KONtx Media Player API reference documentation.

KONtx.control.MediaTransportOverlay

Toolbox media player transport keys user interface

See the section on KONtx.control.MediaTransportOverlay above.

KONtx.media.Playlist

Toolbox media player playlist

The KONtx.media.Playlist class provides a list of media entries for the KONtx Framework media player.

Example

Properties

Property

Type

Description

autostart

Boolean

Deprecated property. The default value is false.

forcePlay

Boolean

Set this to true to force playback of the lowest bitrate stream, even if the consumer’s bandwidth is detected as being lower than the lowest bitrate stream provided. An error event is returned from the KONtx media player if forcePlay is set to false and the consumer’s bandwidth tests lower than the lowest bitrate stream provided. The default value is true.

repeatAll

Boolean

Enables looping of the playlist when the playback finishes for the last entry in the playlist. If set to true the looping occurs, if set to false, playback will stop at the last entry of the playlist. The default value is false.

Methods

KONtx.media.Playlist addEntries(Array entries);

Adds multiple playlist entries to the playlist. The entries parameter is an Array of KONtx.media.PlaylistEntry objects. Returns the updated playlist.

KONtx.media.Playlist addEntry(KONtx.media.PlaylistEntry entry);

Adds the single given entry to the playlist. Calls the addEntries([entry]) method and returns the updated playlist.

KONtx.media.Playlist addEntryByURL(string url, int bitrate, int startIndex);

Allows you to add an entry using the url when all you have is a single bitrate to playback for each playlist entry. Returns the updated playlist.

void clearEntries();

Empties the playlist entries array.

void removeEntry(int index);

Removes the specified playlist entry with the index you provide.

KONtx.media.PlaylistEntry

Toolbox media player playlist entry

The KONtx.media.PlaylistEntry class provides a playlist entry for the KONtx Framework media player. The playlist entry configuration allows for providing the following instantiation options:

  • A url and bitrate.
  • Just a url.
  • An array of streams. Each element in the array is an object with a url property and a bitrate property. If the bitrate is not provided for a stream but is provided in the main config, then all streams without a provided bitrate inherit this value.
  • A url and an array of streams. Both will be appended together.
  • Nothing on instantiation, then calling addURL() to add an array of streams before adding the entry to the playlist.

If you provide multiple streams and do not provide multiple bitrates, then the stream that is selected will be non-deterministic. If you do provide multiple bitrates, but do not provide a connection bandwidth to the media player, then the highest bitrate stream will be selected. If you do provide a bitrate and a connection bandwidth to the media player, then the stream selected will be the fastest one supported by the consumer’s current connection speed.

Example

Properties

Property

Type

Description

url

string

The media URL. Default value is null.

bitrate

int

The bitrate of the video. Default value is null.

startIndex

int

The time index to start playback of the video. Default value is null.

streams

Array

An array of objects with a string url property and an integer bitrate property. If the bitrate is not provided for a stream item in the array but is provided in the main configuration KONtx.media.PlaylistEntry.bitrate, then all stream items in the streams array without a bitrate inherit this value. If a stream item in the array does not have a url, the error "Invalid stream: must at minimum provide a URL" is thrown.

Methods

KONtx.media.PlaylistEntry addURL(string url, int bitrate);

Creates a stream from the given url and bitrate and adds it to the streams array for this entry. If the url is null, the error "Invalid stream: must at minimum provide a URL" is thrown. Returns the updated entry.

Boolean streamsReady(function callback);

This method is called by the KONtx media player to see if the streams are ready before fetching them. If you have streams which expire quickly and need to be refetched immediately before playback, override this method, save the callback passed in as the parameter and return false. Once your streams are ready, call the callback handler and the media player will resume. Please note, this method will be called again after you call the callback handler, so you need to return true the second time through the method or you will create an endless loop of fetching fresh URLs.

KONtx.mediaplayer

Toolbox media player

The KONtx.mediaplayer interface defines the KONtx Framework media player API.

Example

Properties

Property

Type

Description

debugInternals

Object

Normally all of the inner workings of the API are enclosed behind a public/private API separation. The debugInternals property can be used via the console to gain access to the complete “private” scope. Do not access this method in your TV App code.

isPlaylistEntryActive

Boolean

Boolean indicating if the current playlist entry is in one of the active states. These states are currently defined as PLAY, PAUSE, FASTFORWARD, REWIND, BUFFERING, or INFOLOADED. This state list is subject to change.

playlist.currentEntry

KONtx.media.Playlist

The currently selected playlist entry if one is set.

playlist.currentIndex

Object

Object with entry and stream properties. The entry property is the zero-based index of the currently selected playlist entry (if one is selected). The stream property is the zero-based index of the currently selected stream in the playlist entry (if one is selected).

tvapi.activeControl

TVControl

The active TVControl object. Not for general use. Read-only.

tvapi.activeInput

TVNetworkInput

The active TVNetworkInput object. Not for general use. Read-only.

tvapi.activeOutput

TVOutput

The active TVOutput object. Not for general use. Read-only.

tvapi.activePath

TVPath

The active TVPath object. Not for general use. Read-only.

tvapi.currentHTTPErrorCode

int

The HTTP error code as returned by the tvapi.activeInput or -1 if no error. Read-only.

tvapi.currentMediaDuration

int

The length of the currently playing content in milliseconds. Read-only.

tvapi.currentPlayerState

int

The current player state to be compared against the constants.states enumeration. Read-only.

tvapi.currentTimeIndex

int

The current time index of the playing content in milliseconds. Read-only.

Methods

void control.fastforward(int increment);

Tells the media player to fast forward the current content at the specified increment if supported by the media player. Supported increments are 2, 4, 8, and 16. Anything else will be rounded up or limited to the nearest supported value. Not all OEMs support this operation.

void control.pause();

Pauses the currently playing content.

void control.play();

Causes play to be called on the OEM-specific player. Only call this method if you called pause, use playlist.start() instead to start initial playback.

void control.rewind(int increment);

Tells the player to rewind the current content at the specified increment if supported by the media player. Supported increments are 2, 4, 8, and 16. Anything else will be rounded up or limited to the nearest supported value. Not all OEMs support this operation.

void control.seek(float offset, Boolean absolute);

Tells the media player to seek to the specified offset in seconds. If true is passed as the absolute parameter, then the offset is considered to be an absolute offset rather than a relative offset from the current playback position.

void control.stop();

Stops playback of the currently playing content.

void control.streamswitch(KONtx.mediaplayer.constants.streamswitch method, Object config);

Tells the media player to perform a stream switch to an alternate stream for the same entry using the specified algorithm identified by the method parameter. The config parameter changes based on the method used. The KONtx.mediaplayer.constants.streamswitch.BANDWIDTH algorithm is used to provided an updated connection bitrate and margin. If you choose this option, the config parameter is an Object with bitrate and margin properties. The config.bitrate property is the bitrate of the consumer’s connection as tested through KONtx.speedtest. The config.margin property is the margin factor to apply to the consumer’s bandwidth. Valid values are between 0 and 1. The config.margin property defaults to 1 or what was previously set if not provided. See the method setConnectionBandwidth() for more details.

The KONtx.mediaplayer.constants.streamswitch.INDEX_CHANGE algorithm is used to increase or decrease the selected stream by a specified amount. If you choose this option, the config parameter is an Object with direction and offset_amount properties. The possible values for config.direction are String values up or down. The default value is down. The config.offset_amount property is the amount to shift up or down. If you provide a config.direction but not a config.offset_amount, then the config.offset_amount is defaulted to 1.

Object getDefaultViewportBounds();

Returns a bounds object with properties the same as setViewportBounds(). Currently all OEMs return {x:0, y:0, width:1920, height:1080}. The values for the returned object are subject to change as new OEM platforms are added. Always check for the proper values.

double getMaxBufferSize();

Returns as a double the maxiumum buffer size supported by the device in bytes. The default value is 30 MB.

void initialize();

Initializes the KONtx Media Player. Initialization only needs to happen once, but must be performed before any media playback is started.

KONtx.media.Playlist playlist.get();

Returns the playlist which is currently set on the media player.

void playlist.loadEntry(int entry);

Tells the media player to load and play the specified zero-based entry in the playlist.

void playlist.nextEntry();

Tells the media player to load and play the next entry in the playlist.

void playlist.previousEntry();

Tells the media player to load and play the previous entry in the playlist.

void playlist.set(KONtx.media.Playlist playlist);

Takes a playlist and saves it in the media player for usage.

void playlist.start();

Starts the playlist which is currently set on the media player.

void setConnectionBandwidth(int bitrate, float margin);

Sets the connection bitrate to the specified value. If margin is also provided (defaults to 1), then it is applied to the bitrate before using the bitrate to select a stream. If bitrate == 2000 and margin == 0.8, then that means the KONtx media player will not select any stream greater than 1600. Use this to provide “head room” to help eliminate buffering attempts caused by the consumer using their internet connection temporarily for other things.

void setViewportBounds(int x, int y, int width, int height);

Sets the viewport bounds to the specified values. The parameter x is the horizontal offset of the top left corner of the viewport. The parameter y is the vertical offset of the top left corner of the viewport. The parameter width is the width of the viewport. The parameter height is the height of the viewport. This method also accepts a single parameter in the format of the returned Object from the method getDefaultViewportBounds(), for example:

KONtx.mediaplayer.setViewportBounds(KONtx.mediaplayer.getDefaultViewportBounds());

Table of Contents