Quality Selection Plugin

In this topic, you will learn how to use the Quality Selection Plugin. This plugin provides a menu button in the player’s controlbar which allows you to manually select the playback quality for HLS or Dash sources.

Note: The Quality Selection Plugin does not work with all video sources. The following points clarify the situation:

This plugin only works with HLS/DASH sources.
This plugin will display the resolution information for any M3U8 master file that includes the resolution info for the child renditions. If no resolution is specified, the plugin will show HD/SD instead.
It does not matter where the HLS M3U8 file is hosted or whether it is LIVE or VOD.
This plugin does NOT work with MP4. If you have five MP4 sources, and only one HLS source, you will not see the quality selector appear showing the different MP4 qualities.

Mục lục

Player example

The following is a Brightcove Player that is using the quality selection plugin. Once you play the video, in the controlbar you will see the following icon:

Once you make a selection, the gear will spin until the new quality is rendered, for DASH sources, or until the new quality is being loaded, for HLS sources. More information is provided below on the quality options you see for the selection, and gear spinning behavior.

If you have a fast Internet connection, you may have to make a number of selections before you see the gear spin as changes take place quickly with HLS renditions, which this video is using.

Quality options

When the gear icon is clicked, a number of quality options are displayed for user selection. For example, a video with the following renditions:

All video renditions

will create the following quality options:

Quality options

Here is how those options are built and then a specific rendition selected:

All renditions are grouped based on lines of horizontal resolution (e.g. 270p, 360p, 540p, 720p and 1080p in the example above) and used as quality options.
After user selection of a group, if there are multiple renditions in the selected group the standard adaptive bitrate streaming algorithm then chooses the optimal rendition in the selected resolution group. The process is how rendition selection currently works, but only within a selected resolution group.
If resolution information is not available, options will fallback to show options SD and HD, for Standard Definition and High Definition respectively. The plugin will use bitrate information for each rendition to determine whether it is SD or HD, using a configurable dividing line.

Buffering

When changing the quality it is possible that some buffering will take place and you will see the loading spinner appear. This is because the quality is changed immediately on quality selection and segments will need to be downloaded. If you prefer to have the same smooth transition behavior seen with automatic rendition switches, you can manually initialize the player with the following option:

var options = {
  html5: {
    hls: {
      smoothQualityChange: true
    }
  }
};

Details on manually initializing the player using the bc() method can be found in the Using bc() and getPlayer() Methods document.

Gear spinning

The gear icon spinning represents changes to the rendition used. The rules for spinning differ for DASH and HLS sources:

For DASH sources, the gear will spin until the quality has changed in the player and being rendered on screen.
For HLS sources, the gear stops spinning when the internal algorithm has decided to start LOADING the new quality, not when it has been rendered. This decision happens quickly, so it is probable you won’t see the spinning action that frequently with an HLS source.

Implement using Players module

To implement the quality selection plugin using the Players module, follow these steps:

Open the PLAYERS module and either create a new player or locate the player to which you wish to add the plugin.
Click the link for the player to open the player’s properties.
Click Controls in the left navigation menu.
Check the box in front of Quality Selector.
Use a radio button to display either the different resolutions available, or simply an HD/SD option.
Click Save.
To publish the player, click Publish & Embed > Publish Changes.
To close the open dialog, click Close.

Implement using Code

To implement the quality selection plugin using code, follow these steps:

In an editor, open your HTML code where you want the Brightcove Player to reside.

In the head section, add the quality selection plugin default style sheet.

<link href="https://players.brightcove.net/videojs-quality-menu/1/videojs-quality-menu.css" rel='stylesheet'>

In the body section, add the advanced player embed code.

To the player embed code, we’ve added an id attribute so that we can get a reference to the player in a later script.

<video-js id="myPlayerID"
  data-account="1752604059001"
  data-player="default"
  data-embed="default"
  controls=""
  data-video-id="5842800655001"
  data-playlist-id=""
  data-application-id=""
  width="960" height="540"></video-js>
<script src="https://players.brightcove.net/1752604059001/default_default/index.min.js"></script>

After your player embed code, add the quality selection plugin script file.

<script src="https://players.brightcove.net/videojs-quality-menu/1/videojs-quality-menu.min.js"></script>

Below the plugin script, add a script that does the following:
- Get a reference to the Brightcove Player.
- Register the quality selection plugin with the player.
- Specify any plugin options that you want to use. In this example, we are setting the default quality selection to 720p.
```
<script type="text/javascript">
  videojs.getPlayer('myPlayerID').ready(function() {
    var myPlayer = this;
    myPlayer.qualityMenu({
      defaultResolution: '720p'
    });
  });
</script>
```

Complete code example

Here is a complete code example for using the quality selection plugin, setting the initial default resolution:

<!DOCTYPE html>
<html>
    <head>
      <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
      <title>Quality Selection</title>

      <!-- CSS for the quality selection plugin -->
      <link href="https://players.brightcove.net/videojs-quality-menu/1/videojs-quality-menu.css" rel='stylesheet'>
    </head>

    <body>
    <h1>Quality Selection</h1>

    <!-- Brightcove Player embed code -->
    <video-js id="myPlayerID"
      data-account="1752604059001"
      data-player="default"
      data-embed="default"
      controls=""
      data-video-id="5842800655001"
      data-playlist-id=""
      data-application-id=""
      width="960" height="540"></video-js>
    <script src="https://players.brightcove.net/1752604059001/default_default/index.min.js"></script>

    <!-- Script for the quality selection plugin -->
    <script src="https://players.brightcove.net/videojs-quality-menu/1/videojs-quality-menu.min.js"></script>

    <script type="text/javascript">
      // When the player is ready, get a reference to it
      videojs.getPlayer('myPlayerID').ready(function() {
        var myPlayer = this;

        // Register the quality selection plugin with options
        myPlayer.qualityMenu({
          defaultResolution: '720p'
        });
      });
    </script>
    </body>
</html>

Configuration options

The following options are available to configure the plugin if you are implementing the plugin using code:

defaultResolution
- Type: String
- Default: none
- Defines the default resolution or resolution mapping to use. Pass it either the horizontal resolution or SD/HD.
Change default initial resolution in Video Cloud Studio

Follow these steps to change the default resolution in Video Cloud Studio:
1. In the PLAYERS module, select the player to which you have added the Quality Selection Plugin.
2. In the left navigation, select JSON Editor.
3. Locate the section about the Quality Selection Plugin in the plugins section, shown here:
```
{
    "registry_id": "@brightcove/videojs-quality-menu",
    "version": "1.x",
    "options": {
      "useResolutionLabels": true
    }
  }
```
4. To the options section, add your desired default resolution, as shown in the highlighted section (don’t forget to add a comma at the end of the previous line):
```
{
    "registry_id": "@brightcove/videojs-quality-menu",
    "version": "1.x",
    "options": {
      "useResolutionLabels": true,
      "defaultResolution": "720p"
    }
  }
```
5. Click Save to save the altered JSON.
6. Publish the changed player.
Of course, similar steps can be used to set any of the options in this section using Video Cloud Studio.
sdBitrateLimit
- Type: Number
- Default: 2000000
- Defines the upper bitrate limit (exclusive) for considering a rendition SD.
useResolutionLabels
- Type: Boolean
- Default: true
- When true, the plugin will attempt to categorize renditions by lines of horizontal resolution when available. Set to false to always use SD/HD categorization.
To implement the useResolutionLabels option, you would enter the following in the plugin’s options in Studio:
```
{
  "useResolutionLabels": false
}
```
The resulting quality options would appear as follows:

The player would then select the optimal rendition from the selected group. As detailed in this section, sdBitrateLimit is configurable to determine the renditions classified as SD and HD.

Contradictory settings will not work. For instance, neither of the following make sense to use as in both cases you are providing an illegal value for a label based on the useResolutionLabels setting.
```
"useResolutionLabels": true,
"defaultResolution": "HD"
```
```
"useResolutionLabels": false,
"defaultResolution": "1080p"
```
resolutionLabelBitrates
- Type: Boolean
- Default: false
- When true, the plugin will attach bitrate information to the resolution labels (e.g. 720p @ 13806 kbps). This option has no effect when useResolutionLabels is false or when resolution information is unavailable.
When this configuration option is set the true, the quality selector will appear as follows:

Styling the control

CSS is used to style the gear icon, as well as the menu that appears. The following table shows the common components you can style, the components’ selectors and finally the CSS property to set.

Component
Selector
Property

Gear icon
button.vjs-quality-menu-button.vjs-menu-button.vjs-menu-button-popup.vjs-button
color

Color of menu items
div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-menu-item
background-color

Text color of menu items
div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-menu-item-text
color

Color of selected menu item
div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-menu-item.vjs-selected
background-color

Text color of selected item
div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-menu-item.vjs-selected .vjs-menu-item-text
color

Text color of HD label
div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-quality-menu-item-sub-label
color

For example, to achieve the following:

You would use this CSS:

/* Style the icon */
button.vjs-quality-menu-button.vjs-menu-button.vjs-menu-button-popup.vjs-button {
  color: red;
}
/* Style the background of the menu items */
div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-menu-item {
  background-color: yellow;
}
/* Style the text of menu items */
div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-menu-item-text {
  color: green;
}
/* Style the background color of selected menu item */
div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-menu-item.vjs-selected {
  background-color: white;
}
/* Style the text color of selected menu item */
div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-menu-item.vjs-selected .vjs-menu-item-text{
  color: blue;
}
/* Style the HD label */
div.vjs-quality-menu-wrapper.vjs-menu-button.vjs-menu-button-popup.vjs-control.vjs-button.vjs-quality-menu-button-use-resolution .vjs-quality-menu-item-sub-label {
  color: lime;
}

Known issues

The plugin functions with Brightcove Player version 5.17.0 and later. Functionality with earlier versions of the player is not supported.
The quality selector does not appear in Safari.
The quality selector does not appear in iOS. This is an Apple limitation, apple does not allow manually controlling the playback quality on iOS or desktop as it uses adaptive bitrate streaming to adjust the quality level automatically, based on bandwidth, connection speed, screen size, etc.

Notes:

There is no way for Brightcove to override this as Apple doesn’t expose any APIs to allow for overriding their built-in rendition selection.
The Brightcove Player uses Safari’s native playback engine on macOS and iOS/iPadOS, which does not allow quality selection by the user. The engine has its own rendition selection algorithm that results in a good user experience.

At times the quality switch will not happen at the desired time, it can take longer than expected.
Setting the source in the player configuration and building with single video template will cause the quality menu to not be initialized properly. This is because the source will be set through a call to the videojs constructor, which does not have access to the player or plugins. The source should be set by calling player.src(). This does not affect Video Cloud users.
The quality menu will not be displayed when using DASH content with Silverlight.
The Video Quality in the selector is re-set to Auto at every player load. It does not maintain any previous setting.

Changelog

See the Quality Menu Plugin Release Notes.

For historical release notes, see the changelog here.

Player example

Quality options

Buffering

Gear spinning

Implement using Players module

Implement using Code

Complete code example

Configuration options

`defaultResolution`

Change default initial resolution in Video Cloud Studio

`sdBitrateLimit`

`useResolutionLabels`

`resolutionLabelBitrates`

Styling the control

Known issues

Changelog