Skip to content

Module: src/settings/Quality

The Quality component provides a UI for changing video quality, either automatically or manually through a menu in the settings popup. If multiple resolutions are available, it can adapt the stream to display size changes and downgrade quality automatically when stalling occurs. It also reacts to language-based quality updates and supports advanced adaptive streaming logic.

Version
1.0.0
Author
Frank Kudermann - alphanull
License
MIT
Requires
Menu
Source
Quality.js, line 13

Constructor

new Quality(player, parent, optionsopt)

Creates an instance of the Quality component.

Parameters:
Name Type Attributes Description
player Player

Reference to the media player instance.
parent Popup

Reference to the parent instance (In this case the settings popup).
options Object optional

Additional options.

Parameters:
Name Type Attributes Description
apiKey symbol optional

Token for extended access to the player API.

Members

Configuration options for the Quality component.

Properties
Name Type Attributes Default Description
adaptToSize boolean optional true

If true, adapt quality to display size changes.
useDeviceRatio boolean optional true

If true, use devicePixelRatio for display-based quality decisions.
downgradeIfStalled boolean optional true

If true, automatically downgrade quality after a stalling delay.
downgradeDelay number optional 10

Time in seconds to wait before lowering quality after a stall.
resizeDelay number optional 2

Time in seconds to delay resize-based quality logic, so resizes do not immediately affect quality selection.
showPlaceholder boolean optional false

If enabled, display a 'not available' placeholder if no qualities are available, otherwise completely hide the menu.
Type
Object
Source
Quality.js, line 24

Reference to the main player instance.

Type
Player
Source
Quality.js, line 37

Reference to the parent instance.

Type
Controller
Source
Quality.js, line 43

Holds tokens of subscriptions to player events, for later unsubscribe.

Type
Array<number>
Source
Quality.js, line 49

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
Quality.js, line 56

Whether a quality change has been initiated from an external component Used by Dash and Hls.

Type
boolean
Source
Quality.js, line 69

The currently active source object.

Type
Media~metaData
Source
Quality.js, line 75

List of available qualities (could be numeric or textual, but can also be "null" which means "auto").

Type
Array<(null|number|string)>
Source
Quality.js, line 81

The currently selected quality, or null for "auto".

Type
string | number
Source
Quality.js, line 87

Timer ID for stalling-based quality downgrade.

Type
number
Source
Quality.js, line 93

Timer ID for size-based adaptation checks.

Type
number
Source
Quality.js, line 99

Methods

private #onDataSource(metaData)

Called when a media source has been selected.

Parameters:
Name Type Description
metaData Media~metaData

The new media item data.
Listens
data/source
Source
Quality.js, line 153

private #onDataReady(mediaItem)

Called when player data is ready, or when a "quality/language/refresh" event arrives. Collects the available quality levels from the stream data and sets up the menu.

Parameters:
Name Type Description
mediaItem Data~mediaItem

Object containing media info.
Listens
data/ready
quality/language/refresh
Source
Quality.js, line 166

private #onQualityUpdate(data)

Called when an external update modifies the quality list or current selection. Rebuilds the menu and sets externalUpdate to "true".

Parameters:
Name Type Description
data Array<(string|number)>

Array with available qualities.

Parameters:
Name Type Description
qualityData Array<(null|number|string)>

Updated quality array.
current Object

Updated current stream.

Parameters:
Name Type Description
height number

Height of currentSource.
quality string

Quality of currentSource.
Listens
quality/update
Source
Quality.js, line 211

private #updateMenu(metaData)

Updates the UI to match the new current stream's quality.

Parameters:
Name Type Description
metaData Media~metaData

The updated meta data object.
Listens
media/ready
quality/active
Source
Quality.js, line 225

private #toggleQuality(quality)

Switches to a new quality if it differs from the current. Publishes "quality/selected" and tries to switch streams if needed.

Parameters:
Name Type Description
quality number | string

The chosen quality value.
Fires
quality/selected
Source
Quality.js, line 246

private #resize(size)

Reacts to the "ui/resize" event if adaptToSize is enabled. Schedules a check to see if we should automatically pick a new quality based on the new player dimensions.

Parameters:
Name Type Description
size Object

Resize data.

Parameters:
Name Type Description
width number

New width in pixels.
height number

New height in pixels.
Fires
quality/resize
Listens
ui/resize
Source
Quality.js, line 275

private #onStallBegin()

Called when stalling begins. If configured, schedules a possible quality downgrade after a delay.

Listens
media/stall/begin
Source
Quality.js, line 304

private #onStallEnd()

Called when stalling ends, canceling any queued downgrade.

Listens
media/stall/end
Source
Quality.js, line 326

destroy()

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

Source
Quality.js, line 335

Events

quality/active

The Quality component listens to this event to react to outside changes to the selected quality. Updates the menu accordingly. Used mainly for external control by components as dash and hls.

Parameters:
Name Type Description
quality string | number

The selected quality.
Listeners
Quality#updateMenu
Source
Quality.js, line 347

quality/update

The Quality component listens to this event to react to outside changes to the available qualities. Rebuilds the menu accordingly. Used mainly for external control by components as dash and hls.

Parameters:
Name Type Description
qualities Array<(string|number)>

Array with available qualities.
Listeners
Quality#onQualityUpdate
Source
Quality.js, line 354

quality/language/refresh

The Quality component listens to this event to react to outside changes to the selected language. Rebuilds the menu accordingly, using available qualities from the new language.

Parameters:
Name Type Description
qualities Array<(string|number)>

Array with available qualities.
Listeners
Quality#onDataReady
Source
Quality.js, line 361

quality/selected

Fired when a new quality is selected by the user or component logic.

Parameters:
Name Type Description
qualityInfo Object

The selected quality information.
quality string | number

The newly selected quality.
Listeners
Dash#onQualitySelected
Hls#onQualitySelected
Source
Quality.js, line 368

quality/resize

Fired when the component performs a resize-based logic, providing updated width/height info.

Parameters:
Name Type Description
size Object

The updated size information.

Parameters:
Name Type Description
width number

The new width in pixels.
height number

The new height in pixels.
Listeners
Dash#onQualityResize
Source
Quality.js, line 375