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 component’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(id) pins one rendition by its id from videoRenditionList; 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

  • The live preset omits qualityFeature and cannot accept extra features. To add a quality menu to a live player, use createPlayer with [...liveVideoFeatures, qualityFeature]. See Play live streams for custom player setup.
  • 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.
  • Pinning a high rendition on a slow connection causes buffering: the engine can no longer step down. Keep “Auto” the default.
  • Loading a new source replaces the rendition list and resets the selection.

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.

Pin quality programmatically

Call selectVideoRendition to hold one rendition until the user selects “Auto”. To limit resolution while keeping automatic switching, set maxAutoResolution on the source. It needs the hls.js engine; native HLS playback ignores it. See Options Video.js normalizes.

Add a button inside the primary example’s container:

<button type="button" id="lowest-quality" disabled>Use lowest quality</button>

Read the current list from the player store and use the rendition’s id. Pass 'auto' to restore adaptive selection:

import '@videojs/html/video/player';
import { selectQuality } from '@videojs/html';

const player = document.querySelector('video-player');
if (!player) throw new Error('Missing video-player');

const store = player.store;
const button = document.querySelector<HTMLButtonElement>('#lowest-quality')!;
let lowestValue: string | undefined;

function updateButton() {
  const renditions = selectQuality(store.state)?.videoRenditionList ?? [];
  const lowest = [...renditions].sort((a, b) => (a.height ?? 0) - (b.height ?? 0))[0];

  lowestValue = lowest?.id;
  button.disabled = renditions.length < 2;
}

button.addEventListener('click', () => {
  if (lowestValue !== undefined) selectQuality(store.state)?.selectVideoRendition(lowestValue);
});

const unsubscribe = store.subscribe(updateButton);
updateButton();
// Call unsubscribe() when this player is removed.

Troubleshooting

The quality menu doesn’t render

Confirm that the player includes qualityFeature. The live preset omits it; compose a custom player as described above.

Quality availability is 'unavailable'. The source is progressive (no renditions), the manifest hasn’t loaded yet, or the media component doesn’t support renditions. Use a streaming media component 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