bitmovin-player
Version:
The Bitmovin HTML5 Adaptive Streaming Player for MPEG-DASH and HLS
1,462 lines (1,461 loc) • 50.2 kB
TypeScript
/**
* The entry point to the player configuration is the {@link 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:
*
* ```js
* const player = new bitmovin.player.Player(container, config);
* ```
*
* 2) Whe the player is loaded from the CDN via {@link https://requirejs.org/|RequireJS}:
*
* ```js
* requirejs(['<cdn_url>'], (bitmovinplayer) => {
* const player = new bitmovinplayer.Player(container, config);
* });
* ```
*
* 3) When the player is imported from NPM:
*
* ```ts
* import { Player } from 'bitmovin-player';
* const player = new Player(container, config);
* ```
*
* Example configuration:
*
* ```js
* {
* 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:
*
* ```js
* 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'
* }
* }
* });
* ```
*
* @module Core.Config
*/ /** */
import { AdvertisingConfig } from '../advertising/ConfigAPI';
import { DRMConfig } from '../drm/ConfigAPI';
import { GoogleCastRemoteControlConfig as InternalGoogleCastRemoteControlConfig } from '../remotecontrol/GoogleCastRemoteControlConfig';
import { WebSocketRemoteControlConfig as InternalWebSocketRemoteControlConfig } from '../remotecontrol/WebSocketRemoteControlConfig';
import { SubtitleTrack } from '../subtitles/API';
import { VRConfig } from '../vr/ConfigAPI';
import { HttpHeaders, NetworkConfig } from './NetworkAPI';
import { LogLevel, PlayerEventCallback, Technology } from './PlayerAPI';
export interface ProgressiveSourceConfig {
/**
* The URL to the progressive video file.
*/
url: string;
/**
* The MIME type of the video file, e.g. “video/mp4” or “video/webm”.
*/
type?: string;
/**
* 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.
*/
bitrate?: number;
/**
* 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.
*/
preferred?: boolean;
/**
* Specifies the label to be displayed in the quality selection in the player’s settings window.
*/
label?: string;
}
export interface SourceConfigOptions {
/**
* Send credentials and cookies along with cross origin manifest (HLS and MPEG-DASH) requests.
* Must be supported by the server. Default is `false`.
*/
manifestWithCredentials?: boolean;
/**
* Send credentials and cookies along with cross origin (HLS and MPEG-DASH) segment requests.
* Must be supported by the server. Default is `false`.
*/
withCredentials?: boolean;
/**
* Send credentials and cookies along with cross origin HLS manifest requests.
* Must be supported by the server. Default is `false`.
*/
hlsManifestWithCredentials?: boolean;
/**
* Send credentials and cookies along with cross origin HLS segment requests.
* Must be supported by the server. Default is `false`.
*/
hlsWithCredentials?: boolean;
/**
* Send credentials and cookies along with cross origin MPEG-DASH manifest requests.
* Must be supported by the server. Default is `false`.
*/
dashManifestWithCredentials?: boolean;
/**
* Send credentials and cookies along with cross origin MPEG-DASH segment requests.
* Must be supported by the server. Default is `false`.
*/
dashWithCredentials?: boolean;
/**
* If set to `true`, this will keep the poster image visible during playback, e.g. for audio-only streams.
*/
persistentPoster?: boolean;
/**
* The position in fractional seconds to start playback from.
* @since 7.1
* @deprecated use StartOffset instead
*/
startTime?: number;
/**
* The position where the stream should be started. Number can be positive or negative depending on the used
* {@link 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:
* ```js
* // 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
*/
startOffset?: number;
/**
* Timeline reference point to calculate {@link SourceConfigOptions.startOffset} from.
* Default for live: `TimelineReferencePoint.End`
* Default for VOD: `TimelineReferencePoint.Start`
*/
startOffsetTimelineReference?: TimelineReferencePoint;
/**
* 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
* {@link PlaybackConfig.audioCodecPriority}
* @since 7.6
*/
audioCodecPriority?: 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
* {@link PlaybackConfig.videoCodecPriority}
* @since 7.6
*/
videoCodecPriority?: string[];
headers?: HttpHeaders;
}
export declare enum TimelineReferencePoint {
/**
* `startOffset` will be calculated from the beginning of the stream or DVR window.
*/
Start = "start",
/**
* `startOffset` will be calculated from the end of the stream or the live edge in case of a live stream with DVR
* window.
*/
End = "end",
/**
* Specify the default starting point for live(same as End) or VOD(same as Start).
*
* @hidden - not implemented yet
*/
CurrentTime = "currenttime"
}
export interface ThumbnailTrack {
/**
* The URL to the associated file.
*/
url: string;
}
export interface TrackMetadata {
/**
* Unique identifier of the track.
*/
id?: string;
/**
* Mime type of the track.
*/
mimeType?: string;
/**
* Language of the track. Only applicable for audio and subtitles, otherwise `undefined`.
*/
lang: string;
}
export interface QualityMetadata {
/**
* Unique identifier of the quality.
*/
id: string;
/**
* Mime type of the quality.
*/
mimeType: string;
/**
* Bitrate of the quality.
*/
bitrate: number;
/**
* Width of the quality. Only applicable for video tracks, otherwise `undefined`.
*/
width: number;
/**
* Height of the quality. Only applicable for video tracks, otherwise `undefined`.
*/
height: number;
/**
* The quality ranking as given in the manifest. `undefined` if not present.
*/
qualityRanking?: number;
/**
* Frame rate of the quality. Only applicable for video tracks, otherwise `undefined`.
*/
frameRate?: number;
}
/**
* An object with callback functions to provide labels for audio tracks, qualities and subtitle tracks.
*/
export interface SourceLabelingConfig {
/**
* A function that generates a label for a track, usually an audio track.
* @param track 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.
*/
tracks?: (track: TrackMetadata) => string;
/**
* A function that generates a label for a quality, usually a video quality.
* @param quality Object with metadata about the quality for which the label should be generated.
*/
qualities?: (quality: QualityMetadata) => string;
/**
* A function that generates a label for a subtitle.
* @param subtitle The subtitle for which the label should be generated.
*/
subtitles?: (subtitle: SubtitleTrack) => string;
}
/**
* The source object is passed into {@link PlayerAPI.load} to load a new source.
*
* Example:
* ```js
* 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',
* }],
* 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';
* }
* }
* }
* });
* ```
*/
export interface SourceConfig {
/**
* 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.
*/
dash?: string;
/**
* An URL to an HLS playlist file (M3U8). The file has to be a valid M3U8 playlist.
*/
hls?: string;
/**
* 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.
*/
progressive?: string | ProgressiveSourceConfig[];
/**
* An URL to a SmoothStreaming manifest file (xml or ismc). The file has to be a valid smooth streaming manifest
* file.
*/
smooth?: string;
/**
* The URL to a preview image displayed until the video starts. Make sure JavaScript and Flash are 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.
*/
poster?: string;
/**
* The DRM object should be included into the source object.
*/
drm?: DRMConfig;
/**
* An object specifying advanced source specific options.
*/
options?: SourceConfigOptions;
/**
* An array of external subtitle tracks.
*/
subtitleTracks?: SubtitleTrack[];
/**
* A thumbnail track.
*/
thumbnailTrack?: ThumbnailTrack;
/**
* Configuration for VR and omnidirectional (360°) video.
*/
vr?: VRConfig;
/**
* The title of the video source.
*/
title?: string;
/**
* The description of the video source.
*/
description?: string;
/**
* Labeling config for the different stream types.
*/
labeling?: SourceLabelingStreamTypeConfig;
}
/**
* Labeling config for the different stream types.
*/
export interface SourceLabelingStreamTypeConfig {
/**
* Labeling functions for DASH sources.
*/
dash?: SourceLabelingConfig;
/**
* Labeling functions for HLS sources.
*/
hls?: SourceLabelingConfig;
}
export interface PreferredTechnology extends Technology {
/**
* Set to `true` to exclude this technology from the list of preferred technologies.
*/
exclude?: boolean;
}
/**
* Example:
* ```js
* playback : {
* autoplay: false,
* muted: false,
* audioLanguage: ['en', 'es', 'de'],
* subtitleLanguage: 'en',
* preferredTech: [{
* player: 'html5',
* streaming: 'dash'
* }, {
* player: 'flash',
* streaming: 'hls'
* }]
* }
* ```
*/
export interface PlaybackConfig {
/**
* Whether the player starts playing after loading a source or not (`false`, default).
* Note that unmuted autoplay is blocked on several browsers, check for {@link Events.Warning} with code
* {@link WarningCode.PLAYBACK_COULD_NOT_BE_STARTED} for detecting the blocking.
*/
autoplay?: boolean;
/**
* Whether the sound is muted on startup or not (`false`, default).
*/
muted?: boolean;
/**
* Defines the volume level of the player when started for the first time. Default value is 100.
*/
volume?: number;
/**
* Defines one or more subtitle languages which should be used
* the specified order on start up.
*/
audioLanguage?: string | string[];
/**
* Defines one or more subtitle languages which should be used
* in the specified order on start up.
*/
subtitleLanguage?: string | string[];
/**
* 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.
*/
timeShift?: boolean;
/**
* Whether to allow seeking or not. Default is true.
*/
seeking?: 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.
*/
playsInline?: boolean;
/**
* 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.
*
* Player technologies:
* - `html5` refers to the MediaSource Extension (MSE) based JavaScript player
* - `flash` refers to the Flash fallback
* - `native` refers to the browser’s native capabilities are being used, e.g. playing back HLS in Safari on iOS
*
* Currently supported combinations:
* ```js
* { player: 'html5', streaming: 'dash'}
* { player: 'html5', streaming: 'hls'}
* { player: 'html5', streaming: 'smooth'}
* { player: 'native', streaming: 'hls'}
* { player: 'flash', streaming: 'dash'}
* { player: 'flash', streaming: 'hls'}
* { player: 'flash', streaming: 'smooth'}
* { player: 'native-flash', streaming: 'hls'}
* { player: 'native', streaming: 'progressive'}
* ```
*
* Example:
* ```js
* preferredTech : [{
* player: 'html5',
* streaming: 'dash'
* }, {
* player: 'flash',
* streaming: 'hls'
* }]
* ```
*/
preferredTech?: PreferredTechnology[];
/**
* 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-3', 'mp4a.a6', 'ac-3', 'mp4a.a5', 'mp4a.40']`
* @since 7.6
*/
audioCodecPriority?: 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 `['av1',
* 'hevc', 'hvc', 'vp9', 'avc']`
* @since 7.6
*/
videoCodecPriority?: string[];
}
/**
* Example:
* ```js
* style : {
* width: '100%',
* aspectratio: '16:9',
* }
* ```
*/
export interface StyleConfig {
/**
* 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)
*/
width?: 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)
*/
height?: string;
/**
* 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.
*/
aspectratio?: string | number;
/**
* Specifies whether native subtitle rendering should always be enabled for native HLS and progressive files.
* @hidden
*/
nativeSubtitles?: Boolean;
}
export interface BufferMediaTypeConfig {
/**
* The amount of data in seconds the player tries to buffer in advance. Default is `40`.
*
* For live streams the lowest value of playlist duration for HLS, `timeShiftBufferDepth` for DASH and
* this `targetLevel` value is used as a maximum value for the forward buffers.
*/
forwardduration?: number;
}
/**
* Configures different kinds of buffer settings for media types defined in {@link MediaType}.
*
* Example:
* ```js
* buffer: {
* [MediaType.Video]: {
* [BufferType.ForwardDuration]: 30,
* },
* [MediaType.Audio]: {
* [BufferType.ForwardDuration]: 50,
* },
* },
* ```
*/
export interface BufferConfig {
/**
* Configures various settings for the video buffers.
*/
video?: BufferMediaTypeConfig;
/**
* Configures various settings for the audio buffers.
*/
audio?: BufferMediaTypeConfig;
}
/**
* A map of query parameter names to values.
*
* Example:
* ```js
* const query_parameters = {
* name: 'value',
* 'another-name': 'another-value',
* // Empty values are allowed
* name3: '',
* // Names without values are also allowed
* name4: null,
* }
* ```
* The resulting query string of the example will be `name=value&another-name=another-value&name3=&name4`.
*/
export interface QueryParameters {
[name: string]: string;
}
/**
* A map of [[HttpRequestType]] to HTTP status codes.
* For the included request types, requests will not be retried if they return those codes.
*
* **The key must be a string belonging to [[HttpRequestType]]**
* @since 8.4
*
* Example:
* ```js
* disable_retry_for_response_status: {
* [HttpRequestType.MANIFEST_DASH]: [ 401 ]
* }
*```
*/
export interface ResponseStatusMap {
[name: string]: number[];
}
/**
* 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:
* ```js
* tweaks : {
* autoqualityswitching : true,
* max_buffer_level : 20,
* query_parameters : {
* key1: 'value1',
* key2: 'value2',
* mycustomname: 'another-value'
* }
* }
* ```
*/
export interface TweaksConfig {
/**
* Determines if the automatic quality switching is enabled on startup (`true`, default).
*/
autoqualityswitching?: boolean;
/**
* 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 {@link BufferConfig.targetLevel} instead.
*/
max_buffer_level?: 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.
*/
startup_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.
*/
restart_threshold?: number;
/**
* Enable or disable (`false`, default) hardware-supported video decoding for the Flash fallback. Enabling this
* might lead to decoding artefacts, but can improve performance.
*/
hwdecoding?: boolean;
/**
* 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:
* ```js
* 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`.
*/
query_parameters?: QueryParameters;
/**
* If enabled the native player used for HLS in Safari would fetch and parse the HLS playlist and trigger
* {@link Events.SegmentPlayback} events carrying segment-specific metadata like `#EXT-X-PROGRAM-DATE-TIME`
* if present in the manifest. 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
* an {@link PlayerEvent.Error} event if the download of a segment fails and the playback stalls. Default is `false`.
*/
native_hls_download_error_handling?: 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`.
*/
stop_download_on_pause?: boolean;
/**
* Sets the LOG_LEVEL of the player by calling {@link PlayerAPI.setLogLevel}.
*/
log_level?: LogLevel;
/**
* Sets the license server to the given URL if it is included in {@link PlayerAPI.getAvailableLicenseServers}.
* Default is the first entry of the available license servers.
*/
licenseServer?: string;
/**
* Sets the impression server to the given URL if it is included in {@link PlayerAPI.getAvailableImpressionServers}.
* Default is the first entry of the available impression servers.
*/
impressionServer?: string;
/**
* 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_audio_only_threshold_bitrate?: number;
/**
* TODO add description
* @hidden
*/
segmentLoader?: any;
/**
* TODO add description
* @hidden
*/
segmentLoaderArgs?: any;
/**
* Whether to use the file protocol or not. Used in combination with app_id. Default is false.
* @hidden
*/
file_protocol?: boolean;
/**
* @hidden
*/
app_id?: string;
/**
* 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
*/
adaptation_set_switching_without_supplemental_property?: 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
*/
ignore_mp4_edts_box?: boolean;
/**
* Disables grouping of audio renditions by name. With this enabled, every audio rendition will be a separate
* available audio (and not a quality)
* @hidden
*/
ignore_hls_audio_groups?: boolean;
/**
* 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:
* ```js
* disable_retry_for_response_status: {
* [HttpRequestType.MANIFEST_DASH]: [ 401 ]
* }
*```
*/
disable_retry_for_response_status?: ResponseStatusMap;
/**
* The number of segments at the start of the segment list that the player considers unsafe to request. E.g when set
* to 2 the earliest possible segment to seek/timeShift to would be the third segment in the list.
* The default value is 0, so the complete DVR window is used.
*/
live_segment_list_start_index_offset?: number;
/**
* Disables period switches on the subtitle handling, in case there are no discontinuities in the subtitle playlist
*/
disable_subtitle_period_switch?: 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.
*/
prevent_video_element_preloading?: boolean;
/**
* Defines the [scope]() of the `ServiceWorker` that is created in the `bitmovin-serviceworker-client.js` module.
* @since 8.13.0
*/
serviceworker_scope?: string;
}
/**
* Example:
* ```js
* cast : {
* enable : true,
* application_id : 'A12B45C6'
* }
* ```
*/
export interface CastConfig {
/**
* ChromeCast support is disabled (`false`) per default. To enable it, set this attribute to `true`.
*/
enable?: boolean;
/**
* The ChromeCast application ID retrieved from Google when a Cast receiver app is registered. To use
* ChromeCast with player version 6 an higher, it is not necessary to use this option. For versions
* pre v6, please use ‘121122A0’, or your dedicated ID, in case you want to use a custom ChromeCast
* receiver app.
*
* Starting with player 6, the application ID needs only be set if you want to use your own custom receiver app.
* By default, Bitmovin's Cast receiver app is used.
*/
application_id?: string;
/**
* A custom message namespace as defined in the Cast receiver app. To use ChromeCast, it is not necessary
* to use this option! This is only needed if one wants to create a custom ChromeCast receiver app.
*/
message_namespace?: string;
/**
* A URL to a CSS file the Chromecast receiver app loads. Can be used to style the receiver app.
* @since 7.1
*/
receiverStylesheetUrl?: string;
}
/**
* Example:
* ```js
* adaptation : {
* desktop: {
* bitrates: {
* minSelectableAudioBitrate: '128kbps',
* maxSelectableAudioBitrate: '320kbps',
* minSelectableVideoBitrate: '900kbps',
* maxSelectableVideoBitrate: Infinity
* }
* },
* mobile: {
* bitrates: {
* minSelectableAudioBitrate: 0,
* maxSelectableAudioBitrate: '256000bps',
* minSelectableVideoBitrate: 0,
* maxSelectableVideoBitrate: '2.5mbps'
* }
* }
* }
* ```
*/
export interface AdaptationConfig {
/**
* Limits the automatically selected quality to the player size, so the player won't select quality
* levels with a higher resolution than the video element. This is disabled (`false`) per default.
*/
limitToPlayerSize?: boolean;
/**
* The bitrate the player should start playback with. If this option doesn’t exist
* in the configuration, the player will try to find the best startup bitrate automatically.
*/
startupBitrate?: Bitrate;
/**
* The maximum bitrate the player should start playback with.
* Has no effect if {@link startupBitrate} is used.
*/
maxStartupBitrate?: Bitrate;
/**
* The player automatically cancels requests if it takes too long and retries in a lower quality (default, `false`).
* This behavior can be disabled by setting this option to `true`.
*/
disableDownloadCancelling?: boolean;
/**
* Specifies whether the player preloads the content (default: `true` for VOD, `false` for live streams) or not.
*/
preload?: boolean;
/**
* Specifies whether qualities that must not be switched to should be removed when parsing the manifest or
* not. Qualities which must not be switched to can be specified by {@link bitrates} or {@link resolution}.
* Default is false.
*/
exclude?: boolean;
/**
* Lower and upper bitrate boundaries to limit qualities.
*/
bitrates?: BitrateLimitationConfig;
/**
* Lower and upper resolution boundaries. Use `0` for no limitation for minimum selectable width/height and
* `Infinity` for no limitation for maximum selectable width/height.
*/
resolution?: VideoSizeLimitationConfig;
/**
* The maximum PSNR difference that is allowed for chosen representation when Quality Optimized Streaming Data
* is present.
* @hidden
*/
qualityThreshold?: number;
/**
* The maximum PSNR value above which it doesn't make much sense. Netflix has said that scores under 35 dB will show
* encoding artifacts, while scores over 45 dB produce no perceptible quality improvements.
* @hidden
*/
qualityUpperThreshold?: number;
/**
* Defines the adaptation logic. Can be either 'v1' or 'v2' (default).
* @hidden
*/
logic?: string;
/**
* A callback function to customize the player's adaptation logic that is called before the player tries to download
* a new video segment.
*
* Example:
* ```js
* const conf = {
* ...
* adaptation: {
* desktop: {
* onVideoAdaptation: (data) => {
* // Do your custom logic
* return newRepresentationId;
* }
* },
* mobile: {
* onVideoAdaptation: (data) => {
* // Do your custom logic
* return newRepresentationId;
* }
* },
* }
* };
* ```
*
* To simply restrict video qualities to the current video player size, use {@link limitToPlayerSize}.
*
* @param data An object carrying the <code>suggested</code> attribute, holding the suggested representation/quality
* ID the player would select
* @return A valid representation/quality ID which the player should use, based on your custom logic (either
* <code>data.suggested</code> to switch to the player's suggested quality, or a {@link VideoQuality.id})
* @see {@link PlayerAPI.getAvailableVideoQualities} to get a list of all available video qualities
*/
onVideoAdaptation?: (data: VideoAdaptationData) => string;
/**
* A callback function to customize the player's adaptation logic that is called before the player tries to download
* a new audio segment.
*
* Example:
* ```js
* const conf = {
* ...
* adaptation: {
* desktop: {
* onAudioAdaptation: (data) => {
* // Do your custom logic
* return newRepresentationId;
* }
* },
* mobile: {
* onAudioAdaptation: (data) => {
* // Do your custom logic
* return newRepresentationId;
* }
* },
* }
* };
* ```
*
* @param data An object carrying the <code>suggested</code> attribute, holding the suggested representation/quality
* ID the player would select
* @return A valid representation/quality ID which the player should use, based on your custom logic (either
* <code>data.suggested</code> to switch to the player's suggested quality, or a {@link AudioQuality.id})
* @see {@link PlayerAPI.getAvailableAudioQualities} to get a list of all available audio qualities
*/
onAudioAdaptation?: (data: AudioAdaptationData) => string;
}
interface AdaptationData {
/**
* The ID of the representation that the player selected, which is the same ID as returned through the
* {@link AudioQuality} and {@link VideoQuality} objects from {@link PlayerAPI.getAvailableAudioQualities} and
* {@link PlayerAPI.getAvailableVideoQualities}.
*/
suggested: string;
}
export interface VideoAdaptationData extends AdaptationData {
}
export interface AudioAdaptationData extends AdaptationData {
}
export interface BitrateLimitationConfig {
/**
* Lower bitrate boundary for audio qualities. All qualities below this threshold will not be selected by
* the ABR logic. These qualities are still available for manual quality selection unless the {@link exclude}
* flag is set to `true`.
* Can be set to `0` for no limitation.
*/
minSelectableAudioBitrate?: Bitrate;
/**
* Upper bitrate boundary for audio qualities. All qualities above this threshold will not be selected by
* the ABR logic. These qualities are still available for manual quality selection unless the {@link exclude}
* flag is set to `true`.
* Can be set to `Infinity` for no limitation.
*/
maxSelectableAudioBitrate?: Bitrate;
/**
* Lower bitrate boundaries for video qualities. All qualities below this threshold will not be selected by
* the ABR logic. These qualities are still available for manual quality selection unless the {@link exclude}
* flag is set to `true`.
* Can be set to `0` for no limitation.
*/
minSelectableVideoBitrate?: Bitrate;
/**
* Upper bitrate boundary for video qualities. All qualities above this threshold will not be selected by
* the ABR logic. These qualities are still available for manual quality selection unless the {@link exclude}
* flag is set to `true`.
* Can be set to `Infinity` for no limitation.
*/
maxSelectableVideoBitrate?: Bitrate;
}
export interface VideoSizeLimitationConfig {
/**
* Lower video height boundary for video qualities. All qualities below this threshold will not be selected by
* the ABR logic. These qualities are still available for manual quality selection unless the
* {@link AdaptationConfig.exclude} flag is set to `true`.
* Can be set to `0` for no limitation.
*/
minSelectableVideoHeight?: number;
/**
* Upper video height boundary for video qualities. All qualities above this threshold will not be selected by
* the ABR logic. These qualities are still available for manual quality selection unless the
* {@link AdaptationConfig.exclude} flag is set to `true`.
* Can be set to `0` for no limitation.
*/
maxSelectableVideoHeight?: number;
/**
* Lower video width boundary for video qualities. All qualities below this threshold will not be selected by
* the ABR logic. These qualities are still available for manual quality selection unless the
* {@link AdaptationConfig.exclude} flag is set to `true`.
* Can be set to `0` for no limitation.
*/
minSelectableVideoWidth?: number;
/**
* Upper video width boundary for video qualities. All qualities above this threshold will not be selected by
* the ABR logic. These qualities are still available for manual quality selection unless the
* {@link AdaptationConfig.exclude} flag is set to `true`.
* Can be set to `0` for no limitation.
*/
maxSelectableVideoWidth?: number;
}
/**
* Specifies a bitrate either as number in bits per second (bps) or as a string with the unit, such as `mbps`
* (megabits per second),
* `kbps` (kilobits per second) or `bps` (bits per second). Example: `'5000kbps'`
*/
export declare type Bitrate = number | string;
/**
* Adaptation configurations for different platforms. Most options are not applicable for the `native` and
* `native-flash` player technologies due to technical limitations.
*/
export interface AdaptationPlatformConfig extends AdaptationConfig {
desktop?: AdaptationConfig;
mobile?: AdaptationConfig;
}
/**
* Example:
* ```js
* location : {
* flash: 'MY_FLASH_FOLDER/my_bitmovinplayer.swf',
* 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'
* }
* ```
*/
export interface LocationConfig {
/**
* Specifies the path, relative or absolute, to the file containing the Flash fallback.
*
* Default name: `bitmovinplayer.swf`
*/
flash?: string;
/**
* Specifies the path, relative or absolute, to the file containing the Flash-native fallback.
*
* Default name: `bitmovinplayer.swf`
*/
flash_native?: string;
/**
* Specifies the path, relative or absolute, to the [Bitmovin Player UI](
* https://github.com/bitmovin/bitmovin-player-ui/)/skin JavaScript file.
*
* Default name: `bitmovinplayer-ui.js`
*/
ui?: string;
/**
* Specifies the path, relative or absolute, to the style sheet of the [Bitmovin Player UI](
* https://github.com/bitmovin/bitmovin-player-ui/)/skin.
*
* Default name: `bitmovinplayer-ui.css`
*/
ui_css?: 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
*/
cast?: string;
/**
* The URL of the Google IMA Framework.
*
* Default URL: https://imasdk.googleapis.com/js/sdkloader/ima3.js
*
* @deprecated Use {@link ImaAdvertisingConfig.sdkUrl} instead.
*/
google_ima?: string;
/**
* Specifies the path, relative or absolute, to the service worker JS file.
*
* 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
*
* Default URL: ``
*
* @hidden not implemented yet
*/
serviceworker?: string;
}
export interface LogsConfig {
/**
* Enable (`true`, default) or disable the Bitmovin credits in the browser's console.
*/
bitmovin?: boolean;
/**
* 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`
*/
level?: LogLevel;
}
export interface LicensingConfig {
/**
* Can be used to set the delay (in milliseconds) until the licensing call is issued.
* Maximum value is 30000 (30 seconds).
*/
delay?: number;
}
/**
* A mapping of {@link PlayerEvent} values to event handler callback functions.
*
* Events can also be dynamically added and removed through {@link PlayerAPI.on} and {@link PlayerAPI.off}.
*
* Example:
* ```js
* events : {
* [PlayerEvent.SourceLoaded]: (data) => {
* console.log('version: ' + this.getVersion() + ', onReady Event data: ', data);
* },
* [PlayerEvent.Play]: (data) => {
* // do awesome stuff
* },
* [PlayerEvent.Error]: (data) => {
* console.error('An error occurred:', data);
* }
* }
* ```
*/
export interface EventConfig {
[event: string]: PlayerEventCallback;
}
export interface RemoteControlCustomReceiverConfig {
/**
* Arbitrary configuration values that are sent to the remote control receiver.
*/
[key: string]: string;
/**
* A URL to a stylesheet that customizes the receiver UI style.
*/
receiverStylesheetUrl?: string;
}
/**
* Configuration interface for remote control of Google Cast (e.g. Chromecast) receivers.
*
* Example (enable casting with Bitmovin receiver app and custom style):
* ```js
* {
* type: 'googlecast',
* customReceiverConfig: {
* receiverStylesheetUrl: 'https://mycdn.com/mycustomreceiverstyle.css',
* },
* }
* ```
*
* Example (custom receiver):
* ```js
* {
* type: 'googlecast',
* receiverApplicationId: '1234ABCD',
* customReceiverConfig: {
* customPropertyName: 'customValue',
* },
* }
* ```
*
*/
export interface GoogleCastRemoteControlConfig extends InternalGoogleCastRemoteControlConfig {
type: 'googlecast';
}
/**
* Configuration interface for WebSocket-based player remote control.
* Requires a running WebSocket server available at
* https://github.com/bitmovin/bitmovin-player-remote-websocketserver.
*
* Example:
* ```js
* {
* type: 'websocket',
* url: 'ws://your-server-ip:29100',
* customReceiverConfig: {
* receiverStylesheetUrl: 'https://mycdn.com/mycustomreceiverstyle.css',
* },
* }
* ```
*/
export interface WebSocketRemoteControlConfig extends InternalWebSocketRemoteControlConfig {
type: 'websocket';
}
/**
* Mandatory configuration for {@link PlayerType} `native-flash`.
* This player tech won't work without a valid authorization token.
*/
export interface NativeFlashConfig {
/**
* URL to an Adobe authorization token. The player SWF file needs to be loaded from a domain whitelisted by the
* token.
*/
tokenURL: string;
/**
* The type of the provided {@link tokenURL}. `swf` can contain multiple tokens while `dat` is only one specific
* token. `swf` is the default value.
*/
tokenType?: 'swf' | 'dat';
/**
* The list of available wildcard domains the token specified by {@link tokenURL} is valid for. Only needed if
* wildcard domains are included and the {@link tokenType} is `swf`.
*/
wildcardDomains?: string[];
}
/**
* Configuration interface for properties used for live streams.
*
* Example:
* ```js
* {
* synchronization: [{
* method: LiveSynchronizationMethod.HttpHead,
* serverUrl: 'http://time.akamai.com',
* }],
* }
* ```
*/
export interface LiveConfig {
synchronization?: SynchronizationConfigEntry[];
lowLatency?: LowLatencyConfig;
}
/**
* Method to be used for time server response parsing
*/
export declare enum LiveSynchronizationMethod {
/**
* The time information is in the response HTTP 'Date' header.
*/
HttpHead = "httphead",
/**
* The time information is in the response body in xs:date format.
*/
HttpXsDate = "httpxsdate",
/**
* The time information is in the response body a ISO 8601 timestamp.
*/
HttpIso = "httpiso"
}
export interface SynchronizationConfigEntry {
/**
* Method how to extract the time information from the time server response.
*/
method: LiveSynchronizationMethod;
/**
* URL of the time server
*/
serverUrl: string;
}
/**
* Placeholder type for the Bitmovin Player UI's UIConfig.
* https://github.com/bitmovin/bitmovin-player-ui
*/
export declare type UIConfig = any;
/**
* Configuration for live streams to maintain a certain live latency.
*/
export interface LowLatencyConfig {
/**
* The target latency in seconds, i.e. the distance from the stream's live edge to be maintained by the player during
* playback.
*/
targetLatency?: number;
/**
* Configuration defining catchup to be done if the player exceeds the target latency.
*/
catchup?: LowLatencySyncConfig;
/**
* Configuration defining fallback to be done if the player falls below the target latency.
*/
fallback?: LowLatencySyncConfig;
}
/**
* Configuration specifying live latency synchronization (i.e. maintaining latency by catchup/fallback)
*/
export interface LowLatencySyncConfig {
/**
* Allowed deviation from target latency before catchup/fallback by changing the playback speed is done.
*/
playbackRateThreshold?: number;
/**
* Allowed deviation from target latency before catchup/fallback by seeking is done.
*/
seekThreshold?: number;
/**
* Playback speed to be used for catchup/fallback.
*/
playbackRate?: number;
}
export interface PlayerConfig {
/**
* 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.
*/
key: string;
/**
* Playback config settings.
*/
playback?: PlaybackConfig;
/**
* UX/UI config settings.
*/
style?: StyleConfig;
/**
* A list of callback functions for events. Events can also be dynamically added and removed through
* {@link PlayerAPI.on} and {@link PlayerAPI.off}.
*
* Example:
* ```js
* 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);
* }
* }
* ```
*/
events?: EventConfig;
/**
* Configures various buffer settings.
*/
buffer?: BufferConfig;
/**
* Tweaks. Use these values only if you know what you are doing.
*/
tweaks?: TweaksConfig;
/**
* Google Cast configuration.
* @deprecated Use {@link remotecontrol} with {@link GoogleCastRemoteControlConfig} instead.
*/
cast?: CastConfig;
/**
* Configures the adaptation logic.
*/
adaptation?: AdaptationPlatformConfig;
/**
* 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.
*/
advertising?: AdvertisingConfig;
/**
* This can be used to specify custom paths to bitmovinplayer.swf, bitmovinplayer-core.min.js,
* and bitmovinplayer-core.min.css instead of having all files in the same folder.
*/
location?: LocationConfig;
/**
* Can be use to fine tune logging of the player.
*/
logs?: LogsConfig;
/**
* Licensing configuration.
*/
licensing?: LicensingConfig;
/**
* Network configuration.
*/
network?: NetworkConfig;
/**
* Remote control configuration (e.g. Chromecast)
* @since 7.1
*/
remotecontrol?: GoogleCastRemoteControlConfig | WebSocketRemoteControlConfig;
/**
* Native-Flash player configuration.
* @since 8.0
*/
nativeflash?: NativeFlashConfig;
/**
* UI configuration that is passed to the Bitmovin Player UI if the UI module is loaded. Can also be used