From 407d41d24915a7d29b19abe05ab2b9abd7ad7920 Mon Sep 17 00:00:00 2001
From: David LaPalomento <dlapalomento@gmail.com>
Date: Wed, 25 Jan 2017 19:22:04 -0500
Subject: [PATCH] Error early for misconfigured overrideNative (#980)

overrideNative requires emulated text tracks and silently fails if it's misconfigured. Instead, fail spectacularly and early and document that behavior.
---
 README.md                        | 20 ++++++++++++++++++++
 src/videojs-contrib-hls.js       |  8 ++++++++
 test/videojs-contrib-hls.test.js | 12 ++++++++++++
 3 files changed, 40 insertions(+)

diff --git a/README.md b/README.md
index 9376a50c..e7954245 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,7 @@ Maintenance Status: Stable
     - [List](#list)
       - [withCredentials](#withcredentials)
       - [useCueTags](#usecuetags)
+      - [overrideNative](#overridenative)
   - [Runtime Properties](#runtime-properties)
     - [hls.playlists.master](#hlsplaylistsmaster)
     - [hls.playlists.media](#hlsplaylistsmedia)
@@ -242,6 +243,25 @@ cuesTrack.addEventListener('cuechange', function() {
 });
 ```
 
+##### overrideNative
+* Type: `boolean`
+* can be used as an initialization option
+
+Try to use videojs-contrib-hls even on platforms that provide some
+level of HLS support natively. There are a number of platforms that
+*technically* play back HLS content but aren't very reliable or are
+missing features like CEA-608 captions support. When `overrideNative`
+is true, if the platform supports Media Source Extensions
+videojs-contrib-hls will take over HLS playback to provide a more
+consistent experience.
+
+__NOTE__: If you use this option, you must also set
+`videojs.options.html5.nativeAudioTracks` and
+`videojs.options.html5.nativeVideoTracks` to
+`false`. videojs-contrib-hls relies on audio and video tracks to play
+streams with alternate audio and requires additional capabilities only
+supported by non-native tracks in video.js.
+
 ### 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:
diff --git a/src/videojs-contrib-hls.js b/src/videojs-contrib-hls.js
index 8f533f12..b50905e2 100644
--- a/src/videojs-contrib-hls.js
+++ b/src/videojs-contrib-hls.js
@@ -329,6 +329,14 @@ class HlsHandler extends Component {
       }
     }
 
+    // overriding native HLS only works if audio tracks have been emulated
+    // error early if we're misconfigured:
+    if (videojs.options.hls.overrideNative &&
+        (tech.featuresNativeVideoTracks || tech.featuresNativeAudioTracks)) {
+      throw new Error('Overriding native HLS requires emulated tracks. ' +
+                      'See https://git.io/vMpjB');
+    }
+
     this.tech_ = tech;
     this.source_ = source;
     this.stats = {};
diff --git a/test/videojs-contrib-hls.test.js b/test/videojs-contrib-hls.test.js
index f0217415..cbd6cecd 100644
--- a/test/videojs-contrib-hls.test.js
+++ b/test/videojs-contrib-hls.test.js
@@ -1517,6 +1517,18 @@ QUnit.test('loads if native HLS is available and override is set', function(asse
 
   Hls.supportsNativeHls = true;
   player = createPlayer();
+  player.tech_.featuresNativeVideoTracks = true;
+  assert.throws(function() {
+    player.src({
+      src: 'http://example.com/manifest/master.m3u8',
+      type: 'application/x-mpegURL'
+    });
+  }, 'errors if native tracks are enabled');
+  player.dispose();
+
+  player = createPlayer();
+  player.tech_.featuresNativeVideoTracks = false;
+  player.tech_.featuresNativeAudioTracks = false;
   player.src({
     src: 'http://example.com/manifest/master.m3u8',
     type: 'application/x-mpegURL'