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'
}
}
interface TweaksConfig {
    adaptation_set_switching_without_supplemental_property?: boolean;
    check_all_drm_licenses_for_kid?: boolean;
    chunked_cmaf_streaming?: boolean;
    dash_clear_buffers_on_period_switches?: boolean;
    disable_parallel_segment_loading?: boolean;
    disable_retry_for_response_status?: ResponseStatusMap;
    dword_base_media_decode_timestamps?: boolean;
    enable_muted_background_playback?: boolean;
    enable_seek_for_live?: boolean;
    fairplay_ignore_duplicate_init_data_key_errors?: boolean;
    force_base_media_decode_time_rewrite?: boolean;
    force_software_decryption?: boolean;
    hls_audio_only_threshold_bitrate?: number;
    hls_backup_stream_penalty_duration?: number;
    hls_clear_buffers_on_discontinuity_switches?: boolean;
    hls_parse_manifest_in_worker?: boolean;
    hls_parse_native_metadata?: boolean;
    hls_sync_segment_playback_time_via_media_sequence?: boolean;
    ignore_mp4_edts_box?: boolean;
    impressionServer?: string;
    infinite_retries_for_live?: boolean;
    licenseServer?: string;
    log_level?: LogLevel;
    max_buffer_level?: number;
    max_cdn_retries?: number;
    max_mpd_retries?: number;
    max_retries?: number;
    max_safe_mse_duration?: number;
    max_startup_buffer?: number;
    min_size_for_gap_skipping?: number;
    minimal_backward_buffer_clearing_interval?: number;
    mpd_retry_delay?: number;
    mpd_update_period_tolerance?: number;
    native_hls_download_error_handling?: boolean;
    native_hls_parsing?: boolean;
    no_quota_exceeded_adjustment?: boolean;
    parse_cea_708_caption?: boolean;
    parse_emsg_boxes?: boolean;
    playstation_5?: PlayStation5Tweaks;
    postpone_manifest_updates_until_playback_start?: boolean;
    prefer_managed_media_source?: boolean;
    preserve_gaps_for_base_media_decode_time_rewrite?: boolean;
    prevent_video_element_preloading?: boolean;
    query_parameters?: QueryParameters;
    restart_threshold?: number;
    resume_live_content_at_previous_position_after_ad_break?: boolean;
    segment_encryption_transition_handling?: boolean;
    serviceworker_scope?: string;
    startup_threshold?: number;
    stop_download_on_pause?: boolean;
    tizen_max_safe_bmdt?: number;
    tizen_max_safe_pto?: number;
    webos_max_safe_bmdt?: number;
    webos_max_safe_pto?: number;
    wish_abr_params?: WishAbrConfig;
    [key: string]: any;
}

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? check_all_drm_licenses_for_kid? chunked_cmaf_streaming? dash_clear_buffers_on_period_switches? disable_parallel_segment_loading? disable_retry_for_response_status? dword_base_media_decode_timestamps? enable_muted_background_playback? enable_seek_for_live? fairplay_ignore_duplicate_init_data_key_errors? force_base_media_decode_time_rewrite? force_software_decryption? hls_audio_only_threshold_bitrate? hls_backup_stream_penalty_duration? hls_clear_buffers_on_discontinuity_switches? hls_parse_manifest_in_worker? hls_parse_native_metadata? hls_sync_segment_playback_time_via_media_sequence? ignore_mp4_edts_box? impressionServer? infinite_retries_for_live? licenseServer? log_level? max_buffer_level? max_cdn_retries? max_mpd_retries? max_retries? max_safe_mse_duration? max_startup_buffer? min_size_for_gap_skipping? minimal_backward_buffer_clearing_interval? mpd_retry_delay? mpd_update_period_tolerance? native_hls_download_error_handling? native_hls_parsing? no_quota_exceeded_adjustment? parse_cea_708_caption? parse_emsg_boxes? playstation_5? postpone_manifest_updates_until_playback_start? prefer_managed_media_source? preserve_gaps_for_base_media_decode_time_rewrite? prevent_video_element_preloading? query_parameters? restart_threshold? resume_live_content_at_previous_position_after_ad_break? segment_encryption_transition_handling? serviceworker_scope? startup_threshold? stop_download_on_pause? tizen_max_safe_bmdt? tizen_max_safe_pto? webos_max_safe_bmdt? webos_max_safe_pto? wish_abr_params?

Properties

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?: 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?: 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?: 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 overcoming 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_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?: 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?: boolean

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

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_seek_for_live?: boolean

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

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?: 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?: 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?: 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?: 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?: boolean

When set, the SourceBuffers will be cleared between segments with different discontinuities that otherwise have matching properties. This tweak can be used to switch this behaviour off for certain streams to gain more performance and seamless playback between discontinuity boundaries.

Default is true.

Since

v8.93.0

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?: 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?: 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?: 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?: string

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

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?: string

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

log_level?: LogLevel

Sets the LOG_LEVEL of the player by calling setLogLevel.

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?: 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?: 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?: 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?: 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?: 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?: 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?: number

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

Default is 0.5

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?: 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?: 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?: 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?: boolean

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

Since

8.25.0

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?: 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?: PlayStation5Tweaks

PlayStation 5 Platform tweaks

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?: boolean

Use ManagedMediaSource over regular MediaSource when both are available.

Default is true.

preserve_gaps_for_base_media_decode_time_rewrite?: boolean

If set to true, the BMDT will preserve possible gaps in segments while rewriting timestamps, which may prevent out of sync audio and video.

prevent_video_element_preloading?: boolean

This flag indicates whether we prevent the native video element to preload data. Metadata will always be preloaded. In case of native HLS playback on Safari, this will cause e.g. AudioTracks not being added, before the playback starts.

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?: 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?: boolean

Specifies whether live content should resume playback at the playback time before the ad break. This is required in order to be able to use replaceContentDuration for live streams. By default, live content resumes at the live edge. Note: enable_seek_for_live is required if this is set to true.

Since

8.27.0

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?: string

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

Since

8.13.0

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?: 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?: 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?: 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?: 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?: 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?: WishAbrConfig

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