Interface MKPlayerAPI

MKPlayer API.

Hierarchy

MKPlayerAPI

Index

Methods

addCastMetadata addSubtitle castStop castVideo destroy disableSubtitle enableSubtitle getAspectRatio getAudio getAudioQuality getAvailableAudio getAvailableAudioQualities getAvailableSubtitles getAvailableVideoQualities getBufferLevel getBufferedRanges getCatchupConfig getCurrentTime getDownloadedAudioData getDownloadedVideoData getDroppedVideoFrames getDuration getFallbackConfig getLatency getMaxTimeShift getPlaybackAudioData getPlaybackSpeed getPlaybackVideoData getSeekableRange getTargetLatency getThumbnail getTimeShift getTotalStalledTime getVersion getVideoContainer getVideoElement getVideoQuality getViewMode getVolume hasEnded isAirplayActive isAirplayAvailable isCastAvailable isCasting isLive isMuted isPaused isPlaying isStalled isViewModeAvailable load mute off on pause play preload removeSubtitle seek seekToLiveEdge setAspectRatio setAudio setAudioQuality setAuthorizationToken setCatchupConfig setFallbackConfig setInhomeStatus setLocationDetail setLogLevel setPlaybackSpeed setPosterImage setTargetBufferLevel setTargetLatency setVideoElement setVideoQuality setViewMode setVolume showAirplayTargetPicker unload unmute

Methods

addCastMetadata

addCastMetadata(metadata): boolean
Sends custom metadata to a remote receiver app (e.g. Chromecast).
Parameters
- metadata: any
  
  the custom metadata to send to the receiver.
Returns boolean
true if it was successful.

addSubtitle

addSubtitle(subtitleTrack): void
Adds a subtitle track.

isFragmented type of subtitle tracks are not supported when added via this method.
Parameters
- subtitleTrack: MKSubtitleTrack
Returns void

castStop

castStop(): void
Stops a running Cast session (i.e. isCasting returns true).

Has no effect if isCasting returns false.

Returns void

castVideo

castVideo(): void
Initiates casting the current video to a Cast-compatible device.

The user has to choose the target device.

Returns void

destroy

destroy(): Promise<void>
Unloads the player and removes all inserted HTML elements and event handlers.

Returns Promise<void>
Promise resolves when the player has cleaned up all its event handlers & resources.

disableSubtitle

disableSubtitle(subtitleID): void
Disables an already enabled subtitle track.
Parameters
- subtitleID: string
  
  the subtitle track identifier.
Returns void

enableSubtitle

enableSubtitle(subtitleID): void
Enables a subtitle track.
Parameters
- subtitleID: string
  
  the subtitle track identifier.
Returns void

getAspectRatio

getAspectRatio(): number
Returns the current aspect ratio of the player, or 0 if there is no style module.

Note: the default player aspect ratio is 16:9.

Returns number
A number indicating the player aspect ratio (e.g. 1.6 for 16:10) or 0 in case of error.

getAudio

getAudio(): null | MKAudioTrack
Returns the currently used audio track, or null if no track is active.

Returns null | MKAudioTrack

getAudioQuality

getAudioQuality(): null | MKAudioQuality
Returns the currently selected audio quality.

One of the elements of getAvailableAudioQualities.

Returns null | MKAudioQuality

getAvailableAudio

getAvailableAudio(): MKAudioTrack[]
Returns an array of all available audio tracks.

Returns MKAudioTrack[]

getAvailableAudioQualities

getAvailableAudioQualities(): MKAudioQuality[]
Returns an array of all available audio qualities the player can adapt between.

Returns MKAudioQuality[]

getAvailableSubtitles

getAvailableSubtitles(): MKSubtitleTrack[]
Get list of all available subtitle tracks.

Returns MKSubtitleTrack[]
list of available subtitle tracks when available or an empty array when not available.

getAvailableVideoQualities

getAvailableVideoQualities(): MKVideoQuality[]
Returns an array containing all available video qualities the player can adapt between.

Returns MKVideoQuality[]

getBufferLevel

getBufferLevel(type, media): null | MKBufferLevel
Returns the current and target buffer level for the given buffer type and media type.
Parameters
- type: MKBufferType
  
  the buffer type for which to get the buffer level for.
- media: MKMediaType
  
  the media type for which to get the buffer level for.
Returns null | MKBufferLevel
the buffer level object or null in case of error.

getBufferedRanges

getBufferedRanges(): MKTimeRange[]
Returns the currently buffered time ranges of the video element.

Returns MKTimeRange[]

getCatchupConfig

getCatchupConfig(): null | MKLowLatencySyncConfig
Returns the current latency sync configuration for catchup.

Returns null | MKLowLatencySyncConfig
the catchup sync configuration.

getCurrentTime

getCurrentTime(mode?): number
Returns the current playback time in seconds of the video.
Parameters
- Optional mode: MKTimeMode
  
  The mode to decide if the returned time should be absolute or relative, see MKTimeMode.
  
  For Live and Events the default mode is AbsoluteTime. For VOD, Catchup and DVR its RelativeTime.
Returns number

getDownloadedAudioData

getDownloadedAudioData(): null | MKDownloadedAudioData
Returns data about the last downloaded audio segment.

Returns null | MKDownloadedAudioData

getDownloadedVideoData

getDownloadedVideoData(): null | MKDownloadedVideoData
Returns data about the last downloaded video segment.

Returns null | MKDownloadedVideoData

getDroppedVideoFrames

getDroppedVideoFrames(): number
Returns the total number of dropped video frames since playback started.

Returns number

getDuration

getDuration(): number
Returns the total duration in seconds of the current video.

Returns number

getFallbackConfig

getFallbackConfig(): null | MKLowLatencySyncConfig
Returns the current latency sync configuration for fallback.

Returns null | MKLowLatencySyncConfig
the fallback sync configuration.

getLatency

getLatency(): number
Returns the current latency in seconds.

Returns number
the current latency in seconds.

getMaxTimeShift

getMaxTimeShift(): number
Returns the limit in seconds for time shift.

Is either negative or 0 and applicable to live streams only.

Returns number

getPlaybackAudioData

getPlaybackAudioData(): null | MKAudioQuality
Returns data about the currently playing audio segment.

Returns null | MKAudioQuality

getPlaybackSpeed

getPlaybackSpeed(): number
Returns the current playback speed of the player.

1 is the default playback speed, values between 0 and 1 refer to slow motion and values greater than 1 refer to fast forward.

Values less or equal zero are ignored.

Returns number

getPlaybackVideoData

getPlaybackVideoData(): null | MKVideoQuality
Returns data about the currently playing video segment.

Returns null | MKVideoQuality

getSeekableRange

getSeekableRange(mode?): null | MKTimeRange
Returns the time range that is currently valid for seeking.

Note For VOD default mode is RelativeTime and for Live it is AbsoluteTime.
Parameters
- Optional mode: MKTimeMode
  
  The mode to decide if the returned time should be absolute or relative, see MKTimeMode.
Returns null | MKTimeRange
the current seekable range when available or null otherwise.

getTargetLatency

getTargetLatency(): number
Returns the current target latency in seconds.

Returns number
target latency in seconds.

getThumbnail

getThumbnail(time): null | MKThumbnail
Returns a thumbnail image for a certain time or null if there is no thumbnail available.

Requires a configured thumbnails track in thumbnailTrack if sideloaded thumbnails are configured.

Requires enableHlsImageMediaPlaylistSupport to be true if thumbnail images from the HLS manifest are needed.

When thumbnailTrack are configured, this will have preference over the thumbnails found in the HLS manifest.
Parameters
- time: number
  
  the media time for which the thumbnail should be returned.
Returns null | MKThumbnail
A thumbnail if a thumbnails track is configured and a thumbnail exists for the specified time, else null.

getTimeShift

getTimeShift(): number
Returns the current time shift offset to the live edge in seconds.

Is either negative or 0 and applicable to live streams only.

Offset 0 indicates the current live edge.

Returns number

getTotalStalledTime

getTotalStalledTime(): number
Returns the stalled time in seconds since playback started.

Returns number

getVersion

getVersion(): string
Returns current MKPlayer SDK version.

Returns string

getVideoContainer

getVideoContainer(): HTMLElement
Returns the html element that the player is embedded in, which has been provided in the player constructor.

Returns HTMLElement

getVideoElement

getVideoElement(): undefined | HTMLVideoElement
Returns the used HTML5 video element.

Returns undefined | HTMLVideoElement

getVideoQuality

getVideoQuality(): null | MKVideoQuality
Returns the currently selected video quality, if the user manually selected one.

In this case it returns one of the elements of getAvailableVideoQualities.

Returns null | MKVideoQuality

getViewMode

getViewMode(): null | MKViewMode
Gets the active MKViewMode.

Returns null | MKViewMode

getVolume

getVolume(): number
Returns the player’s volume between 0 (silent) and 100 (max volume).

Returns number

hasEnded

hasEnded(): boolean
Returns true if the video has ended.

Returns boolean

isAirplayActive

isAirplayActive(): boolean
Checks if Apple Airplay is enabled.

Returns boolean

isAirplayAvailable

isAirplayAvailable(): boolean
Checks if Apple AirPlay support is available.

Returns boolean

isCastAvailable

isCastAvailable(): boolean
Returns true if casting to another device (such as a ChromeCast) is available, otherwise false.

Please note that this function only returns true after the CastAvailable event has fired.

Returns boolean

isCasting

isCasting(): boolean
Returns true if the video is currently casted to a device and not played in the browser, or false if the video is played locally.

Returns boolean

isLive

isLive(): boolean
Return true if the displayed video is a live stream.

Returns boolean

isMuted

isMuted(): boolean
Returns true if the player has been muted.

Returns boolean

isPaused

isPaused(): boolean
Returns true if the player has started playback but is currently paused.

Returns boolean

isPlaying

isPlaying(): boolean
Returns true if the player is currently playing, i.e. has started and is not paused.

Returns boolean

isStalled

isStalled(): boolean
Returns true if the player is currently stalling due to an empty buffer.

Returns boolean

isViewModeAvailable

isViewModeAvailable(viewMode): boolean
Tests if a particular ViewMode is available for selection with setViewMode.
Parameters
- viewMode: MKViewMode
  
  the view mode to test.
Returns boolean
true if the tested view mode is available, else false.

load

load(sourceConfig, disableSeeking?): Promise<void>
Sets a new video source and returns a promise which resolves when the source has loaded successfully.
Parameters
- sourceConfig: MKSourceConfig
  
  the source configuration object.
- Optional disableSeeking: boolean
  
  If set, seeking will be disabled.
Returns Promise<void>
Promise which resolves when the source is loaded and rejects when load fails.

mute

mute(issuer?): void
Mutes the player if an audio track is available. Has no effect if the player is already muted.
Parameters
- Optional issuer: string
  
  The issuer of the API call that will be passed to events triggered by this call.
Returns void

off

off(eventType, callback): void
Removes a handler for a player event.
Parameters
- eventType: MKPlayerEvent
  
  The event to remove the handler from.
- callback: MKPlayerEventCallback
  
  The callback handler to remove.
Returns void

on

on(eventType, callback): void
Subscribes an event handler to a player event.
Parameters
- eventType: MKPlayerEvent
  
  The type of event to subscribe to.
- callback: MKPlayerEventCallback
  
  The event callback handler that will be called when the event fires.
Returns void

pause

pause(issuer?): void
Pauses the video if it is playing. Has no effect if the player is already paused.
Parameters
- Optional issuer: string
  
  The issuer of the API call that will be passed to events triggered by this call.
Returns void

play

play(issuer?): Promise<void>
Starts playback or resumes after being paused.

No need to call it if the player is stup with autoplay.

Calling play has no effect when player is already playing.
Parameters
- Optional issuer: string
  
  the issuer of the API call that will be passed to events triggered by this call.
Returns Promise<void>
a promise which resolves as soon as playback starts. The promise can reject if the play is blocked by the browser.

preload

preload(): void
Starts preloading the content of the currently loaded source.

Returns void

removeSubtitle

removeSubtitle(subtitleID): void
Removes a subtitle track.

Disables it in case it's enabled before removal.
Parameters
- subtitleID: string
  
  the identifier of the subtitle track to remove.
Returns void

seek

seek(time, issuer?): boolean
Seeks to the given playback time specified by the parameter time in seconds.

The time offset specified must always be a positive value.

For VOD, Catchup or DVR specified time must not be greater than the total duration of the video.

For Live and Events the specified time either be relative or absolute offset.
- Calling seek(0) will take you to the start of the live window
- Calling seek(getSeekableRange().end) will take you near the current live edge. You can also call () to jump to current live edge easily.
Parameters
- time: number
  
  The time to seek to in seconds.
- Optional issuer: string
  
  The issuer of the API call that will be passed to events triggered by this call.
Returns boolean
true when successful.

seekToLiveEdge

seekToLiveEdge(issuer?): void
Seeks to the current live edge.

Applicable only for live sources.
Parameters
- Optional issuer: string
  
  The issuer of the API call that will be passed to events triggered by this call.
Returns void

setAspectRatio

setAspectRatio(aspectratio): void
Modifies the current aspect ratio of the player.
Parameters
- aspectratio: string | number
  
  The desired aspect ratio for the player. It can be a string (e.g. '16:9' or '16/9'), or a number (e.g 1.6 for 16:10).
Returns void

setAudio

setAudio(trackID): void
Sets the audio track to the ID specified by trackID.

Available tracks can be retrieved with getAvailableAudio.
Parameters
- trackID: string
  
  The ID of the audio track to activate.
Returns void

setAudioQuality

setAudioQuality(audioQualityID): void
Manually sets the audio stream to a fixed quality, identified by ID.

Has to be an ID defined in the MPD or the keyword 'auto'.

Auto resets to dynamic switching.

A list with valid IDs can be retrieved by calling getAvailableAudioQualities.
Parameters
- audioQualityID: string
  
  The ID of the desired audio quality or 'auto' for dynamic switching.
Returns void

setAuthorizationToken

setAuthorizationToken(authorizationToken): void
Set authorization token.

Note: this is applicable only for registered source streams and during an ongoing playback session to update an authorization token that is about to expire (token refresh). Setting this before calling load will have no effect and it is expected to have the updated authorization token as part of the azuki config in the registered source config object passed to start playback of a next source.
Parameters
- authorizationToken: string
  
  the new authorization token.
Returns void

setCatchupConfig

setCatchupConfig(config): void
Sets the configuration specifying parameters for latency catchup.
Parameters
- config: MKLowLatencySyncConfig
  
  the sync configuration for latency catchup.
Returns void

setFallbackConfig

setFallbackConfig(config): void
Sets the configuration specifying parameters for latency fallback.
Parameters
- config: MKLowLatencySyncConfig
  
  the sync configuration for latency fallback.
Returns void

setInhomeStatus

setInhomeStatus(inhomeStatus): void
Set inhome status.

Note: this is applicable only for registered source streams. This setting will only be applied when the next playback session starts. So it is expected to call this before calling load.
Parameters
- inhomeStatus: boolean
  
  the new inhome status value.
Returns void

setLocationDetail

setLocationDetail(locationDetail): void
Set location detail information.

Note: this is applicable only for registered source streams. This setting will only be applied when the next playback session starts. So it is expected to call this before calling load.
Parameters
- locationDetail: string
  
  the new location details as base64 encoded string.
Returns void

setLogLevel

setLogLevel(level): void
Sets the level of player log outputs.
Parameters
- level: MKLogLevel
  
  Log level, allowed values are "debug", "log", "warn", "error" and "off"
Returns void

setPlaybackSpeed

setPlaybackSpeed(speed): void
Sets the playback speed of the player.

Available only for HTML5 player.

Fast forward as well as slow motion is supported.

Slow motion is used by values between 0 and 1, fast forward by values greater than 1.
Parameters
- speed: number
  
  A playback speed factor greater than 0.
Returns void

setPosterImage

setPosterImage(url, keepPersistent): void
Sets a poster image. Will be displayed immediately, even if a video stream is playing.
Parameters
- url: string
  
  The URL to the poster image.
- keepPersistent: boolean
  
  Flag to set the poster image persistent so it is also displayed during playback (useful for audio-only playback).
Returns void

setTargetBufferLevel

setTargetBufferLevel(type, value, media): void
Sets the target buffer level for the chosen buffer and media type.
Parameters
- type: MKBufferType
  
  the buffer type to change the target buffer level for.
- value: number
  
  the value to set.
- media: MKMediaType
  
  the media type to change the target buffer level for.
Returns void

setTargetLatency

setTargetLatency(latency): void
Sets the target latency to be maintained during playback.

Causes firing a TargetLatencyChanged event.
Parameters
- latency: number
  
  the target latency in seconds.
Returns void

setVideoElement

setVideoElement(videoElement): void
Passes an HTML video element to the player, which should be used in case of Html5 or Native playback.

For this to take effect you must call this function before calling load.

When no video element is set on the player, the player will create one for use internally. You may call getVideoElement to get hold of the video element in use by the player.

Also the video element should be contained within the video container element that was passed as part of player creation.

Example:
```
' In the HTML body
<div id="videoContainer">
    <video id="videoElement"></video>
</div>

' In the script
let videoContainer = document.getElementById("videoContainer");
let videoElement = document.getElementById("videoElement");
let playerConfig = {
    key: "<license_key>",
    playback: {
        autoplay: true,
        muted: true
    }
};

let player = new mkplayer.MKPlayer(playerConfig, videoContainer);
player.setVideoElement(videoElement);
player.load(sourceConfig);
```
Parameters
- videoElement: HTMLVideoElement
  
  the video element to set.
Returns void

setVideoQuality

setVideoQuality(videoQualityID): void
Manually sets the video stream to a fixed quality, identified by ID.

Has to be an ID defined in the Manifest/MPD or the keyword 'auto'.

Auto resets to dynamic switching.

A list with valid IDs can be retrieved by calling getAvailableVideoQualities.
Parameters
- videoQualityID: string
  
  ID defined in the Manifest/MPD or 'auto'.
Returns void

setViewMode

setViewMode(viewMode, options?): void
Sets the player to a particular ViewMode.

Will only work if the selected view mode is available and isViewModeAvailable returns true, else this call will be ignored.

If successful, a ViewModeChanged will be fired.
Parameters
- viewMode: MKViewMode
  
  the view mode to switch the player into.
- Optional options: MKViewModeOptions
  
  additional optional parameters for view modes.
Returns void

setVolume

setVolume(volume, issuer?): void
Sets the player’s volume in the range of 0 (silent) to 100 (max volume). Unmutes a muted player.
Parameters
- volume: number
  
  The volume to set between 0 and 100.
- Optional issuer: string
  
  The issuer of the API call that will be passed to events triggered by this call.
Returns void

showAirplayTargetPicker

showAirplayTargetPicker(): void
Shows the airplay playback target picker.

Returns void

unload

unload(): Promise<void>
Unloads the current video source.

Returns Promise<void>

unmute

unmute(issuer?): void
Unmutes the player if muted.
Parameters
- Optional issuer: string
  
  The issuer of the API call that will be passed to events triggered by this call.
Returns void

Interface MKPlayerAPI

Hierarchy

Index

Methods

Methods

addCastMetadata

Parameters

metadata: any

Returns boolean

addSubtitle

Parameters

subtitleTrack: MKSubtitleTrack

Returns void

castStop

Returns void

castVideo

Returns void

destroy

Returns Promise<void>

disableSubtitle

Parameters

subtitleID: string

Returns void

enableSubtitle

Parameters

subtitleID: string

Returns void

getAspectRatio

Returns number

getAudio

Returns null | MKAudioTrack

getAudioQuality

Returns null | MKAudioQuality

getAvailableAudio

Returns MKAudioTrack[]

getAvailableAudioQualities

Returns MKAudioQuality[]

getAvailableSubtitles

Returns MKSubtitleTrack[]

getAvailableVideoQualities

Returns MKVideoQuality[]

getBufferLevel

Parameters

type: MKBufferType

media: MKMediaType

Returns null | MKBufferLevel

getBufferedRanges

Returns MKTimeRange[]

getCatchupConfig

Returns null | MKLowLatencySyncConfig

getCurrentTime

Parameters

Optional mode: MKTimeMode

Returns number

getDownloadedAudioData

Returns null | MKDownloadedAudioData

getDownloadedVideoData

Returns null | MKDownloadedVideoData

getDroppedVideoFrames

Returns number

getDuration

Returns number

getFallbackConfig

Returns null | MKLowLatencySyncConfig

getLatency

Returns number

getMaxTimeShift

Returns number

getPlaybackAudioData

Returns null | MKAudioQuality

getPlaybackSpeed

Returns number

getPlaybackVideoData

Returns null | MKVideoQuality

getSeekableRange

Parameters

Optional mode: MKTimeMode

Returns null | MKTimeRange

getTargetLatency

Returns number

`Optional` mode: MKTimeMode

`Optional` mode: MKTimeMode

`Optional` disableSeeking: boolean

`Optional` issuer: string

`Optional` issuer: string

`Optional` issuer: string