API Reference
Bitmovin PlatformPlaybackEncodingBitmovin Dashboard

Source Configuration

Configure media sources, DRM, and progressive streams

SourceConfig

Interface

The source object is passed into load to load a new source.

Multiple stream formats can be provided simultaneously (e.g. dash and hls). The player
automatically selects the best format based on platform capabilities.

Stream format selection priority:

  • MSE-capable browsers and smart devices (e.g. Chrome, Firefox, LG WebOS, Samsung Tizen): html5.dash → html5.hls → html5.smooth
  • Safari: native.hls → html5.dash → html5.hls → html5.smooth

To override automatic selection, use preferredTech:

player.setup({
  playback: {
    // Force HLS even on MSE-capable browsers
    preferredTech: [{ player: 'html5', streaming: 'hls' }]
  }
});

Example

player.load({
  dash: 'http://path/to/mpd/file.mpd',
  hls: 'http://path/to/hls/playlist/file.m3u8',
  progressive: [{
    url: 'http://path/to/mp4',
    type: 'video/mp4',
    bitrate: 500000,
    label: 'Low'
  }, {
    url: 'http://path/to/another-mp4',
    type: 'video/mp4',
    bitrate: 1000000,
    label: 'Mid'
    preferred: true
  }, {
    url: 'http://path/to/another-mp4',
    type: 'video/mp4',
    bitrate: 2500000,
    label: 'High'
  }],
  poster: 'images/poster.jpg',
  subtitleTracks: [{
    url: 'http://path/to/subtitles/vtt/file.vtt',
    id: 'track-0',
    lang: 'en'
  }],
  thumbnailTrack: {
    url: 'http://path/to/thumbnail/vtt/file.vtt',
  },
  drm: {
    widevine: {
      LA_URL: 'https://mywidevine.licenseserver.com/'
    },
    playready: {
      LA_URL: 'https://myplayready.licenseserver.com/'
    }
  },
  labeling: {
    hls: {
      qualities: (quality) => {
        return quality.height + 'p';
      }
    },
    dash: {
      qualities: (quality) => {
        return quality.height + 'p';
      }
    }
  }
});

Properties

analytics?

optional analytics?: AnalyticsConfig

Bitmovin Analytics Configuration used to specify per-stream metadata and other settings.

dash?

optional dash?: string

The URL to the MPEG-DASH manifest file (MPD, Media Presentation Description) for the video to play.
The file has to be a valid MPD.

description?

optional description?: string

The description of the video source.

drm?

optional drm?: DRMConfig

The DRM object should be included into the source object.

hls?

optional hls?: string

An URL to an HLS playlist file (M3U8). The file has to be a valid M3U8 playlist.

labeling?

optional labeling?: SourceLabelingStreamTypeConfig

Labeling config for the different stream types.

live?

optional live?: LiveConfigAtSourceLevel

`LiveConfig` at source level.

Note: Only certain parts of the `LiveConfig` are supported here at this time.

Any values defined here at source level will override values of a config at the player level if present.

Since: 8.176.0

metadata?

optional metadata?: object

Optional custom metadata. Also sent to a cast receiver on the load call.

Index Signature

[key: string]: string

options?

optional options?: SourceConfigOptions

An object specifying advanced source specific options.

poster?

optional poster?: string

The URL to a preview image displayed until the video starts. Make sure JavaScript is allowed
to access it, i.e. CORS (for the HTML5/JavaScript player) must be enabled and a crossdomain.xml has to
be there if it’s not the same server as the website.

progressive?

optional progressive?: string | ProgressiveSourceConfig[]

An Array of objects to video files, used for progressive download as fallback. Is only used when all
other methods fail. Multiple progressive files can be used, e.g. .mp4 and .webm files to support as
many browsers as possible.

smooth?

optional smooth?: string

An URL to a SmoothStreaming manifest file (xml or ismc). The file has to be a valid smooth streaming manifest
file.

subtitleTracks?

optional subtitleTracks?: SubtitleTrack[]

An array of external subtitle tracks.

thumbnailTrack?

optional thumbnailTrack?: ThumbnailTrack

A thumbnail track.
Note: An externally set thumbnail track has precedence over thumbnail tracks found in the stream itself.

title?

optional title?: string

The title of the video source.

vr?

optional vr?: VRConfig

Configuration for VR and omnidirectional (360°) video.

whep?

optional whep?: string

An URL pointing to a WHEP endpoint.

SourceLabelingConfig

Interface

An object with callback functions to provide labels for audio tracks, qualities and subtitle tracks.

Properties

qualities?

optional qualities?: (quality) => string

A function that generates a label for a quality, usually a video quality.

Parameters

quality

QualityMetadata

Object with metadata about the quality for which the label should be generated.

Returns

string

subtitles?

optional subtitles?: (subtitle) => string

A function that generates a label for a subtitle.

Parameters

subtitle

SubtitleTrack

The subtitle for which the label should be generated.

Returns

string

tracks?

optional tracks?: (track) => string

A function that generates a label for a track, usually an audio track.

Parameters

track

TrackMetadata

Object with metadata about the track for which the label should be generated. The id field is
populated when used for HLS, the mimeType when used for DASH.

Returns

string

ProgressiveSourceConfig

Interface

Properties

bitrate?

optional bitrate?: number

Can be used to specify which bitrate the a progressive source has. Providing multiple progressive
sources with different bitrates allows the users to manually select qualities.
Please note that no automatic quality switching will happen.

label?

optional label?: string

Specifies the label to be displayed in the quality selection in the player’s settings window.

preferred?

optional preferred?: boolean

Sets the source/quality which the player will use per default. Should be set to true at only one object
within the progressive array. If no element has set this attribute to true, the first object in the array
will be used per default.

type?

optional type?: string

The MIME type of the video file, e.g. “video/mp4” or “video/webm”.

url

url: string

The URL to the progressive video file.

ThumbnailTrack

Interface

Properties

url

url: string

The URL to the associated file.

SourceConfigOptions

Interface

Properties

audioCodecPriority?

optional 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
audioCodecPriority

Since: 7.6

dashManifestWithCredentials?

optional dashManifestWithCredentials?: boolean

Send credentials and cookies along with cross origin MPEG-DASH manifest requests.
Must be supported by the server. Default is false.

dashWithCredentials?

optional dashWithCredentials?: boolean

Send credentials and cookies along with cross origin MPEG-DASH segment requests.
Must be supported by the server. Default is false.

headers?

optional headers?: HttpHeaders

hlsManifestWithCredentials?

optional hlsManifestWithCredentials?: boolean

Send credentials and cookies along with cross origin HLS manifest requests.
Must be supported by the server. Default is false.

hlsWithCredentials?

optional hlsWithCredentials?: boolean

Send credentials and cookies along with cross origin HLS segment requests.
Must be supported by the server. Default is false.

manifestWithCredentials?

optional 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.

persistentPoster?

optional persistentPoster?: boolean

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

shouldRecreateSourceBuffersOnPeriodSwitch?

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

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

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 Bitmovin player is taking a fairly offensive approach on SourceBuffer recreation, meaning it will recreate
the SourceBuffers and the MediaSource when there is any risk that the content might get stuck.

Parameters

sourcePeriodInfo

PeriodInformation

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

targetPeriodInfo

PeriodInformation

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 and MediaSource recreation, false for re-using.

Since: 8.87.0

startOffset?

optional startOffset?: number

The position where the stream should be started. Number can be positive or negative depending on the used
TimelineReferencePoint. Invalid numbers will be corrected according to the stream boundaries. For VOD this
is applied at the time the stream is loaded, for LIVE when the playback starts.

Example:

// Start a VOD stream at 10.5 seconds
{
 startOffset: 10.5,
 startOffsetTimelineReference: TimelineReferencePoint.Start // also the default value
}

// Start a LIVE stream 20 seconds behind the live edge
{
  startOffset: -20,
  startOffsetTimelineReference: TimelineReferencePoint.End // also the default value
}

Since: 8.9.0

startOffsetTimelineReference?

optional startOffsetTimelineReference?: TimelineReferencePoint

Timeline reference point to calculate startOffset from.
Default for live: TimelineReferencePoint.End
Default for VOD: TimelineReferencePoint.Start

startTime?

optional startTime?: number

The position in fractional seconds to start playback from.

Since: 7.1

Deprecated: use StartOffset instead

videoCodecPriority?

optional 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
videoCodecPriority

Since: 7.6

withCredentials?

optional 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.

SourceLabelingStreamTypeConfig

Interface

Labeling config for the different stream types.

Properties

dash?

optional dash?: SourceLabelingConfig

Labeling functions for DASH sources.

hls?

optional hls?: SourceLabelingConfig

Labeling functions for HLS sources.

LiveConfigAtSourceLevel

Interface

Partial `LiveConfig` for usage at the source level.

Extends

  • Pick<LiveConfig, "lowLatency" | "synchronization">

Properties

lowLatency?

optional lowLatency?: LowLatencyConfig

Configuration to enable maintaining a desired live latency.

Inherited from

LiveConfig.lowLatency

synchronization?

optional synchronization?: SynchronizationConfigEntry[]

Configuration to enable the synchronization of the client-clock with an external time source.

Inherited from

LiveConfig.synchronization

StreamType

Enum

  • progressive... Progressive MP4 or WebM streams.
  • dash... MPEG-DASH streams.
  • hls... Apple HLS streams.
  • smooth... Microsoft Smooth Streaming streams.
  • whep... WebRTC based WHEP stream.
  • unknown... No stream specified.

Enumeration Members

Dash

Dash: "dash"

Hls

Hls: "hls"

Progressive

Progressive: "progressive"

Smooth

Smooth: "smooth"

Unknown

Unknown: "unknown"

Whep

Whep: "whep"

Updated 11 days ago

Did this page help you?

Updated 11 days ago

Did this page help you?