Skip to content

Module: src/streaming/Dash

The Dash component integrates dash.js into the player's plugin architecture, allowing DASH streaming with optional DRM (Widevine/PlayReady). Supports Subtitles, Quality and Language selection.

Version
1.0.0
Author
Frank Kudermann - alphanull
License
MIT
Requires
ExtendedMediaError
Source
Dash.js, line 15

Constructor

new Dash(player, mediaComponent, apiKey)

Creates an instance of the Dash plugin.

Parameters:
Name Type Description
player Player

Reference to the player instance.
mediaComponent Media

Reference to the engine (video) instance.
apiKey symbol

Token for extended access to the player API.

Members

The dash configuration, containing debug and optional DRM details.

Properties
Name Type Attributes Default Description
lazyLoadLib boolean optional true

If true, the Dash.js library is only loaded when loading the first media item.
libUrl string optional

Custom URL for the Dash.js library. Defaults to CDN URL if not specified.
debug Object | boolean optional false

Debug settings or boolean to enable debug logs.

Properties
Name Type Attributes Description
enabled boolean optional

Whether debugging is enabled.
drm boolean optional

Whether to log DRM-specific events if dash protection is present.
level string optional

DashJs debug level (e.g., LOG_LEVEL_WARNING).
Type
Object
Source
Dash.js, line 27

Reference to the main player instance.

Type
Player
Source
Dash.js, line 41

Subscriptions to various player events that we handle specifically for dash.

Type
Array<number>
Source
Dash.js, line 47

Secret key only known to the player instance and initialized components. Used to be able to restrict access to API methods in conjunction with secure mode.

Type
symbol
Source
Dash.js, line 54

Reference to the engine (Video) instance.

Type
Media
Source
Dash.js, line 60

Reference to the Dash MediaPlayer Instance.

Type
Object
Source
Dash.js, line 66

Holds currently available audio and video tracks.

Type
Object
Source
Dash.js, line 72

Reference to the Async Task instance. Used to handle async tasks, which can be cancelled, resolved or rejected.

Type
AsyncTask
Source
Dash.js, line 78

Holds metadata information provided by media.load and loaded metadata.

Type
Media~metaData
Source
Dash.js, line 84

Promise awaiting the loading of the dash lib.

Type
Promise
Source
Dash.js, line 90

The list of protection events from dash.js (v5 or vX).

Type
Array<string>
Source
Dash.js, line 704

Methods

canPlay(metaData) → 'probably'|'maybe'|''

Tells whether this plugin can handle the given mimeType and optional DRM system.

Parameters:
Name Type Description
metaData Media~metaData

The data to test.

Parameters:
Name Type Attributes Description
mimeType string

The mime type to test.
drmSystem string optional

Optional DRM system info.
Returns

Indicates if stream can be played.

Type 'probably' | 'maybe' | ''
Source
Dash.js, line 132

async load(metaData, optionsopt) → Promise|undefined

Initializes the dash.js MediaPlayer with the given source.

Parameters:
Name Type Attributes Description
metaData Media~metaData

Source Object (currentSource).

Parameters:
Name Type Description
src string

Actual HLS URL to load.
options Object optional

Additional options.

Parameters:
Name Type Attributes Description
loadTask AsyncTask optional

If a source task instance is provided, handle errors using this object.
Returns

If a source task instance is provided, returns a promise that rejects with a resulting media error.

Type Promise | undefined
Throws

If drm scheme is unknown.

Type Error
Source
Dash.js, line 156

private #loadDashJs() → Promise<void>

Loads dash.js via CDN if not present. Ensures only one load attempt per instance.

Returns
Type Promise<void>
Source
Dash.js, line 249

onLoaded(metaData)

Called by the media component when metadata has loaded, but before the media/ready event has been sent. Allows the plugin to add additional metadata to the mediaSource object.

Parameters:
Name Type Description
metaData Media~metaData

The updated meta data object.
Source
Dash.js, line 303

private #onMetaDataLoaded()

Handler for dash.js PLAYBACK_METADATA_LOADED event. Sets up track lists, languages, qualities.

Fires
quality/update
language/update
subtitles/update
Listens
dashjs.MediaPlayer.events.event:PLAYBACK_METADATA_LOADED
Source
Dash.js, line 366

private #onSubtitlesSelected(selected)

Handler for 'subtitles/selected' event. Matches the track to dash, calls dash.setTextTrack.

Parameters:
Name Type Description
selected Object

Object containing information about the selected Subtitle.

Parameters:
Name Type Description
language string

The newly selected subtitle language code.
Listens
subtitles/selected
Source
Dash.js, line 385

private #onLanguageSelected(langObj)

Handler for 'language/selected' event. Chooses the matching audio track in dash.

Parameters:
Name Type Description
langObj Language~langObj

Object containing selected language information.

Parameters:
Name Type Description
lang string

The newly selected audio language code.
Listens
language/selected
Source
Dash.js, line 401

private #onQualitySelected(selected)

Handler for 'quality/selected' event. If the user picks a specific resolution, use it; else 'auto'.

Parameters:
Name Type Description
selected string

The chosen resolution in the format 'p', or unknown => auto.
Listens
quality/selected
Source
Dash.js, line 450

private #onQualityResize(size)

Handler for 'quality/resize' event. Caps the max bitrate if display size is small.

Parameters:
Name Type Description
size Object

Object containing size information.

Parameters:
Name Type Description
height number

The new container height in px.
Listens
quality/resize
Source
Dash.js, line 481

private #onTrackChangeRendered(mediaInfo)

Handler for dash.js TRACK_CHANGE_RENDERED event. If it's audio, update the player's language state.

Parameters:
Name Type Description
mediaInfo Object

The media info object with the changed settings.

Parameters:
Name Type Description
mediaType string

The media type of the changed object.
newMediaInfo Object

The new media info with language information.
Fires
language/active
Listens
dashjs.MediaPlayer.events.event:TRACK_CHANGE_RENDERED
Source
Dash.js, line 511

private #onQualityChangeRendered(mediaInfo)

Handler for dash.js QUALITY_CHANGE_RENDERED event. Publishes 'quality/active' with the current resolution.

Parameters:
Name Type Description
mediaInfo Object

The media info object with the changed settings.
Fires
quality/active
Listens
dashjs.MediaPlayer.events.event:QUALITY_CHANGE_RENDERED
Source
Dash.js, line 524

private #onDrmKeyStatus(event)

Handler for dash.js 'INTERNAL_KEY_STATUS_CHANGED' event. If a key is restricted or expired, send a media error.

Parameters:
Name Type Description
event Object

The event coming from dash.
Listens
dashjs.MediaPlayer.events.event:INTERNAL_KEY_STATUS_CHANGED
Source
Dash.js, line 554

private #onDashError(event)

Handler for dash.js ERROR event. Maps dash error codes to simulated media errors, publishes 'media/error'.

Parameters:
Name Type Description
event Object

The dahs event object.

Parameters:
Name Type Description
error Object

The event error code.
Fires
media/error
Source
Dash.js, line 568

private #onProtectionEvent(event)

Handler for dash protection events if debug is enabled.

Parameters:
Name Type Description
event Object

Event data from dash.js protection.
Source
Dash.js, line 629

private #onDashEvent(event)

Generic handler for dash.js events when debug mode is enabled. Filters out noisy or frequent events and logs others to the console. This helps with development and troubleshooting by surfacing meaningful events only.

Parameters:
Name Type Description
event Object

The event object emitted by dash.js.

Parameters:
Name Type Description
type string

The type name of the dash event.
Source
Dash.js, line 642

private #removeDash()

Handler for removing dash when 'data/ready' triggers a new media load. Cleans up subscriptions and dash instance.

Listens
data/ready
Source
Dash.js, line 654

destroy()

This method removes all events, subscriptions and DOM nodes created by this component.

Source
Dash.js, line 688