Interface MKSourceOptions

Source options.

interface MKSourceOptions {
    audioCodecPriority?: string[];
    dashManifestWithCredentials?: boolean;
    dashWithCredentials?: boolean;
    headers?: MKHeaders;
    hlsManifestWithCredentials?: boolean;
    hlsWithCredentials?: boolean;
    manifestWithCredentials?: boolean;
    persistentPoster?: boolean;
    programLoadTime?: string;
    shouldRecreateSourceBuffersOnPeriodSwitch?: (
        sourcePeriodInfo: MKPeriodInformation,
        targetPeriodInfo: MKPeriodInformation,
        suggestion: boolean,
    ) => boolean;
    startOffset?: number;
    startOffsetTimelineReference?: MKStartOffsetTimelineReference;
    videoCodecPriority?: string[];
    withCredentials?: boolean;
}

Properties

audioCodecPriority? dashManifestWithCredentials? dashWithCredentials? headers? hlsManifestWithCredentials? hlsWithCredentials? manifestWithCredentials? persistentPoster? programLoadTime? shouldRecreateSourceBuffersOnPeriodSwitch? startOffset? startOffsetTimelineReference? videoCodecPriority? withCredentials?

Properties

OptionalaudioCodecPriority

audioCodecPriority?: string[]

Specify the priority of audio codecs for this source.

If more than one audio codec is available this order will be respected while finding a codec which is supported by the current browser.

Default is MKPlaybackConfig.audioCodecPriority

OptionaldashManifestWithCredentials

dashManifestWithCredentials?: boolean

Send credentials and cookies along with cross origin MPEG-DASH manifest requests.

Must be supported by the server.

Default is false.

OptionaldashWithCredentials

dashWithCredentials?: boolean

Send credentials and cookies along with cross origin MPEG-DASH segment requests.

Must be supported by the server.

Default is false.

Optionalheaders

headers?: MKHeaders

Additional HTTP Headers you want to set for this source.

OptionalhlsManifestWithCredentials

hlsManifestWithCredentials?: boolean

Send credentials and cookies along with cross origin HLS manifest requests.

Must be supported by the server.

Default is false.

OptionalhlsWithCredentials

hlsWithCredentials?: boolean

Send credentials and cookies along with cross origin HLS segment requests.

Must be supported by the server.

Default is false.

OptionalmanifestWithCredentials

manifestWithCredentials?: boolean

Send credentials and cookies along with cross origin manifest (HLS and MPEG-DASH) requests.

Must be supported by the server.

Default is false.

OptionalpersistentPoster

persistentPoster?: boolean

If set to true, this will keep the poster image visible during playback, e.g. for audio-only streams.

OptionalprogramLoadTime

programLoadTime?: string

Set programLoadTime in UTC format yyyy-MM-dd'T'HH:mm:ss.SSS'Z' to start a live program from beginning or any position outside live seekable range.

  • Note: Setting programLoadTime will start live playback with program based manifest. User will be able to seek from programLoadTime to live edge. No need to set startOffset and startOffsetTimelineReference in this case.

OptionalshouldRecreateSourceBuffersOnPeriodSwitch

shouldRecreateSourceBuffersOnPeriodSwitch?: (
    sourcePeriodInfo: MKPeriodInformation,
    targetPeriodInfo: MKPeriodInformation,
    suggestion: boolean,
) => boolean

With this callback it's possible to override the player's default behavior regarding the recreation of SourceBuffers when switching periods.

The downside of SourceBuffer recreation is a prolonged transition time with possible black frames between the periods.

The upside is increased stability: not recreating SourceBuffers may result in PLAYBACK_VIDEO_DECODING_ERROR, or a stuck video element on many platforms. This also depends on the playing content itself.

The player is taking a fairly offensive approach on SourceBuffer recreation, meaning it will recreate the SourceBuffers when there is any risk that the content might get stuck.

Type declaration

    • (
          sourcePeriodInfo: MKPeriodInformation,
          targetPeriodInfo: MKPeriodInformation,
          suggestion: boolean,
      ): boolean

    • Parameters

      • sourcePeriodInfo: MKPeriodInformation

        The information of the period the player is switching away from.

      • targetPeriodInfo: MKPeriodInformation

        The information of the period the player is switching into.

      • suggestion: boolean

        The default behavior suggested by the player, true for recreation, false for reusing.

      Returns boolean

      true for SourceBuffer recreation, false for re-using.

OptionalstartOffset

startOffset?: number

The position where the stream should be started.

Number can be positive or negative depending on the used MKStartOffsetTimelineReference.

Invalid numbers will be corrected according to the stream boundaries.

For VOD this is applied at the time when stream is loaded, for LIVE when the playback starts.

Note:

  • Ensure that correct MKAssetType is set for these options to work correctly.
  • 24x7 Live stream starts at the current live edge by default.
  • Live events start at the beginning (not at the live edge) by default.
  • For VOD the startOffset value should be between 0 and duration of the VOD asset.
  • For Live and Live events the startOffset value (if negative relative offset value less than 0) should be within MKPlayerAPI.getMaxTimeShift.
  • For Live and Live events the startOffset value (if positive absolute offset value greater than 0) should be within MKPlayerAPI.getSeekableRange with MKTimeMode.AbsoluteTime. Typically this option is best used for resuming playback from bookmark offset.

Example:

// Start a VOD stream at 10.5 seconds
{
    startOffset: 10.5, // positive between 0 and duration of VOD asset
    startOffsetTimelineReference: MKStartOffsetTimelineReference.Start // default for VOD and can be ignored
}

// Start a LIVE stream 20 seconds behind the live edge (live edge is always offset `0`)
{
    startOffset: -20, // negative between `0` and `getMaxTimeShift`
    startOffsetTimelineReference: MKStartOffsetTimelineReference.End  // default for LIVE and can be ignored
}

// Start LIVE or EVENT stream at a bookmark offset.
{
    startOffset: 1685868560, // must always specify an absolute timestamp within seekable range
    // timelineReference must be ignored for this use case.
}

// Stat a LIVE EVENT stream at the live edge
{
    startOffset: 0,
    startOffsetTimelineReference: MKStartOffsetTimelineReference.End  // must specify for this use case
}

OptionalstartOffsetTimelineReference

startOffsetTimelineReference?: MKStartOffsetTimelineReference

Timeline reference point to calculate MKSourceOptions.startOffset from.

Default for live: MKStartOffsetTimelineReference.End Default for VOD: MKStartOffsetTimelineReference.Start

OptionalvideoCodecPriority

videoCodecPriority?: string[]

Specify the priority of video codecs for this source.

If more than one video codec is available this order will be respected while finding a codec which is supported by the current browser.

Default is MKPlaybackConfig.videoCodecPriority

OptionalwithCredentials

withCredentials?: boolean

Send credentials and cookies along with cross origin (HLS and MPEG-DASH) segment requests.

Must be supported by the server.

Default is false.

Settings

Member Visibility

On This Page

Properties