Player Configuration

PlayerConfig

Interface

The entry point to the player configuration is the PlayerConfig interface, which is passed into the
constructor of the player. There are several ways to do this:

1. When the full player is loaded from the CDN via <source> tag:

const player = new bitmovin.player.Player(container, config);

2. Whe the player is loaded from the CDN via https://requirejs.org/|RequireJS:

requirejs(['<cdn_url>'], (bitmovinplayer) => {
  const player = new bitmovinplayer.Player(container, config);
});

3. When the player is imported from NPM:

import { Player } from 'bitmovin-player';
const player = new Player(container, config);

Example configuration:

{
  key: 'INSERTPROVIDEDKEYHERE',
  playback: {
    autoplay: false,
    muted: false
  },
  style: {
    width: '90%',
    aspectratio: '16/9',
  },
  events: {
    [PlayerEvent.SourceLoaded]: myFunc,
    [PlayerEvent.Play]: () => {
      // do some awesome stuff
    },
    [PlayerEvent.Error]: myErrorHandlingFunc
  },
  tweaks: {
    startup_threshold?: 5;
  },
  advertising: {
    adBreaks: [{
      tag: {
        url: 'http://your.ad.provider/manifest.xml',
        type: 'vast',
      },
    }],
  }
}

Example source:

player.load({
  dash: 'https://path/to/mpd/file.mpd',
  hls: 'https://path/to/hls/playlist/file.m3u8',
  smooth: 'https://path/to/manifest/file/Manifest',
  progressive: [{
    url: 'http://path/to/mp4',
    type: 'video/mp4'
  }, {
    url: 'http://path/to/webm',
    type: 'video/webm'
  }],
  poster: 'images/poster.jpg',
  drm: {
    widevine: {
      LA_URL: 'https://mywidevine.licenseserver.com/'
    },
    playready: {
      LA_URL: 'https://myplayready.licenseserver.com/'
    },
    access: {
      LA_URL: 'https://myaccess.licenseserver.com/',
      authToken: 'INSERT-YOUR-BASE64-ENCODED-AUTH-TOKEN'
    },
    primetime: {
      LA_URL: 'https://myprimetime.licenseserver.com/'
    },
    fairplay: {
      LA_URL: 'https://fairplay.licenseserver.com/',
      certificateURL: 'https://fairplay.licenseserver.com/certificate-url'
    }
  }
});

Properties

adaptation

• Optional adaptation: AdaptationPlatformConfig

Configures the adaptation logic.

advertising

• Optional advertising: AdvertisingConfig

Allows you to define which ads you want to display and when you want to display them.
In order to play ads on your website, you need to specify an ad config.

analytics

• Optional analytics: false | AnalyticsConfig

Bundled Bitmovin Analytics Configuration used to specify metadata and other related info.
Can also be used to completely disable Analytics by setting this to false
in case the Analytics module is loaded, but Analytics is not desired.

buffer

• Optional buffer: BufferConfig

Configures various buffer settings.

cast

• Optional cast: CastConfig

Google Cast configuration.

Deprecated: Use remotecontrol with GoogleCastRemoteControlConfig instead.

events

• Optional events: EventConfig

A list of callback functions for events. Events can also be dynamically added and removed through
on and off.

Example:

events: {
  [PlayerEvent.SourceLoaded]: data => {
    console.log('version: ' + player.getVersion() + ', SourceLoaded Event data: ', data);
  },
  [PlayerEvent.Play]: data => {
    // do awesome stuff
  },
  [PlayerEvent.Error]: data => {
    console.error('An error occurred:', data);
  }
}

hls

• Optional hls: HlsConfig

HLS specific configuration options.

Since: 8.238.0

key

• key: string

Mandatory. A personal key can be found in the bitmovin portal and should be specified here.
Do not forget to enter all your domains (subdomains are included) in your account.

licensing

• Optional licensing: LicensingConfig

Licensing configuration.

live

• Optional live: LiveConfig

Provide parameters specific to live streams.

For better flexibility it is also possible to define a LiveConfig at source level.

location

• Optional location: LocationConfig

This can be used to specify custom paths to bitmovinplayer-core.min.js,
and bitmovinplayer-core.min.css instead of having all files in the same folder.

logs

• Optional logs: LogsConfig

Can be use to fine tune logging of the player.

network

• Optional network: NetworkConfig

Network configuration.

playback

• Optional playback: PlaybackConfig

Playback config settings.

remotecontrol

• Optional remotecontrol: GoogleCastRemoteControlConfig | WebSocketRemoteControlConfig

Remote control configuration (e.g. Chromecast)

Since: 7.1

storage

• Optional storage: StorageConfig

Allows configuration of the player's access to the Web Storage API.

Since: v8.91.0

style

• Optional style: StyleConfig

UX/UI config settings.

tweaks

• Optional tweaks: TweaksConfig

Tweaks. Use these values only if you know what you are doing.

ui

• Optional ui: any

UI configuration that is passed to the Bitmovin Player UI if the UI module is loaded. Can also be used
to disable the UI in case the UI module is loaded but the UI is not desired.

PlaybackConfig

Interface

Config to determine the initial playback state of the Player.

All options passed in this config, will be considered as the starting state of the player, therefore no events will
be triggered signaling a potential change compared to the player default logic.

Example:

playback : {
  autoplay: false,
  muted: false,
  audioLanguage: ['en', 'es', 'de'],
  subtitleLanguage: 'en',
  preferredTech: [{
    player: 'html5',
    streaming: 'dash'
  }, {
    player: 'native',
    streaming: 'hls'
  }]
}

Properties

audioCodecPriority

• Optional audioCodecPriority: string[]

Specify the priority of audi codecs. If more than one audio codec is available this order will be respected
while
finding a codec which is supported by the current browser.
If there is a codec which is not in this priority list, it will be tried only if none of this list are available
/ supported Default is ['ec-4', 'ac-4', 'ec-3', 'mp4a.a6', 'ac-3', 'mp4a.a5', 'mp4a.40']

Since: 7.6

audioLanguage

• Optional audioLanguage: string | string[]

Defines one or more audio languages which should be used
in the specified order on start up.

autoplay

• Optional autoplay: boolean

Whether the player starts playing after loading a source or not (false, default).
Note that unmuted autoplay is blocked on several browsers, check for Warning with code
PLAYBACK_COULD_NOT_BE_STARTED for detecting the blocking.

isForcedSubtitle

• Optional isForcedSubtitle: (subtitle: SubtitleTrack) => boolean

Determines if the subtitle should be selected by the player per default and
kept in sync with the selected audio language.
The subtitle will not appear in list and can't be deactivated or activated through
the API.

Per default subtitle tracks with forced=true will be selected.
In case of DASH these are subtitles with the role forced_subtitle or forced-subtitle and in case of HLS
subtitles with the attribute FORCED=YES.

Type declaration

▸ (subtitle): boolean

Parameters

Returns

boolean

muted

• Optional muted: boolean

Whether the sound is muted on startup or not (false, default).

playsInline

• Optional playsInline: boolean

Whether to add the playsinline attribute to the video element or not. This stops videos immediately
going fullscreen after starting playback on iOS for example. Default is true.

preferredTech

• Optional preferredTech: PreferredTechnology[]

An array of objects to specify the player and streaming technology order to use. If the first is
supported, this technologies are used. If not, the second is tried etc. If none of the specified combinations
are supported, then a SOURCE_NO_SUPPORTED_TECHNOLOGY will be thrown.

Player technologies:

• html5 refers to the MediaSource Extension (MSE) based JavaScript player
• native refers to the browser’s native capabilities are being used, e.g. playing back HLS in Safari on iOS

Currently supported combinations:

{ player: 'html5', streaming: 'dash'}
{ player: 'html5', streaming: 'hls'}
{ player: 'html5', streaming: 'smooth'}
{ player: 'native', streaming: 'hls'}
{ player: 'native', streaming: 'progressive'}

Example:

preferredTech : [{
  player: 'html5',
  streaming: 'dash'
}, {
  player: 'native',
  streaming: 'hls'
}]

seeking

• Optional seeking: boolean

Whether to allow seeking or not. Default is true.

subtitleLanguage

• Optional subtitleLanguage: string | string[]

Defines one or more subtitle languages which should be used
in the specified order on start up.

timeShift

• Optional timeShift: boolean

Enables time shift / DVR for live streams. Default is true (enabled). If time shift is disabled
(set to false), the timeline (scrub bar) will not be shown any more.

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. If there is a codec which is not
in this priority list, it will be tried only if none of this list are available / supported.
Default is ['dvhe', 'dvh1', 'vvc', 'vvi', 'av01', 'av1', 'hevc', 'hev', 'hvc', 'vp9', 'avc']

Since: 7.6

volume

• Optional volume: number

Defines the volume level of the player when started for the first time. Default value is 100.

StyleConfig

Interface

Example:

style : {
  width: '100%',
  aspectratio: '16:9',
}

Properties

aspectratio

• Optional aspectratio: string | number

The aspect ratio of the player, e.g. 16:9, 16:10, 4:3. Not more than two options of width, height,
and aspect ratio should be given. Defaults to 16:9.

container

• Optional container: () => HTMLElement

A callback to specify the element that the player will add style elements to.
Defaults to the head element.

Type declaration

▸ (): HTMLElement

Returns

HTMLElement

height

• Optional height: string

The height of the player. Can have any value including the unit (e.g. px, %, em, vh) usable in CSS,
e.g. 500px or 90%. Not more than two options of width, height, and aspect ratio should be given.
If no unit is give, 'px' is assumed.
If no height is given, the height is controlled via CSS aspect-ratio classes (default)

uiManagerFactory

• Optional uiManagerFactory: (playerAPI: PlayerAPI, config?: any) => any

A callback to provide a custom initialization of a UIManager for the Bitmovin Player Web UI.

Example:

uiManagerFactory = (playerAPI, config) => {
  // create and return your custom UIManager here
  return new bitmovin.playerui.UIFactory.buildUI(playerAPI, config);
};

Per default playerui.UIFactory.buildUI will be called to create the UI.

Type declaration

▸ (playerAPI, config?): any

Parameters

Returns

any

width

• Optional width: string

The width of the player. Can have any value including the unit (e.g. px, %, em, vw) usable in CSS,
e.g. 500px or 90%. Not more than two options of width, height, and aspect ratio should be given.
If no unit is given, 'px' is assumed.
If no width is given, the width is controlled via CSS aspect-ratio classes (default)

TweaksConfig

Interface

The tweaks configuration is used as an incubator for experimental features and also contains features
implemented for specific customers that might not make it into the officially supported feature set.

Tweaks are not officially supported and are not guaranteed to be stable, i.e. their naming, functionality
and API can change at any time within the tweaks or when being promoted to an official feature and moved into
its final configuration namespace.
Tweaks are often proof-of-concepts that are quickly implemented for urgent needs of customers. They often do
not go through an architectural review and are therefore not signed and approved by the architecture team.

Example:

tweaks : {
  max_buffer_level     : 20,
  query_parameters : {
    key1: 'value1',
    key2: 'value2',
    mycustomname: 'another-value'
  }
}

Indexable

▪ [key: string]: any

Tweaks are meant for experimental purpose and might often change so we allow the interface
to contain any option to avoid possible type checking failures.

Properties

adaptation_set_switching_without_supplemental_property

• Optional adaptation_set_switching_without_supplemental_property: boolean

Groups adaptation sets and switches between them based on their group attribute instead of the recommended
SupplementalProperty urn:mpeg:dash:adaptation-set-switching:2016. Default is false.

Since: 8.1

check_all_drm_licenses_for_kid

• Optional check_all_drm_licenses_for_kid: boolean

If set, the player checks all available DRM licenses when the key status for a KID updates.

Instead of surfacing an error once the KID becomes unusable on a license, the key status for the KID is checked
across all licenses. Only if the KID is not usable on any of the licenses an error is thrown.

Default is true.

Since: v8.140.2, v8.144.0

chunked_cmaf_streaming

• Optional chunked_cmaf_streaming: boolean

When set, the player will use the fetch API (instead of XMLHttpRequest) to download data segments and forward
any received and complete CMAF chunks to the decoder straight away while the respective request is still ongoing.

Enabling this tweak in combination with chunked CMAF content can yield faster video startup time and seeking.
Furthermore, it can be used to achieve low-latency live streaming as it enables usage of HTTP chunked transfer
encoding (CTE).

dash_clear_buffers_on_period_switches

• Optional dash_clear_buffers_on_period_switches: boolean

When set, the SourceBuffers will be cleared when transitioning from one DASH period to another, even when content
has compatible characteristics. Enabling this tweak can impact playback performance as transitions may become more
noticeable to the user, however it can also help overcome playback issues that may arise when working with DASH
streams having inconsistencies in the timing model.

Default is false. Buffers will only be cleared when strictly necessary, such as when transitioning from
encrypted to unencrypted content or vice versa.
However, if a shouldRecreateSourceBuffersOnPeriodSwitch callback is defined as part of
the SourceConfig, the player will autonomously consider this default to be true instead, so that the intended
behavior of the callback is still achieved, i.e. execute on every period switch.
If your shouldRecreateSourceBuffersOnPeriodSwitch implementation is rather intended
for disabling source buffer recreation for performance reasons, then it's recommended to set this tweak to false
explicitly, so that any unnecessary buffer clearings can be avoided as well. Note that in this case the callback
will only run for relevant period switches that require buffer clearing in any case (e.g. when transitioning from
encrypted to unencrypted content and vice versa).

Since: v8.215.0

disable_auto_recovery_on_dvr_window_exceeded

• Optional disable_auto_recovery_on_dvr_window_exceeded: boolean

If set, the player will not handle DVR window exceeded event by its default behavior of seeking to the live edge.
This is useful in case a custom behavior is desired, such as seeking to a specific position of the DVR window.
Default is false, meaning that the player will seek to the live edge when the DVR window is exceeded.

Since: v8.221.0

disable_parallel_segment_loading

• Optional disable_parallel_segment_loading: boolean

By default, the player will generally try to download audio and video segments in parallel as long as their buffer
levels are equal, while favoring the media with the lower buffer level when they differ. Also, the player will
download data and init segments concurrently.
Setting this tweak to true will instead disable parallel segment loading. In this case, the player will favor the
downloading of video segments over audio ones when their buffer levels are the same. Moreover, init and data
segments will always be downloaded sequencially if the tweak is enabled.

Default is false.

Since: v8.198.0

disable_retry_for_response_status

• Optional disable_retry_for_response_status: ResponseStatusMap

If a specific [[HttpRequestType]] has one or more HTTP status codes associated with it via this configuration
value, requests of that type will not be retried if they return one of the associated status codes.

Since: 8.4

Example:

disable_retry_for_response_status: {
  [HttpRequestType.MANIFEST_DASH]: [ 401 ]
}

dword_base_media_decode_timestamps

• Optional dword_base_media_decode_timestamps: boolean

Allows to use the Tizen module on non-Tizen platforms. This tweak requires the Tizen module to be effective.

enable_muted_background_playback

• Optional enable_muted_background_playback: boolean

When calling player.mute() the player will normally only set the muted flag on the media element. Chromium
based browsers can pause muted media elements when a different tab is selected in order to safe battery.

When this flag is set to true, the player will ensure the muted flag is not set on the media element and
only the volume is set to 0. This prevents the browser from pausing the media element, ensuring uninterrupted
playback but may result in higher battery consumption. The player will still report the same values for
isMuted() and getVolume() as if the tweak was not set (muted = true, volume > 0).

Default is false.

Since: v8.207.0

enable_performance_logs

• Optional enable_performance_logs: boolean

Enables additional debug logs that surface time measurements for certain operations performed in the player.
Such performance logs are prefixed with [Performance].

Default is false.

Since: v8.41.0

enable_seek_for_live

• Optional enable_seek_for_live: boolean

Specifies whether seek is allowed for live streams. By default this is not allowed.

enable_sgai_handling

• Optional enable_sgai_handling: boolean

Enables handling of HLS Interstitials (and SGAI in general in the future).
Requires AdvertisingCore module to be present.

Default is false.

Since: v8.238.0

fairplay_ignore_duplicate_init_data_key_errors

• Optional fairplay_ignore_duplicate_init_data_key_errors: boolean

If set, keyerror events will be ignored for Fairplay when more than one needkey event was triggered with
identical initData.

Since: 8.18.0

force_base_media_decode_time_rewrite

• Optional force_base_media_decode_time_rewrite: boolean

If set, every BaseMediaDecodeTime in data segments will be rewritten, regardless if they exceed 32 bits or not.
The tizen or webOS module has to be present and the player should run on Tizen or webOS TV.

Using this tweak might cause some unwanted problems when content has short discontinuities (e.g. SSAI streams).
Enabling the tweak is only recommended when the playback experience is improved on testing.

force_software_decryption

• Optional force_software_decryption: boolean

If set, software decryption is used over the browser's WebCrypto API for anything that the player manually
decrypts. E.g. for decrypting segments of DASH ClearKey-protected and HLS AES-128-encrypted streams.

Note: Proper DRM-protection such as Widevine and PlayReady is not affected by this tweak as decryption of such must
be handled by the browser's CDM.

hls_audio_only_threshold_bitrate

• Optional hls_audio_only_threshold_bitrate: number

All HLS variants with a bitrate lower than the given bitrate in bits per second (bps) are considered audio-only
variants and removed if there is at least one with a higher bitrate.

hls_backup_stream_penalty_duration

• Optional hls_backup_stream_penalty_duration: number

Defines the duration in seconds after which the backup stream penalization is considered to be expired.
The penalty is applied when a playlist, or one of its segments, has failed to load, and the player has
triggerd failover to a backup stream.

Default is 30 seconds.

hls_clear_buffers_on_discontinuity_switches

• Optional hls_clear_buffers_on_discontinuity_switches: boolean

When set, the SourceBuffers will be cleared when transitioning from one discontinuity to another, even when content
has compatible characteristics. Enabling this tweak can impact playback performance as transitions may become more
noticeable to the user, however it can also help overcome other playback issues.

Default is false. Buffers will only be cleared when strictly necessary, such as when transitioning from
encrypted to unencrypted content or vice versa.

Since: v8.93.0

hls_parse_manifest_in_worker

• Optional hls_parse_manifest_in_worker: boolean

When set, the player will parse the manifest in a worker thread. This can improve the performance of the player
when the manifest is large.

Default is false.

hls_parse_native_metadata

• Optional hls_parse_native_metadata: boolean

Whether the native player used for HLS on Safari should subscribe to cuechange events from the metadata TextTrack
and relay ID3 events as Metadata events.

Note: This tweak has no effect if the MSE-based player (i.e. Html5) is used.

Default is true.

Since: v8.158.0

hls_sync_segment_playback_time_via_media_sequence

• Optional hls_sync_segment_playback_time_via_media_sequence: boolean

When set, the playback times of the segments between HLS playlist are synced using
media sequence number during quality switch.

Default is false.

ignore_mp4_edts_box

• Optional ignore_mp4_edts_box: boolean

If enabled, Edit (edts) boxes in MP4 segments which would introduce a segment start time offset are filtered from
segments before forwarding them to the decoder. This is required as browsers are handling such boxes differently.
This flag ensures consistent cross-browser behavior in this matter and is enabled by default.

Since: 8.3

impressionServer

• Optional impressionServer: string

Sets the impression server to the given URL if allowlisted.
Default is the bitmovin impression server URL.

infinite_retries_for_live

• Optional infinite_retries_for_live: boolean

If a live stream becomes unreachable during playback, i.e. requests are failing for segments and/or HLS playlists,
the player will not throw an error after all qualities have been tried if the tweak is set. Instead, it will keep
trying and, in case the stream comes back online, the player will resume playback.
If the tweak is disabled, the player will throw a network error after exhausting all qualities.

Default is true.

Since: v8.175.0

licenseServer

• Optional licenseServer: string

Sets the license server to the given URL if allowlisted.
Default is the bitmovin license server URL.

log_level

• Optional log_level: LogLevel

Sets the LOG_LEVEL of the player by calling setLogLevel.

max_buffer_level

• Optional max_buffer_level: number

Changes the maximum buffer level in seconds. Default is 40 seconds.
For live streams the lowest value of playlist duration for HLS, timeShiftBufferDepth for DASH and
the max_buffer_level is used as a maximum value for the buffer.

Deprecated: Use forwardduration instead.

max_cdn_retries

• Optional max_cdn_retries: number

The number of retries per CDN if a download error occurred in VoD streams
By default the player will retry 2 times.

max_mpd_retries

• Optional max_mpd_retries: number

Amount of times to retry a failed MPD download before throwing an error for failed download.
By default the player will retry 2 times.

max_retries

• Optional max_retries: number

Maximum number of retries when network request fails for the provided manifest.
Applies for both master and variant playlist in case of Hls.

Default value is 2.

max_safe_mse_duration

• Optional max_safe_mse_duration: number

For live streams, Infinity is typically set as duration on the MediaSource object. This can cause problems
on some legacy platforms. On those, finite values like Number.MAX_SAFE_INTEGER could resolve playback start
issues of live streams.

Default is Infinity.

Since: v8.192.0

max_startup_buffer

• Optional max_startup_buffer: number

The maximum amount of buffer (in seconds) to be built upon initial play.

The player will stop loading segments once this buffer level is reached and will not load any further content until
playback starts. This helps avoid excessive content loading at startup, which can lead to longer startup times.

• A value of 0 applies platform-specific defaults:
  • Samsung Tizen and LG webOS TVs: 2.5 seconds
  • Other platforms: no limit
• A value of Infinity disables this behavior, effectively limiting the loaded buffer only by the configured forward buffer duration.
• A positive value sets a specific buffer limit; the player will stop loading once this level is reached.

Note: On older TV platforms (webOS 2016-2020 and Tizen 2016-2019), a minimum buffer of 4 or 6 seconds is enforced,
and any value lower than that will be overridden.

Default value: 0.

Since: v8.214.0

min_size_for_gap_skipping

• Optional min_size_for_gap_skipping: number

Gaps in content that are smaller than this value will not be skipped. This tweak should be used if gap skipping
is unnecessary: some browsers are able to play through small gaps in content without getting stuck.

Default value is 0, which means that all encountered gaps will be skipped.

minimal_backward_buffer_clearing_interval

• Optional minimal_backward_buffer_clearing_interval: number

Defines the minimum interval in seconds at which the backward buffer will be cleared.

Default is 0.5

mpd_retry_delay

• Optional mpd_retry_delay: number

The time in seconds to wait before trying to download the MPD again after a download error occurred.
By default the player will retry in half a second

mpd_update_period_tolerance

• Optional mpd_update_period_tolerance: number

The time in seconds that the MPD age for live streams may exceed the minimumUpdatePeriod, before it should be
considered outdated. By default the player will use 5 seconds.

native_hls_download_error_handling

• Optional native_hls_download_error_handling: boolean

If enabled the native player used for HLS in Safari would fetch and parse the HLS playlist and trigger
an Error event if the download of a segment fails and the playback stalls. Default is false.

native_hls_parsing

• Optional native_hls_parsing: boolean

If enabled the native player used for HLS in Safari would fetch and parse the HLS playlist and trigger
SegmentPlayback events carrying segment-specific metadata like #EXT-X-PROGRAM-DATE-TIME
if present in the manifest. Default is false.

no_quota_exceeded_adjustment

• Optional no_quota_exceeded_adjustment: boolean

Specifies whether the Player should not adjust the target buffer levels after a QuotaExceededError.

Since: 8.25.0

parse_cea_708_caption

• Optional parse_cea_708_caption: boolean

When set, CEA-708 captions are parsed when present in the source stream, instead of CEA-608.
By default CEA-608 captions are parsed.

parse_emsg_boxes

• Optional parse_emsg_boxes: boolean

Whether the player should parse and process emsg boxes from MP4 segments.

Note: This tweak is limited to the MSE-based player (i.e. if getPlayerType returns
Html5) and has no effect for the native player (Native).

Default is true.

Since: v8.98.0

playstation_5

• Optional playstation_5: PlayStation5Tweaks

PlayStation 5 Platform tweaks

postpone_manifest_updates_until_playback_start

• Optional postpone_manifest_updates_until_playback_start: boolean

In case of live streams that require manifest updates, this tweak causes the player to delay the scheduling of
such updates until playback has started, which can help improve startup time on slower devices. Does not take
an effect on HLS low latency streams.

Default is true.

Since: v8.209.0

prefer_managed_media_source

• Optional prefer_managed_media_source: boolean

Use ManagedMediaSource over regular MediaSource when both are available.

Default is true.

prevent_video_element_preloading

• Optional prevent_video_element_preloading: boolean

This flag prevents the native video element from preloading any data (sets preload='none').
When enabled, in case of native HLS playback on Safari, this will cause e.g. AudioTracks
not being added or duration not being available before playback starts.

Note: To limit preloading to metadata only (sets preload='metadata'), use preload
set to false instead.

proactive_gap_skip_distance_seconds

• Optional proactive_gap_skip_distance_seconds: number

If set to a value greater than 0, gaps in the content will be skipped proactively. The skip distance defines how
many seconds prior to the gap, the gap will be skipped.

Default value is 0, which disables proactive gap skipping.

Since: v8.53.0

query_parameters

• Optional query_parameters: QueryParameters

Query parameters are added as GET parameters to all request URLs (e.g. manifest, media segments,
subtitle files, …). Query_parameters should be an object with key value pairs, where the keys are
used as parameter name and the values as parameter values.

Example:

query_parameters : {
  key1: 'value1',
  key2: 'value2',
  mycustomname: 'another-value'
}

The example above would be translated into MY_REQUEST_URL?key1=value1&key2=value2&mycustomname=another-value.

restart_threshold

• Optional restart_threshold: number

Amount of seconds the player buffers before playback starts again after a stall. Default is 0.9 seconds.
This value is restricted to the maximum value of the buffer minus 0.5 seconds.

resume_live_content_at_previous_position_after_ad_break

• Optional resume_live_content_at_previous_position_after_ad_break: boolean

Specifies whether live content should resume playback from the same position it was prior to the ad break.
Default is false: the live content will be replaced for the duration of the ad break, and playback will resume
with the same distance from live edge as before the ad break.

Note: this tweak is ignored if replaceContentDuration is set. In such case, the live
content is rather replaced for the duration defined via this config as opposed to using the ad duration.

Since: 8.27.0

segment_encryption_transition_handling

• Optional segment_encryption_transition_handling: boolean

Makes sure that player initialize period switch and recreate source buffers in case that we are switching
from unenctyped to encrypted segments. This fixes the issues with pixelated picture on playready protected
HLS stream with unecrypted SSAI in MS Edge.

Deprecated: As of 8.33.0 new buffer handling covers this case by default so it doesn't have any effect.

Since: 8.25.1

serviceworker_scope

• Optional serviceworker_scope: string

Defines the scope of the ServiceWorker that is created in the bitmovin-serviceworker-client.js module.

Since: 8.13.0

startup_threshold

• Optional startup_threshold: number

Amount of seconds the player buffers before playback starts. Default is 0.9 seconds.
This value is restricted to the maximum value of the buffer minus 0.5 seconds.

stop_download_on_pause

• Optional stop_download_on_pause: boolean

Enabling this flag prevents the player from downloading any further resource (playlist, segments, ...), when the
player is paused. Already issued requests will be finished. Default is false.

tizen_max_safe_bmdt

• Optional tizen_max_safe_bmdt: number

Maximum Base Media Decode Time value that is considered safe on the Tizen platform. Any exceeding value will be
rewritten to be smaller. This tweak requires the Tizen module.

Default value is 2**32 - 1 (aka 32 bits) on Tizen 2016-2018, and Infinity on Tizen 2019+.

tizen_max_safe_pto

• Optional tizen_max_safe_pto: number

Maximum Presentation Time Offset value that is considered safe on the Tizen platform. Any exceeding value will be
rewritten to be smaller. This tweak requires the Tizen module.

Default value is 2**32 - 1 (aka 32 bits) on Tizen 2016-2018, and Infinity on Tizen 2019+.

webos_max_safe_bmdt

• Optional webos_max_safe_bmdt: number

Maximum Base Media Decode Time value that is considered safe on the webOS platform. Any exceeding value will be
rewritten to be smaller. This tweak requires the webOS module.

Default value is 2**38 - 1 (aka 38 bits) on webOS 2016-2019, and Infinity on webOS 2020+.

webos_max_safe_pto

• Optional webos_max_safe_pto: number

Maximum Presentation Time Offset value that is considered safe on the webOS platform. Any exceeding value will be
rewritten to be smaller. This tweak requires the webOS module.

Default value is 2**22 - 1 (aka 22 bits) on webOS 2016-2019, and Infinity on webOS 2020+.

wish_abr_params

• Optional wish_abr_params: WishAbrConfig

Configuration options for WISH ABR logic.
You can enable the logic by setting logic to WISH.

LogsConfig

Interface

Properties

bitmovin

• Optional bitmovin: boolean

Enable (true, default) or disable the Bitmovin credits in the browser's console.

level

• Optional level: LogLevel

Sets the log level for debug output, warnings and errors sent to the browser console.

Please note that especially DEBUG but also LOG level should not be used for production environments as
this can decrease performance, especially for long-term playback, due to the amount of log messages.

Available values are:

• bitmovin.player.LogLevel.DEBUG
• bitmovin.player.LogLevel.LOG
• bitmovin.player.LogLevel.WARN (default)
• bitmovin.player.LogLevel.ERROR
• bitmovin.player.LogLevel.OFF

onLog

• Optional onLog: LogCallback

This callback will be called for every message that would be logged to the console regardless of the configured log
level.

LocationConfig

Interface

Example:

location : {
  vr: 'MY_VR_FOLDER/my_bitmovinplayer-vr.js',
  ui: 'MY_JS_FOLDER/my_bitmovinplayer-ui.js',
  ui_css: 'MY_CSS_FOLDER/my_bitmovinplayer-ui.css',
  cast: 'https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1',
  google_ima: 'https://imasdk.googleapis.com/js/sdkloader/ima3.js'
}

Properties

cast

• Optional cast: string

The URL of the Google Cast Chrome Sender API library.

Default URL: https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1

google_ima

• Optional google_ima: string

The URL of the Google IMA Framework.

Default URL: https://imasdk.googleapis.com/js/sdkloader/ima3.js

Deprecated: Use ImaAdvertisingConfig.sdkUrl instead.

serviceworker

• Optional serviceworker: string

Specifies the path, relative or absolute, to the service worker JS file.

If no URL is provided but the bitmovin-serviceworker.js module is added, the setup will fail
with SETUP_SERVICE_WORKER_LOCATION_MISSING

Preconditions for the ServiceWorker to work:

• This property has to be set to the URL of a ServiceWorker implementation
• This file has to be placed on the same level as the serving HTML page
• The content source used with the player has to enable CORS

Supported events when ServiceWorker is enabled:

• MetadataParsed and Metadata for the metadata present in the HLS playlist:
  • DATERANGE
  • CUETAG
  • CUSTOM
  • SCTE
• SegmentPlayback
• VideoDownloadQualityChanged

Supported API with ServiceWorker:

• getPlaybackVideoData
• getDownloadedVideoData

ui

• Optional ui: string

Specifies the path, relative or absolute, to the Bitmovin Player UI/skin JavaScript file.

Default name: bitmovinplayer-ui.js

ui_css

• Optional ui_css: string

Specifies the path, relative or absolute, to the style sheet of the Bitmovin Player UI/skin.

Default name: bitmovinplayer-ui.css

LicensingConfig

Interface

Properties

delay

• Optional delay: number

Can be used to set the delay (in milliseconds) until the licensing call is issued.
Maximum value is 30000 (30 seconds).

LiveConfig

Interface

Configuration interface for properties used for live streams.

Example:

{
  synchronization: [{
    method: LiveSynchronizationMethod.HttpHead,
    serverUrl: 'http://time.akamai.com',
  }],
}

Properties

incrementalManifestUpdates

• Optional incrementalManifestUpdates: boolean

Flag to control whether incremental manifest updates are made instead of full updates, provided that the current
source supports it.

Incremental updates improve network and client processing efficiency by reducing the amount of data being
transferred and processed.

This feature is currently supported for HLS sources that support
Playlist Delta Updates.

Default is true.

lowLatency

• Optional lowLatency: LowLatencyConfig

Configuration to enable maintaining a desired live latency.

synchronization

• Optional synchronization: SynchronizationConfigEntry[]

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

HlsConfig

Interface

Configuration for HLS related settings.

Since: 8.238.0

Properties

interstitials

• Optional interstitials: InterstitialsConfig

Configuration for interstitials in HLS streams.

LowLatencyConfig

Interface

Configuration for live streams to maintain a certain live latency.

Properties

catchup

• Optional catchup: LowLatencySyncConfig

Configuration defining catchup to be done if the player exceeds the target latency.

fallback

• Optional fallback: LowLatencySyncConfig

Configuration defining fallback to be done if the player falls below the target latency.

targetLatency

• Optional targetLatency: number

The target latency in seconds, i.e. the distance from the stream's live edge to be maintained by the player during
playback.

Default: 5

LowLatencySyncConfig

Interface

Configuration specifying live latency synchronization (i.e. maintaining latency by catchup/fallback)

Properties

playbackRate

• Optional playbackRate: number

Playback speed to be used for catchup/fallback.

Defaults: 1.2 for catchup and 0.95 for fallback.

playbackRateThreshold

• Optional playbackRateThreshold: number

Allowed deviation from target latency before catchup/fallback by changing the playback speed is done.

Default: Infinity (i.e. disabled)

seekThreshold

• Optional seekThreshold: number

Allowed deviation from target latency before catchup/fallback by seeking is done.

Default: Infinity (i.e. disabled)

PlaybackRestrictions

Interface

Playback restrictions that can be applied during content playback.
Used for controlling user interactions during ad playback or other restricted content.

Properties

playbackRate

• Optional playbackRate: boolean

If true, playback rate changes will be disabled during playback.

seeking

• Optional seeking: boolean

If true, seeking will be disabled during playback.

PreferredTechnology

Interface

A player and streaming technology tuple describing a supported technology of the player.

Hierarchy

• Technology

  ↳ PreferredTechnology

Properties

exclude

• Optional exclude: boolean

Set to true to exclude this technology from the list of preferred technologies.

player

• player: PlayerType

A string determining a rendering mode used to render the player.
See PlayerType for details of the supported values.

Inherited from

Technology.player

streaming

• streaming: StreamType

A string determining a streaming technology.
See StreamType for details of the supported values.

Inherited from

Technology.streaming

Technology

Interface

A player and streaming technology tuple describing a supported technology of the player.

Hierarchy

• Technology

  ↳ PreferredTechnology

Properties

player

• player: PlayerType

A string determining a rendering mode used to render the player.
See PlayerType for details of the supported values.

streaming

• streaming: StreamType

A string determining a streaming technology.
See StreamType for details of the supported values.

StorageConfig

Interface

Allows controlling the player's storage behavior.

Properties

disableStorageApi

• Optional disableStorageApi: boolean

Controls whether the browser may access the Web Storage API which consists of

• window.localStorage
• window.sessionStorage

If the device would not support the localStorage, the player would
then fallback to use document.cookie.

If set to true, the player will not store anything in either one.
If set to false (default case), the player will store information about DRM licenses,
bandwidth measurements and VAST ad information.

SynchronizationConfigEntry

Interface

Properties

method

• method: LiveSynchronizationMethod

Method how to extract the time information from the time server response.

serverUrl

• serverUrl: string

URL of the time server

PlayStation5Tweaks

Interface

Properties

esvm

• Optional esvm: boolean

Enables the Enhanced Security Video Mode. This uses a more secure video render pipeline which is required
when content is encrypted with PlayReady SL-3000 or Widevine L1, and/or HDR/10-bit content.

Playback of PlayReady SL-3000, Widevine L1 and/or HDR/10-bit content both require esvm to be set to true.
If it is set to false a decoding error will occur.
PlayReady SL-2000, Widevine L2 or L3, unprotected, and/or SDR content, can also be played when esvm is true.

When setting esvm, all previous video elements must be destroyed.
This cannot change during any form of video playback.

Default is false

Since: 8.88.0

pass_through

• Optional pass_through: boolean

The pass_through option enables and disables audio pass-through.

If enabled, audio is passed through to the AV Receiver to decompress audio.
If disabled, the PlayStation® console will decompress audio into LPCM.

Only one audio stream can be passed through to the AV Receiver at a time.
Attempting to enable pass_through on a second video element when the first is still active
will result in an error.

Default is false

Since: 8.88.0

playmode

• Optional playmode: "4K" | "2K"

This flag is used to define hardware resources when playing multiple videos at the same time.
If playing only a single video, or two videos up with combined resolution up to 4k
the playmode can be left as "4K" - which is also capable of playing 2K content.

• "4K" Informs the underlying video engine that this SourceBuffer will play content above 2K and up to 4K.
• "2K" Informs the underlying video engine that this SourceBuffer will not play content above 2K.
  Playback of 4K content in this mode will result in an error.

When setting playmode, all previous video elements must be destroyed.
This cannot change during any form of video playback.

Default is "4K"

Since: 8.88.0

LogLevel

Enum

Enumeration Members

DEBUG

• DEBUG = "debug"

ERROR

• ERROR = "error"

LOG

• LOG = "log"

OFF

• OFF = "off"

WARN

• WARN = "warn"

LatencyMode

Enum

Enumeration Members

Catchup

• Catchup = "catchup"

The player is behind the target latency and performing catchup.

Fallback

• Fallback = "fallback"

The player is ahead of the target latency and performing fallback.

Idle

• Idle = "idle"

The player is playing at the target latency.

Suspended

• Suspended = "suspended"

Controlling the latency is temporarily disabled due to not playing at the live edge or a user-defined
playback speed (i.e. unequal to 1) being set.

LiveSynchronizationMethod

Enum

Method to be used for time server response parsing

Enumeration Members

HttpHead

• HttpHead = "httphead"

The time information is in the response HTTP 'Date' header.

HttpIso

• HttpIso = "httpiso"

The time information is in the response body a ISO 8601 timestamp.

HttpXsDate

• HttpXsDate = "httpxsdate"

The time information is in the response body in xs:date format.

SupportedTechnologyMode

Enum

The mode how supported technologies are determined. getSupportedTech

Since: v8.1.0

Enumeration Members

Modules

• Modules = "modules"

Technologies supported by the loaded player modules.

Platform

• Platform = "platform"

Technologies supported by the executing platform.

PlatformAndModules

• PlatformAndModules = "platformandmodules"

Technologies supported by the loaded player modules on the executing platform.