feat: allow clients to limit the number of times a playlist attempts to reload following an error (#1098)

Introduce a new option `maxPlaylistRetries`, which defaults to Infinity to match existing behavior. If set, this will cause a playlist to be excluded indefinitely when the threshold is crossed. When a playlist is requested successfully, the count is reset.

If a stream has multiple playlists, all playlists will need to cross the max retries threshold for playback to completely fail.

Co-authored-by: Evan farina <efarina@linkedin.com>
Co-authored-by: Gary Katsevman <git@gkatsev.com>
Co-authored-by: brandonocasey <brandonocasey@gmail.com>

Author: 3 people

README.md

@@ -45,6 +45,7 @@ Video.js Compatibility: 6.0, 7.0
       - [parse708captions](#parse708captions)
       - [overrideNative](#overridenative)
       - [blacklistDuration](#blacklistduration)
+    - [maxPlaylistRetries](#maxplaylistretries)
       - [bandwidth](#bandwidth)
       - [useBandwidthFromLocalStorage](#usebandwidthfromlocalstorage)
       - [enableLowInitialPlaylist](#enablelowinitialplaylist)
@@ -362,6 +363,14 @@ if a playlist is blacklisted, it will be blacklisted for a period of that
 customized duration. This enables the blacklist duration to be configured
 by the user.
 
+#### maxPlaylistRetries
+* Type: `number`
+* Default: `Infinity`
+* can be used as an initialization option
+
+The max number of times that a playlist will retry loading following an error
+before being indefinitely excluded from the rendition selection algorithm. Note: the number of retry attempts needs to _exceed_ this value before a playlist will be excluded.
+
 ##### bandwidth
 * Type: `number`
 * can be used as an initialization option

src/manifest.js

@@ -151,6 +151,7 @@ export const forEachMediaGroup = (master, callback) => {
  */
 export const setupMediaPlaylist = ({ playlist, uri, id }) => {
   playlist.id = id;
+  playlist.playlistErrors_ = 0;
 
   if (uri) {
     // For media playlists, m3u8-parser does not have access to a URI, as HLS media

src/master-playlist-controller.js

@@ -140,6 +140,7 @@ export class MasterPlaylistController extends videojs.EventTarget {
       bandwidth,
       externVhs,
       useCueTags,
+      maxPlaylistRetries,
       blacklistDuration,
       enableLowInitialPlaylist,
       sourceType,
@@ -160,6 +161,7 @@ export class MasterPlaylistController extends videojs.EventTarget {
     this.sourceType_ = sourceType;
     this.useCueTags_ = useCueTags;
     this.blacklistDuration = blacklistDuration;
+    this.maxPlaylistRetries = maxPlaylistRetries;
     this.enableLowInitialPlaylist = enableLowInitialPlaylist;
     if (this.useCueTags_) {
       this.cueTagsTrack_ = this.tech_.addTextTrack(
@@ -172,6 +174,7 @@ export class MasterPlaylistController extends videojs.EventTarget {
     this.requestOptions_ = {
       withCredentials,
       handleManifestRedirects,
+      maxPlaylistRetries,
       timeout: null
     };
 
@@ -1132,6 +1135,8 @@ export class MasterPlaylistController extends videojs.EventTarget {
       return;
     }
 
+    currentPlaylist.playlistErrors_++;
+
     const playlists = this.masterPlaylistLoader_.master.playlists;
     const enabledPlaylists = playlists.filter(isEnabled);
     const isFinalRendition = enabledPlaylists.length === 1 && enabledPlaylists[0] === currentPlaylist;
@@ -1179,7 +1184,16 @@ export class MasterPlaylistController extends videojs.EventTarget {
     }
 
     // Blacklist this playlist
-    currentPlaylist.excludeUntil = Date.now() + (blacklistDuration * 1000);
+    let excludeUntil;
+
+    if (currentPlaylist.playlistErrors_ > this.maxPlaylistRetries) {
+      excludeUntil = Infinity;
+    } else {
+      excludeUntil = Date.now() + (blacklistDuration * 1000);
+    }
+
+    currentPlaylist.excludeUntil = excludeUntil;
+
     if (error.reason) {
       currentPlaylist.lastExcludeReason_ = error.reason;
     }

src/segment-loader.js

@@ -2177,9 +2177,7 @@ export default class SegmentLoader extends videojs.EventTarget {
         `video buffer: ${timeRangesToArray(videoBuffered).join(', ')}, `);
       this.error({
         message: 'Quota exceeded error with append of a single segment of content',
-        // To prevent any possible repeated downloads for content we can't actually
-        // append, blacklist forever.
-        blacklistDuration: Infinity
+        excludeUntil: Infinity
       });
       this.trigger('error');
       return;

test/manifest.test.js

@@ -79,12 +79,14 @@ QUnit.module('manifest', function() {
     const expectedPlaylist0 = {
       attributes: {},
       resolvedUri: urlTo('uri-0'),
+      playlistErrors_: 0,
       uri: 'uri-0',
       id: '0-uri-0'
     };
     const expectedPlaylist1 = {
       attributes: {},
       resolvedUri: urlTo('uri-1'),
+      playlistErrors_: 0,
       uri: 'uri-1',
       id: '1-uri-1'
     };

test/master-playlist-controller.test.js

@@ -5973,6 +5973,45 @@ QUnit.test('switch playlists if current playlist gets excluded and re-include if
   this.env.log.warn.callCount = 0;
 });
 
+QUnit.test('Playlist is excluded indefinitely if number of playlistErrors_ exceeds maxPlaylistRetries', function(assert) {
+  this.requests.length = 0;
+  this.player.dispose();
+  this.player = createPlayer({ html5: { vhs: { maxPlaylistRetries: 1 } } });
+  this.player.src({
+    src: 'manifest/two-renditions.m3u8',
+    type: 'application/vnd.apple.mpegurl'
+  });
+
+  this.clock.tick(1);
+
+  this.masterPlaylistController = this.player.tech_.vhs.masterPlaylistController_;
+
+  // main
+  this.standardXHRResponse(this.requests.shift());
+  // media
+  this.standardXHRResponse(this.requests.shift());
+
+  const mpc = this.masterPlaylistController;
+  const mpl = mpc.masterPlaylistLoader_;
+  const playlist = mpl.master.playlists[0];
+
+  assert.equal(playlist.playlistErrors_, 0, 'playlistErrors_ starts at zero');
+
+  mpc.blacklistCurrentPlaylist();
+
+  assert.ok('excludeUntil' in playlist, 'playlist was excluded');
+  assert.equal(playlist.playlistErrors_, 1, 'we incremented playlistErrors_');
+  assert.notEqual(playlist.excludeUntil, Infinity, 'The playlist was not excluded indefinitely');
+
+  mpc.blacklistCurrentPlaylist();
+
+  assert.equal(playlist.playlistErrors_, 2, 'we incremented playlistErrors_');
+  assert.equal(playlist.excludeUntil, Infinity, 'The playlist was excluded indefinitely');
+  assert.equal(this.env.log.warn.callCount, 2, 'logged a warning each time a playlist was excluded');
+
+  this.env.log.warn.callCount = 0;
+});
+
 QUnit.test('should delay loading of new playlist if lastRequest was less than half target duration', function(assert) {
   this.requests.length = 0;
   this.player.dispose();

test/playlist-loader.test.js

@@ -2020,6 +2020,42 @@ QUnit.module('Playlist Loader', function(hooks) {
     assert.strictEqual(loadedMetadata, 1, 'still one loadedmetadata');
   });
 
+  QUnit.test('playlistErrors_ are reset on a successful response', function(assert) {
+    const loader = new PlaylistLoader('manifest/master.m3u8', this.fakeVhs);
+
+    loader.load();
+
+    // master
+    this.requests.shift().respond(
+      200, null,
+      '#EXTM3U\n' +
+      '#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=17\n' +
+      'playlist/playlist.m3u8\n' +
+      '#EXT-X-STREAM-INF:PROGRAM-ID=2,BANDWIDTH=170\n' +
+      'playlist/playlist2.m3u8\n' +
+      '#EXT-X-ENDLIST\n'
+    );
+
+    loader.master.playlists[0].playlistErrors_ = 3;
+
+    // playlist
+    this.requests.shift().respond(404);
+
+    loader.media(loader.master.playlists[1]);
+    loader.media(loader.master.playlists[0]);
+
+    assert.equal(loader.master.playlists[0].playlistErrors_, 3, 'we have 3 playlistErrors_');
+
+    this.requests[1].respond(
+      200, null,
+      '#EXTM3U\n' +
+      '#EXT-X-MEDIA-SEQUENCE:0\n' +
+      '#EXTINF:10,\n' +
+      '0.ts\n'
+    );
+    assert.equal(loader.master.playlists[0].playlistErrors_, 0, 'playlistErrors_ resets to zero when a playlist sucessfully loads');
+  });
+
   QUnit.test(
     'does not misintrepret playlists missing newlines at the end',
     function(assert) {

test/segment-loader.test.js

@@ -4413,7 +4413,7 @@ QUnit.module('SegmentLoader', function(hooks) {
           loader.error_,
           {
             message: 'Quota exceeded error with append of a single segment of content',
-            blacklistDuration: Infinity
+            excludeUntil: Infinity
           },
           'loader triggered and saved the error'
         );