API

Video Quality

An overview of using and configuring video playback quality.

The Loading Video Qualities guide covers how to create multiple resolutions and why you should consider adaptive streaming protocols such as HLS or DASH. However, you can also load different resolutions using multiple video files, see Source Sizes.

The read-only qualities property on the player returns a VideoQualityList object that contains VideoQuality objects. Each video quality represents a currently available video rendition.

Similar to text tracks or audio tracks, the returned list is live; that is, as qualities are added to and removed from the player, the list’s contents change dynamically. Once you have a reference to the list, you can monitor it for changes to detect when new qualities are added or existing ones are removed by listening to list events.

The VideoQuality interface contains the following shape:

The selected property can be used to set the current video quality like so:

Once set, the underlying provider will update the playback quality setting. Two things to keep in mind is: (1) if the list is read only, setting selected will do nothing (use qualities.readonly to check), and (2) if the list not read only, setting selected will remove auto quality selection.

The quality switching behavior can be configured using the switch property on the VideoQualityList object. The following options are available:

• current (default): Trigger an immediate quality level switch. This will abort the current fragment request if any, flush the whole buffer, and fetch fragment matching with current position and requested quality level.
• next: Trigger a quality level switch for next fragment. This could eventually flush already buffered next fragment.
• load: Set quality level for next loaded fragment.

You can request the engine to handle automatic quality selection using the autoSelect method on the VideoQualityList object like so:

Keep in mind, manually setting qualities will disable auto selection, you will need to call autoSelect() to enable it again.

The VideoQualityList object is an EventTarget which dispatches the following events:

• add: Fired when a video quality has been added to the list.
• remove: Fired when a video quality has been removed from the list.
• change: Fired when the selected video quality changes.
• auto-change: Fired when the auto-quality selection mode changes.
• readonly-change: Fired when the read-only mode changes.

The following video quality properties are available on the media store:

• qualities: An array containing the current list of VideoQuality[] objects.
• quality: The current VideoQuality object or null if none is available.
• autoQuality: Whether automatic quality selection is enabled.
• canSetQuality: Whether qualities can be manually selected, in other words whether the quality list is not read-only.

The changeQuality method on the media remote can be used to dispatch media-quality-change-request request events to update the current video quality like so:

The following video quality events are available on the player: