{"id":17994,"library":"videojs-http-source-selector","title":"Video.js HTTP Source Selector Plugin","description":"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.","status":"maintenance","version":"1.1.6","language":"javascript","source_language":"en","source_url":"https://github.com/jfujita/videojs-http-source-selector","tags":["javascript","videojs","videojs-plugin"],"install":[{"cmd":"npm install videojs-http-source-selector","lang":"bash","label":"npm"},{"cmd":"yarn add videojs-http-source-selector","lang":"bash","label":"yarn"},{"cmd":"pnpm add videojs-http-source-selector","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for parsing and managing the underlying adaptive stream quality levels that this plugin then uses to build the user selection UI.","package":"videojs-contrib-quality-levels","optional":false}],"imports":[{"note":"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.","wrong":"const videojs = require('video.js/dist/video.min.js');","symbol":"videojs","correct":"import videojs from 'video.js';"},{"note":"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.","wrong":"import { httpSourceSelector } from 'videojs-http-source-selector';","symbol":"videojs-http-source-selector","correct":"require('videojs-http-source-selector');"},{"note":"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.","symbol":"Player#httpSourceSelector()","correct":"player.httpSourceSelector(options);"}],"quickstart":{"code":"<!-- HTML structure for the video player -->\n<video id=\"my-video-element-id\" class=\"video-js vjs-default-skin\" controls preload=\"auto\" width=\"640\" height=\"360\">\n  <!-- Replace with an actual HLS/DASH stream -->\n  <source src=\"https://example.com/path/to/my-hls-stream.m3u8\" type=\"application/x-mpegURL\">\n</video>\n\n<script src=\"https://unpkg.com/video.js@7/dist/video.min.js\"></script>\n<script src=\"https://unpkg.com/videojs-contrib-quality-levels/dist/videojs-contrib-quality-levels.min.js\"></script>\n<script src=\"https://unpkg.com/videojs-http-source-selector/dist/videojs-http-source-selector.min.js\"></script>\n\n<script type=\"text/javascript\">\n  // Initialize a Video.js player with the httpSourceSelector plugin options\n  const player = videojs('my-video-element-id', {\n    controls: true,\n    autoplay: false,\n    preload: 'auto',\n    // Configure the httpSourceSelector plugin with a default option\n    plugins: {\n      httpSourceSelector: {\n        default: 'auto' // Options: 'auto', 'low', 'high'\n      }\n    }\n  });\n\n  // Explicitly initialize the plugin on the player instance. \n  // This step is often implicitly handled if configured in 'plugins' during player init.\n  player.httpSourceSelector();\n\n  player.on('ready', function() {\n    console.log('Video.js player is ready with HTTP Source Selector!');\n    // You can programmatically access quality levels if needed\n    // const qualityLevels = player.qualityLevels();\n    // console.log('Available quality levels:', qualityLevels.levels);\n  });\n\n  player.on('error', function() {\n    console.error('Video.js player error:', player.error());\n  });\n</script>","lang":"javascript","description":"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."},"warnings":[{"fix":"Ensure your project utilizes `video.js` version 7 or newer. Upgrade your `video.js` dependency if necessary.","message":"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.","severity":"breaking","affected_versions":"<7.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: player.httpSourceSelector is not a function"},{"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.","cause":"The main `video.js` library was not loaded or initialized correctly, making the global `videojs` object unavailable when plugins attempted to register themselves.","error":"Uncaught ReferenceError: videojs is not defined"},{"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.","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.","error":"Uncaught TypeError: Cannot read properties of undefined (reading 'qualityLevels')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}