Video.js HTTP Source Selector Plugin

1.1.6 verified Thu Apr 23 auth: no javascript maintenance

This Video.js plugin, currently at version 1.1.6, provides a user interface for manual quality level selection in adaptive HTTP streams (HLS/DASH). It is built upon and explicitly requires the `videojs-contrib-quality-levels` plugin to parse and manage the stream's available quality levels. The plugin dynamically generates labels for these levels, prioritizing stream `height` metadata and falling back to `bitrate` when height is unavailable. It is compatible with Video.js versions 7 and higher. While the project appears to be in a maintenance state with no recent releases or significant code commits in the past few years, it remains functional for its intended purpose within compatible Video.js environments. Its primary utility is to offer a direct, user-friendly way to switch stream qualities, enhancing user control over adaptive streaming playback.

Common errors

error TypeError: player.httpSourceSelector is not a function ↓

cause The `videojs-http-source-selector` plugin script has not been loaded or correctly registered with the Video.js player instance before the method was called. This commonly occurs due to incorrect script loading order or failure to include the plugin script.

fix

Ensure video.js, videojs-contrib-quality-levels, and then videojs-http-source-selector are loaded in the correct sequence. For module bundlers, verify the require() or import order. For <script> tags, confirm their placement in the HTML.

error Uncaught ReferenceError: videojs is not defined ↓

cause The main `video.js` library was not loaded or initialized correctly, making the global `videojs` object unavailable when plugins attempted to register themselves.

fix

Verify that video.js is loaded and globally accessible before any Video.js plugins. Check your <script> tag order or module bundling configuration to ensure video.js is the first dependency.

error Uncaught TypeError: Cannot read properties of undefined (reading 'qualityLevels') ↓

cause The `videojs-contrib-quality-levels` plugin, which `videojs-http-source-selector` depends on, was not loaded or correctly initialized on the player instance. This means the `player.qualityLevels()` method is not available.

fix

Confirm that videojs-contrib-quality-levels is installed and loaded *before* videojs-http-source-selector. Ensure that the qualityLevels() method is callable on your videojs player instance before the http source selector tries to use it.

Warnings

breaking This plugin is officially compatible only with Video.js version 7 and above. Using it with older versions of Video.js (prior to v7) may lead to API incompatibilities, unexpected behavior, or runtime errors. ↓

fix Ensure your project utilizes `video.js` version 7 or newer. Upgrade your `video.js` dependency if necessary.

gotcha This plugin has a mandatory peer dependency on `videojs-contrib-quality-levels`. If `videojs-contrib-quality-levels` is not installed and loaded *before* `videojs-http-source-selector`, the plugin will fail to initialize correctly and the source selector UI will not appear. ↓

fix Always install `videojs-contrib-quality-levels` (e.g., `npm install --save videojs-contrib-quality-levels`) and ensure its script is loaded before `videojs-http-source-selector` in `<script>` tags or `require`/`import` statements.

gotcha Quality level labels displayed in the selector menu are primarily generated from the `height` metadata available in the stream's `QualityLevels` sources. If `height` information is missing from your stream's manifest, labels will default to using `bitrate` values, which might be less intuitive for end-users. ↓

fix To ensure clear quality labels (e.g., '1080p', '720p'), verify that your adaptive stream manifests (e.g., HLS M3U8, DASH MPD) include `RESOLUTION` or `HEIGHT` attributes for each quality level.

gotcha The `default` option (`'auto'`, `'low'`, `'high'`) within the `httpSourceSelector` plugin settings dictates the initial quality selection. If `default: 'auto'` is used, the player typically starts at the highest available quality then adapts, which may not be desired for all use cases. Misunderstanding this behavior can lead to unexpected initial playback quality. ↓

fix Explicitly set the `default` option to `'low'` or `'high'` if you require a guaranteed starting quality for all users. Understand that `'auto'` defers to the player's adaptive streaming logic after the initial segment load.

Install

npm install videojs-http-source-selector

yarn add videojs-http-source-selector

pnpm add videojs-http-source-selector

Imports

videojs
wrong
```
const videojs = require('video.js/dist/video.min.js');
```
correct
```
import videojs from 'video.js';
```
This refers to the core Video.js library, which must be loaded and available (either globally or via module import) before the plugin can register itself.
videojs-http-source-selector
wrong
```
import { httpSourceSelector } from 'videojs-http-source-selector';
```
correct
```
require('videojs-http-source-selector');
```
The plugin automatically registers itself with `videojs.Player.prototype` when its script is loaded (via `<script>` tag or `require`). It does not export specific symbols for direct named or default ESM imports.
Player#httpSourceSelector()
```
player.httpSourceSelector(options);
```
After the plugin is loaded and registered, this method is available on Video.js player instances. Calling it initializes and displays the quality selection UI. Options can be passed here or during player initialization via the `plugins` configuration.

Quickstart

This quickstart demonstrates how to set up a Video.js player in HTML, including the necessary script tags for Video.js itself, `videojs-contrib-quality-levels`, and `videojs-http-source-selector`. It then initializes the player, configuring the source selector with a default quality setting and logging its readiness.

<!-- HTML structure for the video player -->
<video id="my-video-element-id" class="video-js vjs-default-skin" controls preload="auto" width="640" height="360">
  <!-- Replace with an actual HLS/DASH stream -->
  <source src="https://example.com/path/to/my-hls-stream.m3u8" type="application/x-mpegURL">
</video>

<script src="https://unpkg.com/video.js@7/dist/video.min.js"></script>
<script src="https://unpkg.com/videojs-contrib-quality-levels/dist/videojs-contrib-quality-levels.min.js"></script>
<script src="https://unpkg.com/videojs-http-source-selector/dist/videojs-http-source-selector.min.js"></script>

<script type="text/javascript">
  // Initialize a Video.js player with the httpSourceSelector plugin options
  const player = videojs('my-video-element-id', {
    controls: true,
    autoplay: false,
    preload: 'auto',
    // Configure the httpSourceSelector plugin with a default option
    plugins: {
      httpSourceSelector: {
        default: 'auto' // Options: 'auto', 'low', 'high'
      }
    }
  });

  // Explicitly initialize the plugin on the player instance. 
  // This step is often implicitly handled if configured in 'plugins' during player init.
  player.httpSourceSelector();

  player.on('ready', function() {
    console.log('Video.js player is ready with HTTP Source Selector!');
    // You can programmatically access quality levels if needed
    // const qualityLevels = player.qualityLevels();
    // console.log('Available quality levels:', qualityLevels.levels);
  });

  player.on('error', function() {
    console.error('Video.js player error:', player.error());
  });
</script>