Skip to content

GuidePlayback

Add a quality selector

Read available renditions, let the engine adapt automatically, and offer manual quality selection.

Quality selection applies to streaming sources. A progressive MP4 plays at one fixed quality and exposes no renditions; HLS and DASH streams offer several. See Media sources.

Installation

This guide uses the hls.js media component, so install its adapter with the framework façade:

pnpm add @videojs/html @videojs/hlsjs-video

Recommended approach

Let automatic quality selection do its job by default, and offer a quality menu for users who want to pin a rendition. Render the menu only when quality selection is available.

 
<video-player class="video-player">
  <media-container>
    <hlsjs-video
      class="video-media"
      src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4.m3u8"
      autoplay
      crossorigin="anonymous"
      muted
      playsinline
      loop
    ></hlsjs-video>
    <div class="menu-bar">
      <button type="button" commandfor="quality-menu" class="settings-trigger">Quality</button>
      <media-menu id="quality-menu" side="top" align="end" class="menu">
        <media-menu-content>
          <media-quality-radio-group class="menu-group" label="Quality">
            <template>
              <media-menu-radio-item class="menu-item">
                <span>
                  <span data-part="label"></span>
                  <sup data-part="tier" class="menu-tier"></sup>
                </span>
                <span data-part="badge" class="menu-badge"></span>
                <media-menu-item-indicator force-mount class="menu-indicator">✓</media-menu-item-indicator>
              </media-menu-radio-item>
            </template>
          </media-quality-radio-group>
        </media-menu-content>
      </media-menu>
    </div>
  </media-container>
</video-player>

How it works

The quality feature mirrors the media element’s video renditions into player state:

  • videoRenditionList holds each rendition’s id, width, height, bitrate, frameRate, codec, and whether it’s selected.
  • activeVideoRendition is the rendition currently playing. When the engine doesn’t report one directly, the player matches it from the video’s current dimensions.
  • selectVideoRendition(value) pins one rendition; pass 'auto' to return control to the engine’s adaptive selection.

<media-quality-radio-group> turns this state into a ready-made radio menu with resolution labels and an “Auto” entry, as the example above shows.

Selecting “Auto” keeps adaptive bitrate switching active: the engine picks the best rendition for current bandwidth and viewport. Pinning a rendition disables adaptation until the user selects “Auto” again.

Availability and constraints

  • Quality availability is 'unavailable' for media that doesn’t offer a choice — progressive files, streams before the manifest loads, and single-rendition streams. Render quality UI conditionally on that value.
  • Renditions come from the streaming engine, so the list depends on what the manifest declares. A single-rendition stream offers no meaningful selection, so availability stays 'unavailable'.
  • Pinning a high rendition on a slow connection causes buffering: the engine can no longer step down. Keep “Auto” the default.
  • Rendition lists change on source change; selection resets with them.

Common variations

Auto quality only

If you don’t want to expose manual selection, do nothing: adaptive selection is on by default and needs no UI.

Cap or pin quality programmatically

Access the player store through the player controller and call selectVideoRendition with a rendition id from videoRenditionList, or 'auto' to restore adaptive selection.

Troubleshooting

The quality menu doesn’t render

Quality availability is 'unavailable'. The source is progressive (no renditions), the manifest hasn’t loaded yet, or the media element doesn’t support renditions. Use a streaming media element such as <hls-video> or <hlsjs-video>.

The menu doesn’t render for a single-rendition stream

The manifest declares a single rendition, so quality availability stays 'unavailable' — one entry offers no choice. Encode the stream as a multi-rendition ladder to give the engine and users something to choose between.

Playback buffers after selecting a quality

The pinned rendition exceeds available bandwidth. Selecting “Auto” lets the engine step down again.

Related pages

Components

API

Guides