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

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

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 = {};

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'