API
Quality
In this section, we'll look at how playback quality can be tracked and configured with Vidstack Player.
Quality tracking and selection is currently only supported by the HLS Provider.
Introduction
Adaptive streaming protocols like HLS not only enable streaming media in chunks, but also have the ability adapt playback quality based on the device size, network conditions, and other information. Adaptive qualities is important for speeding up initial delivery and to avoid loading excessive amounts of data which cause painful buffering delays.
Streaming platforms such as Cloudflare Stream and Mux will take an input video file (e.g., awesome-video.mp4
) and create multiple renditions out of the box for you, with multiple resolutions (width/height) and bit rates:
By default, the best quality is automatically selected by the streaming engine such as hls.js
. You'll usually see this as an "Auto" option in the player quality menu. It can also be manually set if the engine is not making optimal decisions as they're generally more conservative to avoid excessive bandwidth usage. In the following sections, you'll learn how to track available playback qualities with Vidstack Player and also how to configure it manually.
Quality List
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:
Selecting
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 readonly, setting selected will do nothing (use qualities.readonly
to check), and (2) if the list not readonly, setting selected will remove auto quality selection.
Switch
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.
Auto Select
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.
List Events
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.
Media Store
The following video quality properties are available on the media store:
qualities
: An array containing the current list ofVideoQuality
objects.quality
: The currentVideoQuality
object ornull
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.
Media Remote
The changeQuality
method on the media remote can be used to dispatch requests to update the current quality like so:
Media Events
The following video quality events are available on the player:
qualities-change
: Fired when the available list of video qualities has changed.quality-change
: Fired when the selected video quality has changed.