ReadonlyadaptationMKPlayer Adaptation APIs.
ReadonlybufferMKPlayer Buffer APIs.
ReadonlydrmMKPlayer DRM APIs.
ReadonlylowlatencyMKPlayer Low Latency APIs.
ReadonlymanifestMKPlayer Manifest APIs.
ReadonlysubtitlesMKPlayer Subtitles APIs.
Sends custom metadata to a remote receiver app (e.g. Chromecast).
the custom metadata to send to the receiver.
true if it was successful.
Adds a marker to the timeline.
Note: Does not check for duplicates/overlaps at the specified time.
Note: This API is only available when MKPlayerConfig.ui is enabled.
Note: It is also recommended to call this API after playback starts as the positioning of the timeline marker depends on knowing the current seekable range. The best place to call this the first time is as soon as the first time changed event is received from MKPlayerEvent.TimeChanged.
Example to place timeline marker during ongoing playback:
var timelineMarkers = [
{ time: 24, title: 'Salto on the edge' },
{ time: 69, title: 'Interview - Marcus Gustafsson' },
{ time: 105, title: 'Parcour rating explained' },
{ time: 188, duration: 11, title: 'And we have a winner!', cssClasses: ['seekbar-marker-interval'] },
];
// Call this anytime during any ongoing playback
// to add all available timeline markers to the UI.
timelineMarkers.map((marker) => {
player.addTimelineMarker(marker);
});
Example to place timelineMarker for an AdBreak based off MKPlayerEvent.AdMarker:
// list of AdBreaks
const adBreaks = [];
// collect AdMarkers and build the list of adBreaks
player.on(MKPlayerEvent.AdMarker, (event) => {
adBreaks.push(event.adMarker);
// timeline markers cannot be added from here during ongoing playback
// because this callback is always reported when metadata is parsed
// which means the time for this ad is in the future and outside the
// current seekable range. So for upcoming adBreaks new markers can
// only be added when the time falls within the current seekable range
// or when the next MKPlayerEvent.AdBreakStarted event is triggered.
});
// global variable
let firstTimeChangedEvent = false;
// Wait for the playback to start and the
// first time changed event is received to add timeline markers
player.on(MKPlayerEvent.TimeChanged, (event) => {
if (!firstTimeChangedEvent) {
firstTimeChangedEvent = true;
// add timeline markers
adBreaks.map((marker, index) => {
player.addTimelineMarker({time: marker.start});
});
}
});
the timeline marker to be added.
Initiates casting the current video to a Cast-compatible device.
The user has to choose the target device.
Unloads the player and removes all inserted HTML elements and event handlers.
Promise resolves when the player has cleaned up all its event handlers & resources.
Discards all scheduled ad breaks with the given ID. Also stops the current ad break if it has the same ID. Only applicable in case of Client-Side Ad Insertion (CSAI) and available when MKPlayerConfig.advertising is provided in the PlayerConfig.
The ID of the ad break which shall be removed from the scheduled ad breaks.
Dismisses currently active pauseAd overlay, if any.
Note:
Returns the currently active ad, or null if no ad is active. Only applicable in case of Client-Side Ad Insertion (CSAI) and available when MKPlayerConfig.advertising is provided in the PlayerConfig.
the active Ad, or null if none is active
Returns the currently active ad break, or null if no ad break is active. Only applicable in case of Client-Side Ad Insertion (CSAI) and available when MKPlayerConfig.advertising is provided in the PlayerConfig.
the active AdBreak, or null if none is active
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.
A number indicating the player aspect ratio (e.g. 1.6 for 16:10) or 0 in case of error.
Returns the currently used audio track, or null if no track is active.
Returns the currently selected audio quality.
One of the elements of getAvailableAudioQualities.
Returns an array of all available audio tracks.
Returns an array of all available audio qualities the player can adapt between.
Returns info for segments that can be requested by the player.
Returns an array containing all available video qualities the player can adapt between.
Returns the currently buffered time ranges of the video element.
Returns the config object of the current player instance.
OptionalmergedConfig: booleantrue to return the config expanded with all default values, false to return the user config passed to the player's constructor.
The current user or merged player config.
Returns the current playback time in seconds of the video.
If MKPlayerConfig.excludePrerollFromVodDuration is set to true in the player config then,
for VOD content, the duration of any preroll ads will be excluded from the returned current time while playing actual VOD content.
Optionalmode: MKTimeModeThe mode to decide if the returned time should be absolute or relative, see MKTimeMode. Default mode is absolute.
For Live and Events the default mode is MKTimeMode.AbsoluteTime. For VOD, Catchup and DVR its MKTimeMode.RelativeTime.
Returns data about the last downloaded audio segment.
Returns data about the last downloaded video segment.
Returns the total number of dropped video frames since playback started.
Returns the total duration in seconds of the current video.
If MKPlayerConfig.excludePrerollFromVodDuration is set to true in the player config, the duration of any preroll ads for VOD content will be excluded from the returned duration.
For live streams, it returns length of timeShift window.
Returns the current latency in seconds for the live stream.
the current latency in seconds.
Returns the limit in seconds for time shift.
Is either negative or 0 and applicable to live streams only.
Returns the name and version of the currently used advertising module. Only applicable in case of Client-Side Ad Insertion (CSAI) and available when MKPlayerConfig.advertising is provided in the PlayerConfig.
Returns data about the currently playing audio segment.
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 data about the currently playing video segment.
Returns the currently used rendering mode.
See MKPlayerType for details on valid values.
MKPlayerType.Unknown is returned when player type cannot be determined or when the player is not yet ready.
Returns the time range that is currently valid for seeking.
Note For VOD default mode is MKTimeMode.RelativeTime and for Live it is MKTimeMode.AbsoluteTime.
Optionalmode: MKTimeModeThe mode to decide if the returned time should be absolute or relative, see MKTimeMode.
the current seekable range.
Returns the source that was loaded via a successfully finished load call. Returns null if no source is loaded or a load is in progress.
the loaded source or null if no source is loaded
Gets the current playback SourceConfig value passed to load
current SourceConfig values or null otherwise
Returns the currently used streaming technology. See MKStreamType for details of the valid values.
Returns a thumbnail image for a certain time or null if there is no thumbnail available.
Requires a configured thumbnails track in MKSourceConfig.thumbnailTrack if sideloaded thumbnails are configured.
Requires MKPlayerConfig.enableHlsImageMediaPlaylistSupport to be true if thumbnail images from the HLS manifest are needed.
When MKSourceConfig.thumbnailTrack are configured, this will have preference over the thumbnails found in the HLS manifest.
the current relative playback time for which the thumbnail should be returned.
A thumbnail if a thumbnails track is configured and a thumbnail exists for the specified time, else null.
Returns the list of all added markers in undefined order.
Note: This API is only available when MKPlayerConfig.ui is enabled.
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 the stalled time in seconds since playback started.
Returns current MKPlayer SDK version.
Returns the html element that the player is embedded in, which has been provided in the player constructor.
Returns the used HTML5 video element.
Returns the currently selected video quality, if the user manually selected one.
In this case it returns one of the elements of getAvailableVideoQualities.
Gets the active MKViewMode.
Returns the player’s volume between 0 (silent) and 100 (max volume).
Returns true if the video has ended.
Checks if Apple Airplay is enabled.
Checks if Apple AirPlay support is available.
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 MKPlayerEvent.CastAvailable event has fired.
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 true if a linear ad is currently active (playing or paused). Returns false otherwise. Only applicable in case of Client-Side Ad Insertion (CSAI) and available when MKPlayerConfig.advertising is provided in the PlayerConfig.
Return true if the displayed video is a live stream.
Indicates whether the live playback is in low latency mode.
Low latency for live playback can be configured using MKLiveConfigAtSourceLevel.lowLatency. For registered sources, it is decided by Mediakind AV Backend.
true if the live playback is in low latency mode, false otherwise.
Returns true if the player has been muted.
Returns true if a pauseAd overlay is currently active; otherwise, returns false. Returns false when pauseAd feature is disabled.
Returns true if the player has started playback but is currently paused.
Returns true if the player is currently playing, i.e. has started and is not paused.
Returns true if the player is currently stalling due to an empty buffer.
Tests if a particular ViewMode is available for selection with setViewMode.
the view mode to test.
true if the tested view mode is available, else false.
Returns all scheduled ad breaks. Does not include currently active ad breaks. Only applicable in case of Client-Side Ad Insertion (CSAI) and available when MKPlayerConfig.advertising is provided in the PlayerConfig.
Array containing all the scheduled ad breaks.
Sets a new video source and returns a promise which resolves when the source has loaded successfully.
Note: Promise doesn't reject. If source fails to load (ex: invalid sourceConfig or Mediakind AV Backend request fails), MKPlayerEvent.Error event is fired and promise is resolved.
the source the player should load.
OptionaldisableSeeking: booleanIf set, seeking will be disabled.
Promise which resolves when the source is loaded and resolves when load fails as well.
Mutes the player if an audio track is available. Has no effect if the player is already muted.
Optionalissuer: stringThe issuer of the API call that will be passed to events triggered by this call.
Removes a handler for a player event.
The event to remove the handler from.
The callback handler to remove.
Removes all event handlers registered for the given event type.
The event for which all event handlers are to be removed.
Subscribes an event handler to a player event.
The type of event to subscribe to.
The event callback handler that will be called when the event fires.
Pauses the video if it is playing. Has no effect if the player is already paused.
Optionalissuer: stringThe issuer of the API call that will be passed to events triggered by this call.
Starts playback or resumes after being paused.
No need to call it if the player is setup with autoplay.
Calling play has no effect when player is already playing.
Optionalissuer: stringthe issuer of the API call that will be passed to events triggered by this call.
a promise which resolves as soon as playback starts. The promise can reject if the play is blocked by the browser.
Starts preloading the content of the currently loaded source.
Reloads the current source.
For live sources, the manifest is reloaded with startTime as the new program start.
If startOffset is provided, playback begins at that position. If not provided, startOffset previously specified in MKSourceOptions.startOffset will be used. Otherwise, playback starts as per player's default behaviour.
Listen for MKPlayerEvent.SourceLoaded to be notified when the reload completes.
OptionalstartTime: stringProgram start time in UTC format yyyy-MM-dd'T'HH:mm:ss'Z' (applicable only for live sources).
OptionalstartOffset: numberFor live sources, absolute UNIX timestamp (seconds) of the desired playback start position, which must be between program start time and the live edge. Defaults to 0 (starts at live edge). For VoD, relative playback offset (seconds) from beginning of content. Defaults to 0 (starts from beginning).
a promise which resolves as soon as source is reloaded. The promise can reject if no source is loaded or if startTime is passed for non-live source or is not valid date-time.
Removes a marker from the timeline (by reference) and returns true if the marker has
been part of the timeline and successfully removed, or false if the marker could not
be found and thus not removed.
Note: This API is only available when MKPlayerConfig.ui is enabled.
the timeline marker to be removed.
true if marker was found and removed or false otherwise.
Schedules resulting ad break(s) of an ad config for playback. Only applicable in case of Client-Side Ad Insertion (CSAI) and available when MKPlayerConfig.advertising is provided in the PlayerConfig.
The ad configuration used to schedule one or more ad breaks.
Promise that resolves with the ad breaks that were scheduled as a result of the given ad config.
Seeks to the given playback time specified by the parameter time in seconds.
The time offset specified must always be a positive value and within the current MKPlayerAPI.getSeekableRange.
For VoD, if MKPlayerConfig.excludePrerollFromVodDuration is enabled, then duration of any preroll ads is added for seeks once preroll ad has completed playing.
For Live and Events the specified time either be relative or absolute offset.
seek(0) will take you to the start of the live windowseek(getSeekableRange().end) will take you near the current live edge. You can also call MKPlayerAPI.seekToLiveEdge to jump to current live edge easily.The time to seek to in seconds.
Optionalissuer: stringThe issuer of the API call that will be passed to events triggered by this call.
true when successful. For Live and Events this is always true.
Seeks to the current live edge.
Applicable only for live sources.
Optionalissuer: stringThe issuer of the API call that will be passed to events triggered by this call.
Set the customData that needs to be sent to the Bitmovin dashboard during runtime.
Note: This API is not available when analytics is disabled.
The customData parameter should be of type MKAnalyticsConfig
Modifies the current aspect ratio of the player.
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).
Sets the audio track to the ID specified by trackID.
Available tracks can be retrieved with getAvailableAudio.
The ID of the audio track to activate.
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.
The ID of the desired audio quality or 'auto' for dynamic switching.
Sets the base64-encoded CloudId configuration to be included as cloudIdInfo in the roll request payload.
the base64-encoded CloudId configuration or null to remove.
Registers a callback for attaching a GeoComply-style signed location JWT to the Azuki roll request.
Note: this is applicable only for registered source streams. The callback is called
synchronously, on demand, immediately before each roll request is built. If it
returns undefined, the roll simply goes out without a location header.
A registered (non-null) provider is itself the enable signal; there is no separate flag to enable/disable this feature.
function returning the current location JWT, or undefined if none
is available yet; pass null to unregister.
Set HTTP headers.
Use this to pass your HTTP headers for all player/playback manifest requests.
Note: It is recommended to call this method before calling load.
HTTP headers to be used with requests (merged with previously set headers) and when null is passed the set headers will be cleared.
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 so that this value is sent to Mediakind AV Backend.
the new inhome status value.
Set/Remove 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.
Also if needed to remove the old location detail, pass null or empty string.
the new location details as base64 encoded string or null / '' to remove old one.
Sets the level of player log outputs.
Log level, allowed values are "debug", "log", "warn", "error" and "off"
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.
A playback speed factor greater than 0.
Sets a poster image. Will be displayed immediately, even if a video stream is playing.
The URL to the poster image.
Flag to set the poster image persistent so it is also displayed during playback (useful for audio-only playback).
Set the subtitle styling dynamically during runtime.
Note:
Supported subtitle style options:
fontSize
fontStyle
fontFamily
fontColor
fontOpacity
backgroundColor
Example:
styleOptions = {
fontSize: "50",
fontStyle: "normal",
fontFamily: "normal",
fontColor: "white",
fontOpacity: "75",
backgroundColor: "black",
};
the styleOptions parameters for subtitle styling
Used to set the userEngagement data.
Note: this is applicable only for registered source streams so this value is sent to Mediakind AV Backend.
OptionaluserEngagementData: null | MKUserEngagementMKUserEngagement to report to backend or null to remove previously set data
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(videoContainer, playerConfig);
player.setVideoElement(videoElement);
player.load(sourceConfig);
the video element to set.
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.
ID defined in the Manifest/MPD or 'auto'.
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 MKPlayerEvent.ViewModeChanged will be fired.
the view mode to switch the player into.
Optionaloptions: MKViewModeOptionsadditional optional parameters for view modes.
Sets the player’s volume in the range of 0 (silent) to 100 (max volume). Unmutes a muted player.
The volume to set between 0 and 100.
Optionalissuer: stringThe issuer of the API call that will be passed to events triggered by this call.
Shows the airplay playback target picker.
Skips the current ad. Has no effect if no ad is active or if ad's end is out of seekableRange MKPlayerAPI.getSeekableRange.
OptionalisCSAI: booleanwhether the current ad is a client side ad. Skipping the current client-side (CSAI) ad is only applicable when MKPlayerConfig.advertising is provided in the PlayerConfig. Has no effect if the ad is not skippable, if no ad is active or if the IMA module is used (disabled by IMA in version 3.607.0). Defaults to false (server side ad).
Promise that resolves when the ad skip is triggered.
Skips the current server-side (SSAI) adBreak. Has no effect if no adBreak is active or if adBreak's end is out of seekableRange MKPlayerAPI.getSeekableRange.
Unloads the current video source.
Unmutes the player if muted.
Optionalissuer: stringThe issuer of the API call that will be passed to events triggered by this call.
Update STS authToken during an ongoing playback session.
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 MKRegisteredSource.environmentConfig in the MKSourceConfig object passed to start playback of a next source.
the new authorization token.
MKPlayer API.
Defines the API's supported by MKPlayer.