rx-player 3.30.1-dev.2023032800 → 3.31.0-dev.2023052200

package/CHANGELOG.md

@@ -1,15 +1,27 @@
 # Changelog
 
-## v3.30.1-dev.2023032800 (2023-03-28)
+## v3.31.0-dev.2023052200 (2023-05-22)
+
+### Features
+
+  - Add `trackInfo` property to some `MediaError` to expose information on the track that caused the error [#1241]
 
 ### Bug fixes
 
   - DASH: Fix issue which could lead to infinite rebuffering when switching between multiple Periods [#1232]
   - Return actual ending duration through the `getVideoDuration` method when playing dynamic contents whose future end is already known [#1235]
+  - DASH/WASM: actually reject the `DASH_WASM.initialize`'s Promise if it fails [#1238]
+  - On the PlayStation 5, set `Infinity` MediaSource duration for live contents to prevent playback issues [#1250]
+  - DASH/WASM: actually reject the DASH_WASM.initialize's Promise if it fails [#1238]
 
 ### Other improvements
 
-  - adaptive: Perform various adaptive tweaks to avoid switching too much between qualities in some conditions
+  - adaptive: Perform various adaptive tweaks to avoid switching too much between qualities in some conditions [#1237]
+  - Directfile: Detect "forced" subtitles on Safari when playing directfile contents (such as HLS) [#1239]
+  - DRM: Reload when playback is unexpectedly frozen with encrypted but only decipherable data in the buffer [#1236]
+  - Improve `"direct"` `audioTrackSwitchingMode` compatibility by re-seeking [#1246]
+  - The `DEBUG_ELEMENT` feature now uses the `monospace` fallback font as a default for a better rendering on apple devices
+  - doc: externalize documentation-generator code
 
 
 ## v3.30.0 (2023-03-07)

package/CONTRIBUTING.md

@@ -1,32 +1,6 @@
-# Contributing to the RxPlayer #################################################
-
-## Table of contents ###########################################################
-
-- [Issues and new features](#issues)
-- [Reading the current code](#reading)
-- [Code style](#code)
-    - [Linting](#code-lint)
-    - [Types](#code-types)
-    - [Forbidden functions and classes](#code-forbidden)
-- [Starting the demo page](#demo)
-  - [Building the demo and serving it](#demo-running)
-  - [Using HTTPS](#demo-https)
-- [Creating a commit](#commit)
-  - [Checks](#commit-checks)
-  - [Convention](#commit-name)
-- [The test suite](#testing)
-  - [Unit tests](#testing-unit)
-  - [Integration tests](#testing-integration)
-  - [Memory tests](#testing-memory)
-- [Documentation](#doc)
-- [Opening a pull request](#pr)
-  - [Checks](#pr-checks)
-  - [Which branch to merge to](#pr-branch)
-
-
-
-<a name="issues"></a>
-## Issues and new features #####################################################
+# Contributing to the RxPlayer
+
+## Issues and new features
 
 If you detect a problem with the RxPlayer, or if you desire a new feature,
 please first [open an issue on the github's
@@ -38,12 +12,11 @@ Those have to follow the conventions defined below.
 
 
 
-<a name="reading"></a>
-## Reading the current code ####################################################
+## Reading the current code
 
 Even if we hope the current code is straightforward, readable and commented
 enough we can still admit that going blind into the codebase can be hard at
-first (as it would be for any non-small codebase).
+first as this is a pretty big technical project on a specific matter.
 
 We thus encourage you to rely on the architecture documentation you can usually
 find alongside the code, in `README.md` files.
@@ -51,7 +24,7 @@ You can for example start by reading `src/README.md`, to have a clearer idea
 of the general code architecture of the player.
 
 Also, for a more exhaustive approach to the documentation of the project's file
-organization, you can look at `FILES.md` at the root of this repository.
+organization, you can look at [`FILES.md`](./FILES.md).
 
 The code of the RxPlayer being heavily modularized, you should not need to read
 the whole documentation to be ready, only the parts you want to update
@@ -59,18 +32,17 @@ the whole documentation to be ready, only the parts you want to update
 
 
 
-<a name="code"></a>
-## Code style ##################################################################
+## Code style
 
-<a name="code-lint"></a>
-### Linting ####################################################################
+### Linting
 
 The code style in `src` is automatically checked by a "linter", `eslint`.
 
 It basically follows those principles:
   - 2 spaces indentation
   - 90 columns maximum
-  - optimize your code for readability
+  - readability and being explicit is generally better than performance and
+    being smart
 
 You can easily check if you followed our style rules by calling `npm run lint`.
 
@@ -79,10 +51,9 @@ calling `npm run lint:demo`, or the style of the test files (in the `tests`
 directory) by calling `npm run lint:tests`.
 
 
-<a name="code-types"></a>
-### Types ######################################################################
+### Types
 
-#### General TypeScript rules ##################################################
+#### General TypeScript rules
 
 We try to be as strict as possible with types:
 
@@ -91,9 +62,6 @@ We try to be as strict as possible with types:
   - the `as` TypeScript keyword, used for type casting, should also be avoided
     as much as possible.
 
-  - the `is` keyword is fine in some situations, but simpler solutions should be
-    preferred.
-
 This is to be sure we can detect as much as possible type errors automatically
 with TypeScript.
 
@@ -101,7 +69,7 @@ with TypeScript.
 
 TypeScript's `type` and `interface` should all be named beginning with the
 letter `I`, for easier identification purposes\*:
-```
+```ts
 interface IMyObject {
   someKey: string;
 }
@@ -110,88 +78,48 @@ type IStringOrNumber = string |
                        number;
 ```
 
-\*We know that this rule is a controversial subject amongst TypeScript
-developpers, yet we still decide to enforce it for now.
-
-#### Generic parameters typing #################################################
-
-Generic parameters are usually named in order `T` (for the first generic
-parameter), then `U` (if there's two), then `V` (if there's three):
-
-Examples:
-```
-type IMyGenericType<T> = Array<T>;
-
-type IMyGenericType2<T, U> = Promise<T> |
-                             U;
-
-function mergeThree<T, U, V>(
-  arg1: T,
-  arg2: U,
-  arg3: V
-) : T & U & V {
-  return Object.assign({}, arg1, arg2, arg3);
+`enum`s and `const enum`s, which have the particularity in TypeScript of
+actually having an influence on the outputed code, do not follow this rule
+however (because those are not just types erased during transpilation):
+```ts
+enum MyEnum {
+  ValueA = 1,
+  ValueB = 2,
 }
-```
 
-Some exceptions exist like for things like key-values couples, which can be named
-respectively `K` and `V`:
-```
-type IMyMap<K, V> = Map<K, V>;
-```
-
-This is a general convention for generic parameters inherited from Java, and
-re-used by TypeScript, and it helps identifying which type is a generic
-parameter vs which type is a real type (no prefix) vs which type is a type
-definition (prefixed by `I`).
-
-If what they correspond to is not obvious (and if there's more than one, it
-might well be), you're encouraged to add a more verbose and clear name, that you
-should prefix by `T`:
-```
-function loadResource<TResourceFormat>(
-  url : string
-) : Promise<TResourceFormat> {
-  // ...
+const enum MyConstEnum {
+  Value1 = 1,
+  Value2 = 2,
 }
 ```
 
-However note that typing rules for generic parameters is a very minor
-consideration and may not always need to be respected depending on the code it
-is applied on.
-In the end, it will be up to the RxPlayer's maintainers to decide that those
-rules should be enforced or not on a given code.
-
+\*We know that this rule is a controversial subject amongst TypeScript
+developpers, yet we still decide to enforce it for now.
 
-<a name="code-forbidden"></a>
-### Forbidden functions and classes ############################################
+### Forbidden functions and classes
 
 Some native functions, methods or classes should never be used to ensure
-compatibility with every browsers. To work around those, we usually rely on
+compatibility with most browsers. To work around those, we usually rely on
 "ponyfills" which are JavaScript re-implementations.
 
 This concerns the following static methods:
   - `Object.assign`: use `src/utils/object_assign.ts` instead
   - `Object.values`: use `src/utils/object_values.ts` instead
 
-The following methods:
+And the following methods:
   - `Array.prototype.includes`: use `src/utils/array_includes.ts` instead
   - `Array.prototype.find`: use `src/utils/array_find.ts` instead
   - `Array.prototype.findIndex`: use `src/utils/array_find_index.ts` instead
   - `String.prototype.startsWith`: use `src/utils/starts_with.ts` instead
   - `String.prototype.substr`: use `String.prototype.substring` instead
   - `NodeList.prototype.forEach`: use a regular for loop instead
-
-The following class:
-  - `Promise`: use `src/utils/promise.ts` instead
+  - `Promise.prototype.finally`: Use `then` or both `then` and `catch` of that
+    Promise's methods instead.
 
 
+## The demo page
 
-<a name="demo"></a>
-## Starting the demo page ######################################################
-
-<a name="demo-running"></a>
-### Building the demo and serving it ###########################################
+### Building the demo and serving it
 
 You might want to quickly test your code modification(s) on a real use case.
 
@@ -227,10 +155,10 @@ npm run standalone
 
 Both will detect when the RxPlayer's files (or even the demo files) are updated
 and perform a new build when that's the case. In that way, the server will
-always serve the last local version of the code.
+always serve the last local version of the code. Note however that hot-reload is
+not enabled currently, you'll have to refresh the page yourself.
 
-<a name="demo-https"></a>
-### Serving the demo page through HTTPS ########################################
+### Serving the demo page through HTTPS
 
 You might want to serve the demo via HTTPS. This is for example needed to be
 able to play encrypted contents in Chrome.
@@ -252,52 +180,18 @@ when going to one of the demo pages in HTTPS. In most browsers, you can however
 safely ignore that warning.
 
 
-<a name="commit"></a>
-## Creating a commit ###########################################################
+## Creating a commit
 
-<a name="commit-checks"></a>
-### Checks #####################################################################
+### Checks
 
-Every commits in a PR should pass our quick checks (linter, typescript check
-and unit tests). To check if that's the case, you can run locally the `check`
+Every commits in a PR should pass our quick checks (linter and TypeScript
+check). To check if that's the case, you can run locally the `check`
 script by calling `npm run check`.
 
-Those checks give us some guarantees that every merged commit in the `master`
-branch is stable enough.
-
-This gives us more confidence on our code and also allows  more advanced
-debugging if we detect a regression by the usage of tools such as git-bisect.
-
-
-<a name="commit-name"></a>
-### Convention #################################################################
-
-When creating a new commit it is advised (though not enforced) to add a message
-containing multiple paragraphs.
-
-The first paragraph should be a short summary of what the commit does, short
-enough so it can usually be displayed on one line - probably like the usual
-commit messages you are used to.
-The following paragraphs can be as long as you want (note that relying on a
-[maximum column width of around 72 is a sensible
-default](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
-even if we do not enforce that either).
 
-The goal here is to help understand your changes at a later time, in case things
-go wrong in the future.
+## The test suite
 
-_You can create a commit with multiple paragraphs either through the command
-line either by setting multiple `-m` options to git-commit, or just by calling
-`git commit` with no `-m` option and editing the message manually in the opened
-editor._
-
-
-
-<a name="testing"></a>
-## The test suite ##############################################################
-
-<a name="testing-unit"></a>
-### Unit tests #################################################################
+### Unit tests
 
 Unit tests test function implementations. Mostly to check if they give a sane
 output for every input given.
@@ -307,15 +201,14 @@ Writing unit tests for new code is encouraged.
 Unit tests are written in a \_\_tests\_\_ directory, itself created in the same
 directory that the code it tests.
 
-They are written with the help of the Jest library and are named the following
-way: `filename_containing_the_function_tested.test.ts`.
+They are written and run with the help of the Jest library and are named the
+following way: `filename_containing_the_function_tested.test.ts`.
 
 To understand how to create a new test file, you can take inspiration from
 the current unit tests.
 
 
-<a name="testing-integration"></a>
-### Integration tests ##########################################################
+### Integration tests
 
 What we call integration tests are tests testing the entire API of the RxPlayer.
 
@@ -332,8 +225,7 @@ If you want to know how it works, we invite you to rely on the already created
 tests and to read the corresponding files.
 
 
-<a name="testing-memory"></a>
-### Memory tests ###############################################################
+### Memory tests
 
 Memory tests replicate simple scenarios and try to detect memory leaks.
 
@@ -342,8 +234,7 @@ You can also help us improving our memory tests. Those are written in
 
 
 
-<a name="doc"></a>
-## Documentation ###############################################################
+## Documentation
 
 The documentation is written in the `doc` directory, at the root of the project.
 
@@ -353,20 +244,9 @@ calling the `doc` script through `npm run doc`.
 
 
 
-<a name="pr"></a>
-## Opening a pull request ######################################################
-
-<a name="pr-checks"></a>
-### Checks #####################################################################
-
-Before doing a Pull Request, please ensure that all integration tests pass by
-calling `npm run test:integration`.
-
-Then, please call `npm run test:memory`, which tests for memory leaks.
-
+## Opening a pull request
 
-<a name="pr-branch"></a>
-### Which branch to merge to ###################################################
+### Which branch to merge to
 
 Pull requests for bug fixes, new tests or documentation should be done on the
 `master` branch.

package/FILES.md

@@ -1,44 +1,14 @@
-# File architecture ############################################################
+# File architecture
 
 This page describes how the player files are organized. Each chapter go through
 a single directory or subdirectory, in alphabetical order.
 
 
-## Table of Contents ###########################################################
-
-- [demo/: Demos of rx-player implementations](#demo)
-- [dist/: Player builds](#dist)
-- [doc/: Player documentation](#doc)
-- [scripts/: Tools and scripts](#scripts)
-- [src/: the source code](#src)
-  - [src/compat/: The compatibility files](#src-compat)
-  - [src/core/: The core files](#src-core)
-  - [src/errors/: Error definitions](#src-errors)
-  - [src/experimental/: Experimental features](#src-experimental)
-  - [src/features/: Feature switching](#src-features)
-  - [src/manifest/: The Manifest class](#src-manifest)
-  - [src/transports/: The transport protocols](#src-transports)
-  - [src/parsers/: The parsing files](#src-parsers)
-  - [src/typings/: Typescript typings](#src-typings)
-  - [src/utils/: The utils](#src-utils)
-- [src/core/: The core directory](#core)
-  - [src/core/adaptive/: The adaptive bitrate code](#core-abr)
-  - [src/core/api/: The API definition](#core-api)
-  - [src/core/stream/: Load the right segments](#core-stream)
-  - [src/core/decrypt/: Decryption management](#core-decrypt)
-  - [src/core/fetchers/: The fetchers](#core-fetchers)
-  - [src/core/segment_buffers/: The Media buffers](#core-sb)
-  - [src/core/init/: Media streaming logic](#core-init)
-- [src/**/__tests__: the unit tests directories](#src-tests)
-- [tests/: the player's tests](#tests)
-
-
-<a name="demo"></a>
-## The demo/ directory: Demos of rx-player implementations #####################
-
-Demonstration of functional codebases implementing the rx-player.
-
-At the time of writing, there are two demos:
+## `demo/`: Demo applications
+
+The `demo/` directory contains demos of application using the RxPlayer.
+
+At the time of writing, there are two distinct demos:
 
   - _full_: Demo with a graphic interface, written with the React library, to
     showcase what the player can do
@@ -48,36 +18,35 @@ At the time of writing, there are two demos:
     the displayed page.
 
 
-<a name="dist"></a>
-## The dist/ directory: Player builds ##########################################
+## `dist/`: Builds
 
-Store the player builds of the last version released.
+The `demo/` directory stores the player builds of the last version released.
 
-Contains two files: the minified (``rx-player.min.js``) and the non-minified
-files (``rx-player.js``). Both are automatically generated with scripts at every
-new release.
+Contains the minified (``rx-player.min.js``) and the non-minified files
+(``rx-player.js``). Both are automatically generated with scripts at every new
+release.
 
 Two directories, namely ``_esm5.raw`` and ``_esm5.processed`` can also be
 generated in here if the right scripts are called.
 These allow to publish more modular codebases to npm.
 
 
-<a name="doc"></a>
-## The doc/ directory: Player documentation ####################################
+## `doc/`: Documentation
 
-Documentation, mostly in markdown, of various subjects related to the rx-player:
+The `doc/` directory contains the RxPlayer's documentation, mostly written in
+markdown, on various subjects related to the rx-player:
   - API documentation
   - tutorials
   - list of deprecated APIs...
   - how to transition between RxPlayer versions
+  - how to contribute
   - etc.
 
 
-<a name="scripts"></a>
-## The scripts/ directory: scripts #####################################
+## `scripts/`: Project-managing scripts
 
-Contains various scripts used to help the test and the management of the player
-code.
+The `scripts/` directory contains various scripts used to help the test and the
+management of the player code.
 
 For example:
   - generating one of the demo and starting the server to run it
@@ -86,16 +55,14 @@ For example:
   - generating the rx-player build before publishing on npm
 
 
-<a name="src"></a>
-## The src/ directory: the source code #########################################
+## `src/`: The source code
 
-The src contains the entire source code of the rx-player.
+The `src` directory contains the entire source code of the rx-player.
 
 It is subdivized into subdirectories which are defined here.
 
 
-<a name="src-compat"></a>
-### src/compat/: The compatibility files #######################################
+### `src/compat/`: Compatibility files
 
 ``src/compat`` contains functions allowing to use browser APIs in a
 cross-browser manner.
@@ -110,8 +77,7 @@ Every functions needed in the rest of the code are exported in
 ``import { whatINeed } from "../compat";``)
 
 
-<a name="src-core"></a>
-### src/core/: The core files ##################################################
+### `src/core/`: Core logic
 
 Defines the logic and behavior of the player, regardless of the browser and of
 the streaming technology used.
@@ -126,22 +92,19 @@ This directory contains other subdirectories which are listed in the next
 chapter.
 
 
-<a name="src-errors"></a>
-### src/errors/: Error definitions #############################################
+### `src/errors/`: Error definitions
 
 Contains the definition of the error classes used in the rx-player and
 accessible through the API.
 
 
-<a name="src-experimental"></a>
-### src/experimental/: Experimental features ###################################
+### `src/experimental/`: Experimental features
 
 You will find here experimental features. Those are tested features who might
 completely change their API in new player versions.
 
 
-<a name="src-features"></a>
-### src/features/: Feature switching ###########################################
+### `src/features/`: Feature switching
 
 This manage activated or deactivated features (e.g. DASH, TTML subtitles
 parsing).
@@ -150,16 +113,14 @@ It exports an object defining the different activated features and provide utils
 to initialize and update them.
 
 
-<a name="src-manifest"></a>
-### src/manifest/: The Manifest class ##########################################
+### `src/manifest/`: Manifest Object definition
 
 Defines a common `Manifest` class, regardless of the streaming technology (DASH,
 HSS...). This class is then used by the rest of the RxPlayer, to allow
 interaction with it without considering the underlying technology used.
 
 
-<a name="src-transports"></a>
-### src/transports/: The transport protocols ###################################
+### `src/transports/`: Streaming protocols implementation
 
 Defines a common interface for multiple streaming technologies (DASH, HSS).
 
@@ -175,8 +136,7 @@ As in most of the code of the rx-player, everything used in the other parts of
 the code is exported in the index.js file at the root of this directory.
 
 
-<a name="src-parsers"></a>
-### src/parsers/: The parsers ##################################################
+### `src/parsers/`: The parsers
 
 Functions to parse various formats into the same interface.
 
@@ -187,22 +147,19 @@ The parsed data being either:
   - image containers: BIF
 
 
-<a name="src-typings"></a>
-### src/typings/: Typescript typings ###########################################
+### `src/typings/`: Typescript typings
 
 This directory contains only declaration files for TypeScript. It is
 automatically added as a `typeRoots` when the TypeScript code is transpiled.
 
 
-<a name="src-utils"></a>
-### src/utils/: The utils ######################################################
+### `src/utils/`: Util functions
 
 This directory contains general helpers which are used in different parts of the
 rx-player code.
 
 
-<a name="core"></a>
-## The src/core/ directory #####################################################
+## Inside `src/core/`
 
 As written in the previous chapter, this is the "core" of the player, where the
 logic is defined.
@@ -210,8 +167,7 @@ logic is defined.
 As this directory is versatile and complicated, it also deserves its own chapter.
 
 
-<a name="core-abr"></a>
-### src/core/adaptive/: The adaptive bitrate code ##############################
+### `src/core/adaptive/`: Adaptive BitRate logic
 
 Defines functions which manages the adaptive streaming part of the player.
 
@@ -226,29 +182,25 @@ This allows to isolate this complex part and facilitate future refactoring and
 improvements.
 
 
-<a name="core-api"></a>
-### src/core/api/: The API definition ##########################################
+### `src/core/api/`: API definition
 
 Defines the rx-player API. This is the part the library user will directly
 interact with.
 
 
-<a name="core-stream"></a>
-### src/core/stream/: Load the right segments ##################################
+### `src/core/stream/`: Segment-picking logic
 
 The code there calculate which segments should be downloaded, ask for their
 download and push the segments into the `SegmentBuffers`.
 
 
-<a name="core-decrypt"></a>
-### src/core/decrypt/: Decryption management ###################################
+### `src/core/decrypt/`: Decryption handling
 
 Defines functions allowing to handle encrypted contents through the EME browser
 APIs.
 
 
-<a name="core-fetchers"></a>
-### src/core/fetchers/: The fetchers ###########################################
+### `src/core/fetchers/`: Load resources
 
 Handle the segments and Manifest downloading pipelines (load and parse) as
 defined in the ``src/transports/`` directory.
@@ -258,8 +210,7 @@ It facilitates the role of loading the Manifest and new segments for the rest of
 the core.
 
 
-<a name="core-sb"></a>
-### src/core/segment_buffers/: The media buffers ###############################
+### `src/core/segment_buffers/`: Media buffers
 
 Code allowing to interact with the media buffers called `SegmentBuffers`.
 
@@ -272,8 +223,7 @@ for other type of contents (like subtitles), we rely on completely custom media
 buffers implementations.
 
 
-<a name="core-init"></a>
-### src/core/init/: Content initialization #####################################
+### `src/core/init/`: Content initialization and orchestration
 
 This is the central part which download manifests, initialize MSE and EME APIs,
 instanciate the central `StreamOrchestrator` (which will allow to download and
@@ -281,8 +231,7 @@ push segments so the content can play) and link together many subparts of the
 player.
 
 
-<a name="src-tests"></a>
-## src/**/__tests__: the unit tests directories ################################
+## `src/**/__tests__`: Unit tests
 
 You will find multiple directories named `__tests__` in the RxPlayer.
 Those contain unit tests and are put in the same directory than the code it
@@ -304,8 +253,7 @@ Their filename don't follow the same convention than single-source unit tests
 but should still be suffixed by `.test.ts`.
 
 
-<a name="tests"></a>
-## The tests/ directory: the player's tests ####################################
+## `tests/`: The RxPlayer's general tests
 
 This directory contains most testing code for the RxPlayer.