smoothQualityChange flag

README.md

@@ -44,6 +44,8 @@ Video.js Compatibility: 6.0, 7.0
       - [blacklistDuration](#blacklistduration)
       - [bandwidth](#bandwidth)
       - [enableLowInitialPlaylist](#enablelowinitialplaylist)
+      - [limitRenditionByPlayerDimensions](#limitrenditionbyplayerdimensions)
+      - [smoothQualityChange](#smoothqualitychange)
   - [Runtime Properties](#runtime-properties)
     - [hls.playlists.master](#hlsplaylistsmaster)
     - [hls.playlists.media](#hlsplaylistsmedia)
@@ -342,6 +344,22 @@ selection logic will take into account the player size and rendition
 resolutions when making a decision.
 This setting is `true` by default.
 
+##### smoothQualityChange
+* Type: `boolean`
+* can be used as a source option
+* can be used as an initialization option
+
+When the `smoothQualityChange` property is set to `true`, a manual quality
+change triggered via the [representations API](#hlsrepresentations) will use
+smooth quality switching rather than the default fast (buffer-ejecting)
+quality switching. Using smooth quality switching will mean no loading spinner
+will appear during quality switches, but will cause quality switches to only
+be visible after a few seconds.
+
+Note that this _only_ affects quality changes triggered via the representations
+API; automatic quality switches based on available bandwidth will always be
+smooth switches.
+
 ### Runtime Properties
 Runtime properties are attached to the tech object when HLS is in
 use. You can get a reference to the HLS source handler like this:

src/rendition-mixin.js

@@ -48,11 +48,13 @@ const enableFunction = (loader, playlistUri, changePlaylistFn) => (enable) => {
  */
 class Representation {
   constructor(hlsHandler, playlist, id) {
-    // Get a reference to a bound version of fastQualityChange_
-    let fastChangeFunction = hlsHandler
-                              .masterPlaylistController_
-                              .fastQualityChange_
-                              .bind(hlsHandler.masterPlaylistController_);
+    const {
+      masterPlaylistController_: mpc,
+      options_: { smoothQualityChange }
+    } = hlsHandler;
+    // Get a reference to a bound version of the quality change function
+    const changeType = smoothQualityChange ? 'smooth' : 'fast';
+    const qualityChangeFunction = mpc[`${changeType}QualityChange_`].bind(mpc);
 
     // some playlist attributes are optional
     if (playlist.attributes.RESOLUTION) {
@@ -72,7 +74,7 @@ class Representation {
     // specific variant
     this.enabled = enableFunction(hlsHandler.playlists,
                                   playlist.uri,
-                                  fastChangeFunction);
+                                  qualityChangeFunction);
   }
 }
 

src/videojs-http-streaming.js

@@ -341,6 +341,7 @@ class HlsHandler extends Component {
     // defaults
     this.options_.withCredentials = this.options_.withCredentials || false;
     this.options_.limitRenditionByPlayerDimensions = this.options_.limitRenditionByPlayerDimensions === false ? false : true;
+    this.options_.smoothQualityChange = this.options_.smoothQualityChange || false;
 
     if (typeof this.options_.blacklistDuration !== 'number') {
       this.options_.blacklistDuration = 5 * 60;
@@ -359,7 +360,7 @@ class HlsHandler extends Component {
       this.options_.bandwidth === Config.INITIAL_BANDWIDTH;
 
     // grab options passed to player.src
-    ['withCredentials', 'limitRenditionByPlayerDimensions', 'bandwidth'].forEach((option) => {
+    ['withCredentials', 'limitRenditionByPlayerDimensions', 'bandwidth', 'smoothQualityChange'].forEach((option) => {
       if (typeof this.source_[option] !== 'undefined') {
         this.options_[option] = this.source_[option];
       }

test/configuration.test.js

@@ -33,6 +33,11 @@ const options = [{
   default: 4194304,
   test: 5,
   alt: 555
+}, {
+  name: 'smoothQualityChange',
+  default: false,
+  test: true,
+  alt: false
 }];
 
 const CONFIG_KEYS = Object.keys(Config);

test/rendition-mixin.test.js

@@ -41,17 +41,22 @@ const makeMockPlaylist = function(options) {
   return playlist;
 };
 
-const makeMockHlsHandler = function(playlistOptions) {
+const makeMockHlsHandler = function(playlistOptions, handlerOptions) {
   let mcp = {
     fastQualityChange_: () => {
       mcp.fastQualityChange_.calls++;
+    },
+    smoothQualityChange_: () => {
+      mcp.smoothQualityChange_.calls++;
     }
   };
 
   mcp.fastQualityChange_.calls = 0;
+  mcp.smoothQualityChange_.calls = 0;
 
   let hlsHandler = {
-    masterPlaylistController_: mcp
+    masterPlaylistController_: mcp,
+    options_: handlerOptions || {}
   };
 
   hlsHandler.playlists = new videojs.EventTarget();
@@ -222,7 +227,7 @@ function(assert) {
     'excludeUntil not touched when disabling a rendition');
 });
 
-QUnit.test('changing the enabled state of a representation calls fastQualityChange_',
+QUnit.test('changing the enabled state of a representation calls fastQualityChange_ by default',
 function(assert) {
   let renditionEnabledEvents = 0;
   let hlsHandler = makeMockHlsHandler([
@@ -260,3 +265,45 @@ function(assert) {
 
   assert.equal(mpc.fastQualityChange_.calls, 2, 'fastQualityChange_ was called twice');
 });
+
+QUnit.test('changing the enabled state of a representation calls smoothQualityChange_ ' +
+  'when the flag is set',
+function(assert) {
+  let renditionEnabledEvents = 0;
+  let hlsHandler = makeMockHlsHandler([
+    {
+      bandwidth: 0,
+      disabled: true,
+      uri: 'media0.m3u8'
+    },
+    {
+      bandwidth: 0,
+      uri: 'media1.m3u8'
+    }
+  ], {
+    smoothQualityChange: true
+  });
+  let mpc = hlsHandler.masterPlaylistController_;
+
+  hlsHandler.playlists.on('renditionenabled', function() {
+    renditionEnabledEvents++;
+  });
+
+  RenditionMixin(hlsHandler);
+
+  let renditions = hlsHandler.representations();
+
+  assert.equal(mpc.smoothQualityChange_.calls, 0, 'smoothQualityChange_ was never called');
+  assert.equal(renditionEnabledEvents, 0,
+    'renditionenabled event has not been triggered');
+
+  renditions[0].enabled(true);
+
+  assert.equal(mpc.smoothQualityChange_.calls, 1, 'smoothQualityChange_ was called once');
+  assert.equal(renditionEnabledEvents, 1,
+    'renditionenabled event has been triggered once');
+
+  renditions[1].enabled(false);
+
+  assert.equal(mpc.smoothQualityChange_.calls, 2, 'smoothQualityChange_ was called twice');
+});