Quality Selection Plugin

Product(s)
Video Cloud
Brightcove Player
Role(s)
Player Developer
Topic(s)
Playback
Plugins
Renditions

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.

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.

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.

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:

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

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.
  • 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:

    Options SD and HD only

    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.

  • 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:

    All video bitrates

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 work in Safari.
  • The quality selector does not appear in iOS.
  • 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.

Changelog

10 Aug 2018

v1.2.2

  • Fixed styling of cog icon

2 May 2018

v1.2.1

  • Fixed listener disposal

5 Sep 2017

v1.2.0

  • Added enhancement to allow passing default preferred rendition to use

18 Aug 2017

v1.1.1

  • Fixed an issue with plugin registry integration

2017

v1.1.0

  • Added an option to display bitrate data in resolution menu
  • Updated README; added unit test for resolutionLabelBitrates
  • Fixed style for cog icon
  • Updated alignment for vjs-control-text
  • Added support for plugin registry

1 Mar 2017

v1.0.3

  • Support Video.js 5 & 6

13 Feb 2017

v1.0.2

  • Added Graphite skin compatibility
  • Added IE8 support

2 Feb 2017

v1.0.1

  • Update 4K and HD flag styles to be circular
  • Add p to the end of resolution labels

17 Jan 2017

v1.0.0

  • Initial Release