> ## Documentation Index
> Fetch the complete documentation index at: https://developer.bitmovin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Source Configuration

Configure media sources, DRM, and progressive streams

## SourceConfig

> Interface

The source object is passed into [load](https://developer.bitmovin.com/playback/reference/web-sdk-player-api#load) to load a new source.

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

Stream format selection priority:

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

To override automatic selection, use [preferredTech](https://developer.bitmovin.com/playback/reference/web-sdk-player-config#preferredtech):

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

**`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',
    id: 'track-0',
    lang: 'en'
  }],
  thumbnailTrack: {
    url: 'http://path/to/thumbnail/vtt/file.vtt',
  },
  drm: {
    widevine: {
      LA_URL: 'https://mywidevine.licenseserver.com/'
    },
    playready: {
      LA_URL: 'https://myplayready.licenseserver.com/'
    }
  },
  labeling: {
    hls: {
      qualities: (quality) => {
        return quality.height + 'p';
      }
    },
    dash: {
      qualities: (quality) => {
        return quality.height + 'p';
      }
    }
  }
});
```

## Properties

### analytics

• `Optional` **analytics**: [`AnalyticsConfig`](https://developer.bitmovin.com/playback/reference/web-sdk-analytics#analyticsconfig)

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

***

### dash

• `Optional` **dash**: `string`

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

***

### description

• `Optional` **description**: `string`

The description of the video source.

***

### drm

• `Optional` **drm**: [`DRMConfig`](https://developer.bitmovin.com/playback/reference/web-sdk-drm#drmconfig)

The DRM object should be included into the source object.

***

### hls

• `Optional` **hls**: `string`

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

***

### labeling

• `Optional` **labeling**: [`SourceLabelingStreamTypeConfig`](https://developer.bitmovin.com/playback/reference/web-sdk-source-config#sourcelabelingstreamtypeconfig)

Labeling config for the different stream types.

***

### live

• `Optional` **live**: [`LiveConfigAtSourceLevel`](https://developer.bitmovin.com/playback/reference/web-sdk-source-config#liveconfigatsourcelevel)

[`LiveConfig`](https://developer.bitmovin.com/playback/reference/web-sdk-player-config#liveconfig) at source level.

Note: Only certain parts of the [`LiveConfig`](https://developer.bitmovin.com/playback/reference/web-sdk-player-config#liveconfig) are supported here at this time.

Any values defined here at source level will override values of a [config at the player level](https://developer.bitmovin.com/playback/reference/web-sdk-player-config#live) if present.

**Since:** 8.176.0

***

### metadata

• `Optional` **metadata**: `Object`

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

#### Index signature

▪ \[key: `string`]: `string`

***

### options

• `Optional` **options**: [`SourceConfigOptions`](https://developer.bitmovin.com/playback/reference/web-sdk-source-config#sourceconfigoptions)

An object specifying advanced source specific options.

***

### poster

• `Optional` **poster**: `string`

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

***

### progressive

• `Optional` **progressive**: `string` | [`ProgressiveSourceConfig`](https://developer.bitmovin.com/playback/reference/web-sdk-source-config#progressivesourceconfig)\[]

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

***

### smooth

• `Optional` **smooth**: `string`

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

***

### subtitleTracks

• `Optional` **subtitleTracks**: [`SubtitleTrack`](https://developer.bitmovin.com/playback/reference/web-sdk-subtitles#subtitletrack)\[]

An array of external subtitle tracks.

***

### thumbnailTrack

• `Optional` **thumbnailTrack**: [`ThumbnailTrack`](https://developer.bitmovin.com/playback/reference/web-sdk-source-config#thumbnailtrack)

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

***

### title

• `Optional` **title**: `string`

The title of the video source.

***

### vr

• `Optional` **vr**: [`VRConfig`](https://developer.bitmovin.com/playback/reference/web-sdk-vr#vrconfig)

Configuration for VR and omnidirectional (360°) video.

***

### whep

• `Optional` **whep**: `string`

An URL pointing to a WHEP endpoint.

***

## SourceLabelingConfig

> Interface

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

## Properties

### qualities

• `Optional` **qualities**: (`quality`: [`QualityMetadata`](https://developer.bitmovin.com/playback/reference/web-sdk-player-api#qualitymetadata)) => `string`

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

#### Type declaration

▸ (`quality`): `string`

##### Parameters

| Name      | Type                                                        | Description                                                                     |
| :-------- | :---------------------------------------------------------- | :------------------------------------------------------------------------------ |
| `quality` | [`QualityMetadata`](https://developer.bitmovin.com/playback/reference/web-sdk-player-api#qualitymetadata) | Object with metadata about the quality for which the label should be generated. |

##### Returns

`string`

***

### subtitles

• `Optional` **subtitles**: (`subtitle`: [`SubtitleTrack`](https://developer.bitmovin.com/playback/reference/web-sdk-subtitles#subtitletrack)) => `string`

A function that generates a label for a subtitle.

#### Type declaration

▸ (`subtitle`): `string`

##### Parameters

| Name       | Type                                                   | Description                                           |
| :--------- | :----------------------------------------------------- | :---------------------------------------------------- |
| `subtitle` | [`SubtitleTrack`](https://developer.bitmovin.com/playback/reference/web-sdk-subtitles#subtitletrack) | The subtitle for which the label should be generated. |

##### Returns

`string`

***

### tracks

• `Optional` **tracks**: (`track`: [`TrackMetadata`](https://developer.bitmovin.com/playback/reference/web-sdk-player-api#trackmetadata)) => `string`

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

#### Type declaration

▸ (`track`): `string`

##### Parameters

| Name    | Type                                                    | Description                                                                                                                                                 |
| :------ | :------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `track` | [`TrackMetadata`](https://developer.bitmovin.com/playback/reference/web-sdk-player-api#trackmetadata) | Object with metadata about the track for which the label should be generated. The id field is populated when used for HLS, the mimeType when used for DASH. |

##### Returns

`string`

***

## ProgressiveSourceConfig

> Interface

## Properties

### bitrate

• `Optional` **bitrate**: `number`

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

***

### label

• `Optional` **label**: `string`

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

***

### preferred

• `Optional` **preferred**: `boolean`

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

***

### type

• `Optional` **type**: `string`

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

***

### url

• **url**: `string`

The URL to the progressive video file.

***

## ThumbnailTrack

> Interface

## Properties

### url

• **url**: `string`

The URL to the associated file.

***

## SourceConfigOptions

> Interface

## Properties

### audioCodecPriority

• `Optional` **audioCodecPriority**: `string`\[]

Specify the priority of audio codecs for this source. If more than one audio codec is available this order will
be respected while finding a codec which is supported by the current browser. Default is
[audioCodecPriority](https://developer.bitmovin.com/playback/reference/web-sdk-player-config#audiocodecpriority)

**Since:** 7.6

***

### dashManifestWithCredentials

• `Optional` **dashManifestWithCredentials**: `boolean`

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

***

### dashWithCredentials

• `Optional` **dashWithCredentials**: `boolean`

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

***

### headers

• `Optional` **headers**: [`HttpHeaders`](https://developer.bitmovin.com/playback/reference/web-sdk-network#httpheaders)

***

### hlsManifestWithCredentials

• `Optional` **hlsManifestWithCredentials**: `boolean`

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

***

### hlsWithCredentials

• `Optional` **hlsWithCredentials**: `boolean`

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

***

### manifestWithCredentials

• `Optional` **manifestWithCredentials**: `boolean`

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

***

### persistentPoster

• `Optional` **persistentPoster**: `boolean`

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

***

### shouldRecreateSourceBuffersOnPeriodSwitch

• `Optional` **shouldRecreateSourceBuffersOnPeriodSwitch**: (`sourcePeriodInfo`: [`PeriodInformation`](https://developer.bitmovin.com/playback/reference/web-sdk-player-api#periodinformation), `targetPeriodInfo`: [`PeriodInformation`](https://developer.bitmovin.com/playback/reference/web-sdk-player-api#periodinformation), `suggestion`: `boolean`) => `boolean`

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

The downside of SourceBuffer recreation is a prolonged transition time with possible black frames between the
periods. The upside is increased stability: not recreating SourceBuffers may result in
`PLAYBACK_VIDEO_DECODING_ERROR`, or a stuck video element on many platforms. This also depends on the playing
content itself.

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

**Since:** 8.87.0

#### Type declaration

▸ (`sourcePeriodInfo`, `targetPeriodInfo`, `suggestion`): `boolean`

##### Parameters

| Name               | Type                                                            | Description                                                                               |
| :----------------- | :-------------------------------------------------------------- | :---------------------------------------------------------------------------------------- |
| `sourcePeriodInfo` | [`PeriodInformation`](https://developer.bitmovin.com/playback/reference/web-sdk-player-api#periodinformation) | The information of the period the player is switching away from.                          |
| `targetPeriodInfo` | [`PeriodInformation`](https://developer.bitmovin.com/playback/reference/web-sdk-player-api#periodinformation) | The information of the period the player is switching into.                               |
| `suggestion`       | `boolean`                                                       | The default behavior suggested by the player, `true` for recreation, `false` for reusing. |

##### Returns

`boolean`

***

### startOffset

• `Optional` **startOffset**: `number`

The position where the stream should be started. Number can be positive or negative depending on the used
[TimelineReferencePoint](https://developer.bitmovin.com/playback/reference/web-sdk-player-api#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

***

### startOffsetTimelineReference

• `Optional` **startOffsetTimelineReference**: [`TimelineReferencePoint`](https://developer.bitmovin.com/playback/reference/web-sdk-player-api#timelinereferencepoint)

Timeline reference point to calculate [startOffset](https://developer.bitmovin.com/playback/reference/web-sdk-source-config#startoffset) from.
Default for live: `TimelineReferencePoint.End`
Default for VOD: `TimelineReferencePoint.Start`

***

### startTime

• `Optional` **startTime**: `number`

The position in fractional seconds to start playback from.

**Since:** 7.1

**Deprecated:** use StartOffset instead

***

### videoCodecPriority

• `Optional` **videoCodecPriority**: `string`\[]

Specify the priority of video codecs for this source. If more than one video codec is available this order will
be respected while finding a codec which is supported by the current browser. Default is
[videoCodecPriority](https://developer.bitmovin.com/playback/reference/web-sdk-player-config#videocodecpriority)

**Since:** 7.6

***

### withCredentials

• `Optional` **withCredentials**: `boolean`

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

***

## SourceLabelingStreamTypeConfig

> Interface

Labeling config for the different stream types.

## Properties

### dash

• `Optional` **dash**: [`SourceLabelingConfig`](https://developer.bitmovin.com/playback/reference/web-sdk-source-config#sourcelabelingconfig)

Labeling functions for DASH sources.

***

### hls

• `Optional` **hls**: [`SourceLabelingConfig`](https://developer.bitmovin.com/playback/reference/web-sdk-source-config#sourcelabelingconfig)

Labeling functions for HLS sources.

***

## LiveConfigAtSourceLevel

> Interface

Partial [`LiveConfig`](https://developer.bitmovin.com/playback/reference/web-sdk-player-config#liveconfig) for usage at the [source level](https://developer.bitmovin.com/playback/reference/web-sdk-source-config#live).

## Hierarchy

* `Pick`<[`LiveConfig`](https://developer.bitmovin.com/playback/reference/web-sdk-player-config#liveconfig), `"lowLatency"` | `"synchronization"`>

  ↳ **`LiveConfigAtSourceLevel`**

## Properties

### lowLatency

• `Optional` **lowLatency**: [`LowLatencyConfig`](https://developer.bitmovin.com/playback/reference/web-sdk-player-config#lowlatencyconfig)

Configuration to enable maintaining a desired live latency.

#### Inherited from

Pick.lowLatency

***

### synchronization

• `Optional` **synchronization**: [`SynchronizationConfigEntry`](https://developer.bitmovin.com/playback/reference/web-sdk-player-config#synchronizationconfigentry)\[]

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

#### Inherited from

Pick.synchronization

***

## StreamType

> Enum

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

## Enumeration Members

### Dash

• **Dash** = `"dash"`

***

### Hls

• **Hls** = `"hls"`

***

### Progressive

• **Progressive** = `"progressive"`

***

### Smooth

• **Smooth** = `"smooth"`

***

### Unknown

• **Unknown** = `"unknown"`

***

### Whep

• **Whep** = `"whep"`