Merge branch 'master' into backbuffer

brvier · Feb 16, 2021 · 100e42d · 100e42d
2 parents 380be97 + fe29a49
commit 100e42d
Show file tree

Hide file tree

Showing 6 changed files with 573 additions and 279 deletions.
diff --git a/.prettierignore b/.prettierignore
@@ -1,6 +1,8 @@
-/dist
 /api-docs
-package-lock.json
+/api-extractor/report
+/api-extractor/report-*
 /coverage
-libs/
-/api-extractor/report*
+/demo/libs
+/dist
+/lib
+package-lock.json
diff --git a/README.md b/README.md
@@ -9,20 +9,20 @@ Join the discussion via [video-dev.org](https://video-dev.org) in #hlsjs (our Sl
 
 # ![hls.js](https://cloud.githubusercontent.com/assets/616833/19739063/e10be95a-9bb9-11e6-8100-2896f8500138.png)
 
-hls.js is a JavaScript library which implements an [HTTP Live Streaming] client.
+hls.js is a JavaScript library that implements an [HTTP Live Streaming] client.
 It relies on [HTML5 video][] and [MediaSource Extensions][] for playback.
 
 It works by transmuxing MPEG-2 Transport Stream and AAC/MP3 streams into ISO BMFF (MP4) fragments.
-This transmuxing could be performed asynchronously using [Web Worker] if available in the browser.
+Transmuxing is performed asynchronously using a [Web Worker] when available in the browser.
 hls.js also supports HLS + fmp4, as announced during [WWDC2016](https://developer.apple.com/videos/play/wwdc2016/504/)
 
-hls.js does not need any player, it works directly on top of a standard HTML`<video>`element.
+hls.js works directly on top of a standard HTML`<video>` element.
 
 hls.js is written in [ECMAScript6] (`*.js`) and [TypeScript] (`*.ts`) (strongly typed superset of ES6), and transpiled in ECMAScript5 using the [TypeScript compiler].
 
 Modules written in TS and plain JS/ES6 can be interdependent and imported/required by each other.
 
-To build our distro bundle and serve our development environment we use [Webpack].
+[Webpack] is used to build the distro bundle and serve the local development environment.
 
 [html5 video]: https://www.html5rocks.com/en/tutorials/video/basics/
 [mediasource extensions]: https://w3c.github.io/media-source/
@@ -36,7 +36,6 @@ To build our distro bundle and serve our development environment we use [Webpack
 ## API docs and usage guide
 
 - [API and usage docs, with code examples](./docs/API.md)
-
 - [Auto-Generated Docs (Latest Release)](https://hls-js.netlify.com/api-docs)
 - [Auto-Generated Docs (Master)](https://hls-js-dev.netlify.com/api-docs)
 
@@ -60,10 +59,10 @@ Find the commit on [https://github.com/video-dev/hls.js/blob/deployments/README.
 
 hls.js is only compatible with browsers supporting MediaSource extensions (MSE) API with 'video/MP4' mime-type inputs.
 
-As of today, hls.js is supported on:
+Hls.js is supported on:
 
-- Chrome for Android 34+
-- Chrome for Desktop 34+
+- Chrome for Android 39+
+- Chrome for Desktop 39+
 - Firefox for Android 41+
 - Firefox for Desktop 42+
 - IE11+ for Windows 8.1+
@@ -73,13 +72,13 @@ As of today, hls.js is supported on:
 - Safari for Mac 8+ (beta)
 - Safari for ipadOS 13+
 
-**Please note:** iOS Safari (iPhones) does not support the MediaSource API. This includes all browsers on iOS as well as apps using UIWebView and WKWebView.
+**Please note:** iOS Safari on iPhone does not support the MediaSource API. This includes all browsers on iOS as well as apps using UIWebView and WKWebView.
 
-Safari browsers (iOS, ipadOS and macOS) do however have built-in HLS support through the plain video "tag" source URL. See the example below (Getting Started) to run appropriate feature detection and choose between using Hls.js or natively built-in HLS support.
+Safari browsers (iOS, iPadOS, and macOS) have built-in HLS support through the plain video "tag" source URL. See the example below (Getting Started) to run appropriate feature detection and choose between using Hls.js or natively built-in HLS support.
 
-When a platform has neither MediaSource nor native HLS support, you will not be able to play HLS.
+When a platform has neither MediaSource nor native HLS support, the browser cannot play HLS.
 
-_Keep in mind that if the intention is to support HLS on multiple platforms, beyond those compatible with hls.js, the HLS streams need to strictly follow the specifications of RFC8216, especially if apps, smart TVs and set-top boxes are to be supported._
+_Keep in mind that if the intention is to support HLS on multiple platforms, beyond those compatible with hls.js, the HLS streams need to strictly follow the specifications of RFC8216, especially if apps, smart TVs, and set-top boxes are to be supported._
 
 Find a support matrix of the MediaSource API here: https://developer.mozilla.org/en-US/docs/Web/API/MediaSource
 
@@ -119,13 +118,9 @@ Find a support matrix of the MediaSource API here: https://developer.mozilla.org
 
 #### Alternative setup
 
-Note that the example code above will check for hls.js support _first_ and then
-fallback to check if the browser natively supports HLS. If you want to check for
-native browser support first, and then fallback to Hls.js you will want to swap
-those conditionals.
+Note that the example code above will check for hls.js support _first_ and then fallback to check if the browser natively supports HLS. To check for native browser support first and then fallback to Hls.js, swap these conditionals.
 
-The order of these checks depends on if you want to use hls.js whenever possible
-see [this comment](https://github.com/video-dev/hls.js/pull/2954#issuecomment-670021358) to understand some of the tradeoffs.
+See [this comment](https://github.com/video-dev/hls.js/pull/2954#issuecomment-670021358) to understand some of the tradeoffs.
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
@@ -153,11 +148,25 @@ see [this comment](https://github.com/video-dev/hls.js/pull/2954#issuecomment-67
 
 ## Video Control
 
-Video is controlled through HTML `<video>` element.
+Video is controlled through HTML `<video>` element `HTMLVideoElement` methods, events and optional UI controls (`<video controls>`).
+
+## Player Integration
+
+The following players integrate hls.js for HLS playback:
 
-HTMLVideoElement control and events could be used seamlessly.
+- [JW Player](https://www.jwplayer.com)
+- [Akamai Adaptive Media Player (AMP)](https://www.akamai.com/us/en/solutions/products/media-delivery/adaptive-media-player.jsp)
+- [Clappr](https://github.com/clappr/clappr)
+- [Flowplayer](https://www.flowplayer.org) through [flowplayer-hlsjs](https://github.com/flowplayer/flowplayer-hlsjs)
+- [MediaElement.js](https://www.mediaelementjs.com)
+- [Videojs](https://videojs.com) through [Videojs-hlsjs](https://github.com/benjipott/videojs-hlsjs)
+- [Videojs](https://videojs.com) through [videojs-hls.js](https://github.com/streamroot/videojs-hls.js). hls.js is integrated as a SourceHandler -- new feature in Video.js 5.
+- [Videojs](https://videojs.com) through [videojs-contrib-hls.js](https://github.com/Peer5/videojs-contrib-hls.js). Production ready plug-in with full fallback compatibility built-in.
+- [Fluid Player](https://www.fluidplayer.com)
+- [OpenPlayerJS](https://www.openplayerjs.com), as part of the [OpenPlayer project](https://github.com/openplayerjs)
+- [CDNBye](https://github.com/cdnbye/hlsjs-p2p-engine), a p2p engine for hls.js powered by WebRTC Datachannel.
 
-## They use hls.js in production!
+### They use hls.js in production!
 
 |                                                                                                                                                              |                                                                                                                                                                         |                                                                                                                                                                |                                                                                                                                                                                                                                         |
 | :----------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
@@ -172,21 +181,6 @@ HTMLVideoElement control and events could be used seamlessly.
 |                       [<img src="https://streaming.cdn77.com/live-streaming-logo-dark.png" width="120">](https://streaming.cdn77.com/)                       |                                  [<img src="https://avatars0.githubusercontent.com/u/7442371?s=200&v=4" width="120">](https://r7.com/)                                  | [<img src="https://raw.githubusercontent.com/Novage/p2p-media-loader/gh-pages/images/p2pml-logo.png" width="120">](https://github.com/Novage/p2p-media-loader) |                                                              [<img src="https://avatars3.githubusercontent.com/u/45617200?s=400" width="120">](https://kayosports.com.au)                                                               |
 |    [<img src="https://avatars1.githubusercontent.com/u/5279615?s=400&u=9771a216836c613f1edf4afe71cfc69d4c5657ed&v=4" width="120">](https://flosports.tv)     |                                                                                                                                                                         |                                                                                                                                                                |                                                                                                                                                                                                                                         |
 
-## Player Integration
-
-hls.js is (being) integrated in the following players:
-
-- [Akamai Adaptive Media Player (AMP)](https://www.akamai.com/us/en/solutions/products/media-delivery/adaptive-media-player.jsp)
-- [Clappr](https://github.com/clappr/clappr)
-- [Flowplayer](https://www.flowplayer.org) through [flowplayer-hlsjs](https://github.com/flowplayer/flowplayer-hlsjs)
-- [MediaElement.js](https://www.mediaelementjs.com)
-- [Videojs](https://videojs.com) through [Videojs-hlsjs](https://github.com/benjipott/videojs-hlsjs)
-- [Videojs](https://videojs.com) through [videojs-hls.js](https://github.com/streamroot/videojs-hls.js). hls.js is integrated as a SourceHandler -- new feature in Video.js 5.
-- [Videojs](https://videojs.com) through [videojs-contrib-hls.js](https://github.com/Peer5/videojs-contrib-hls.js). Production ready plug-in with full fallback compatibility built-in.
-- [Fluid Player](https://www.fluidplayer.com)
-- [OpenPlayerJS](https://www.openplayerjs.com), as part of the [OpenPlayer project](https://github.com/openplayerjs)
-- [CDNBye](https://github.com/cdnbye/hlsjs-p2p-engine), a p2p engine for hls.js powered by WebRTC Datachannel.
-
 ## Chrome/Firefox integration
 
 made by [gramk](https://github.com/gramk/chrome-hls), plays hls from address bar and m3u8 links
@@ -197,9 +191,9 @@ made by [gramk](https://github.com/gramk/chrome-hls), plays hls from address bar
 ## Dependencies
 
 No external JS libs are needed.
-Prepackaged build is included [with the releases](https://github.com/video-dev/hls.js/releases).
+A prepackaged build is included [with each release](https://github.com/video-dev/hls.js/releases).
 
-If you want to bundle the application yourself, use node
+Hls.js can be installed as a dependency using npm:
 
 ```
 npm install hls.js
@@ -223,12 +217,6 @@ Or type
 npm install --save hls.js
 ```
 
-### Server-side-rendering (SSR) and `require` from a Node.js runtime
-
-We support this now. You can safely require this library in Node and absolutely nothing will happen :) See https://github.com/video-dev/hls.js/pull/1841
-
-(This is also known as "Universal builds" and "isomorphic apps")
-
 ## CORS
 
 All HLS resources must be delivered with [CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) permitting `GET` requests.
@@ -252,7 +240,7 @@ All HLS resources must be delivered with [CORS headers](https://developer.mozill
   - Widevine CDM (beta/experimental) (see Shaka-package test-stream in demo)
 - CEA-608/708 captions
 - WebVTT subtitles
-- Alternate Audio Track Rendition (Master Playlist with alternative Audio) for VoD and Live playlists
+- Alternate Audio Track Rendition (Master Playlist with Alternative Audio) for VoD and Live playlists
 - Adaptive streaming
   - Manual & Auto Quality Switching
     - 3 Quality Switching modes are available (controllable through API means)
@@ -263,29 +251,29 @@ All HLS resources must be delivered with [CORS headers](https://developer.mozill
 - Accurate Seeking on VoD & Live (not limited to fragment or keyframe boundary)
 - Ability to seek in buffer and back buffer without redownloading segments
 - Built-in Analytics
-  - Every internal events could be monitored (Network Events,Video Events)
+  - All internal events can be monitored (Network Events, Video Events)
   - Playback session metrics are also exposed
 - Resilience to errors
   - Retry mechanism embedded in the library
-  - Recovery actions could be triggered fix fatal media or network errors
+  - Recovery actions can be triggered fix fatal media or network errors
 - [Redundant/Failover Playlists](https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/StreamingMediaGuide/UsingHTTPLiveStreaming/UsingHTTPLiveStreaming.html#//apple_ref/doc/uid/TP40008332-CH102-SW22)
 
-## Not Supported (Yet)
-
-- MP3 Elementary Stream in Edge for Windows 10+
-
 ### Supported M3U8 tags
 
-For details on the HLS format and these tags meanings see https://tools.ietf.org/html/draft-pantos-hls-rfc8216bis-07
+For details on the HLS format and these tags' meanings, see https://tools.ietf.org/html/draft-pantos-hls-rfc8216bis-08
 
-Manifest tags
+#### Manifest tags
 
 - `#EXT-X-STREAM-INF:<attribute-list>`
   `<URI>`
 - `#EXT-X-MEDIA:<attribute-list>`
 - `#EXT-X-SESSION-DATA:<attribute-list>`
 
-Playlist tags
+The following properties are added to their respective variants' attribute list but are not implemented in their selection and playback.
+
+- `VIDEO-RANGE` and `HDCP-LEVEL` (See [#2489](https://github.com/video-dev/hls.js/issues/2489))
+
+#### Playlist tags
 
 - `#EXTM3U`
 - `#EXT-X-VERSION=<n>`
@@ -297,7 +285,7 @@ Playlist tags
 - `#EXT-X-DISCONTINUITY-SEQUENCE=<n>`
 - `#EXT-X-BYTERANGE=<n>[@<o>]`
 - `#EXT-X-MAP:<attribute-list>`
-- `#EXT-X-KEY:<attribute-list>`
+- `#EXT-X-KEY:<attribute-list>` (`METHOD=SAMPLE-AES` is only supports with MPEG-2 TS segments)
 - `#EXT-X-PROGRAM-DATE-TIME:<attribute-list>`
 - `#EXT-X-START:TIME-OFFSET=<n>`
 - `#EXT-X-SERVER-CONTROL:<attribute-list>`
@@ -306,10 +294,29 @@ Playlist tags
 - `#EXT-X-PRELOAD-HINT:<attribute-list>`
 - `#EXT-X-SKIP:<attribute-list>`
 - `#EXT-X-RENDITION-REPORT:<attribute-list>`
-- The following tags are added to their respective fragment's attribute list
-  - `#EXT-X-DATERANGE:<attribute-list>`
-  - `#EXT-X-BITRATE`
-  - `#EXT-X-GAP`
+
+The following tags are added to their respective fragment's attribute list but are not implemented in streaming and playback.
+
+- `#EXT-X-DATERANGE:<attribute-list>` (Not added to metadata TextTracks. See [#2218](https://github.com/video-dev/hls.js/issues/2218))
+- `#EXT-X-BITRATE` (Not used in ABR controller)
+- `#EXT-X-GAP` (Not implemented. See [#2940](https://github.com/video-dev/hls.js/issues/2940))
+
+### Not Supported
+
+For a complete list of issues, see ["Top priorities" in the Release Planning and Backlog project tab](https://github.com/video-dev/hls.js/projects/6). Codec support is dependent on the runtime environment (for example, not all browsers on the same OS support HEVC).
+
+- Multiple `#EXT-X-MAP` tag support [#2279](https://github.com/video-dev/hls.js/issues/2279)
+- CMAF CC support [#2623](https://github.com/video-dev/hls.js/issues/2623)
+- `Emsg` Inband Timed Metadata for FMP4 (ID3 within Emsgv1) in "metadata" TextTracks [#2360](https://github.com/video-dev/hls.js/issues/2360)
+- `#EXT-X-DATERANGE` in "metadata" TextTracks [#2218](https://github.com/video-dev/hls.js/issues/2218)
+- `#EXT-X-GAP` filling [#2940](https://github.com/video-dev/hls.js/issues/2940)
+- `SAMPLE-AES` with fmp4, aac, mp3, vtt... segments (MPEG-2 TS only)
+- Advanced variant selection based on runtime media capabilities (See issues labeled [`media-capabilities`](https://github.com/video-dev/hls.js/labels/media-capabilities))
+- MP3 elementary stream audio in IE and Edge (<=18) on Windows 10 (See [#1641](https://github.com/video-dev/hls.js/issues/1641) and [Microsoft answers forum](https://answers.microsoft.com/en-us/ie/forum/all/ie11-on-windows-10-cannot-play-hls-with-mp3/2da994b5-8dec-4ae9-9201-7d138ede49d9))
+
+### Server-side-rendering (SSR) and `require` from a Node.js runtime
+
+You can safely require this library in Node and **absolutely nothing will happen**. A dummy object is exported so that requiring the library does not throw an error. Hls.js is not instantiable in Node.js. See [#1841](https://github.com/video-dev/hls.js/pull/1841) for more details.
 
 ## License
 
@@ -319,7 +326,7 @@ hls.js is released under [Apache 2.0 License](LICENSE)
 
 Pull requests are welcome. Here is a quick guide on how to start.
 
-- First, checkout the repository and install required dependencies
+- First, checkout the repository and install the required dependencies
 
 ```sh
 git clone https://github.com/video-dev/hls.js.git

diff --git a/bower.json b/bower.json