rx-player 4.1.0-dev.2024040900 → 4.1.0-dev.2024070800

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rx-player",
   "author": "Canal+",
-  "version": "4.1.0-dev.2024040900",
+  "version": "4.1.0-dev.2024070800",
   "description": "Canal+ HTML5 Video Player",
   "main": "./dist/commonjs/index.js",
   "module": "./dist/es2017/index.js",
@@ -145,17 +145,18 @@
     "build:dev": "./scripts/generate_build.mjs --dev-mode",
     "build:wasm:debug": "mkdir -p dist && cd ./src/parsers/manifest/dash/wasm-parser && cargo build --target wasm32-unknown-unknown && cp target/wasm32-unknown-unknown/debug/mpd_node_parser.wasm ../../../../../dist/mpd-parser.wasm",
     "build:wasm:release": "./scripts/build_wasm_release.sh",
-    "bundle": "webpack --progress --config webpack.config.mjs --env production",
-    "bundle:min": "webpack --progress --config webpack.config.mjs --env minify --env production",
-    "bundle:min:watch": "webpack --progress --config webpack.config.mjs -w --env production --env minify",
-    "bundle:watch": "webpack --progress --config webpack.config.mjs -w --env production",
+    "bundle": "./scripts/run_bundler.mjs src/index.ts --production-mode -o dist/rx-player.js",
+    "bundle:min": "./scripts/run_bundler.mjs src/index.ts --production-mode -o dist/rx-player.js --minify",
+    "bundle:min:watch": "./scripts/run_bundler.mjs src/index.ts --production-mode -o dist/rx-player.js --minify --watch",
+    "bundle:watch": "./scripts/run_bundler.mjs src/index.ts --production-mode -o dist/rx-player.js --watch",
     "certificate": "./scripts/generate_certificate",
-    "check": "npm run check:types && npm run lint",
+    "check": "npm run check:types && npm run lint && npm run check:types:unit_tests",
     "check:all": "npm run check:types && npm run lint && npm run lint:demo && npm run lint:tests && npm run test:unit && npm run test:integration && npm run test:memory && node -r esm ./scripts/check_nodejs_import_compatibility.js",
     "check:demo": "npm run check:demo:types && npm run lint:demo",
     "check:demo:types": "tsc --noEmit --project demo/full",
     "clean:build": "rimraf dist",
     "check:types": "tsc --noEmit --project .",
+    "check:types:unit_tests": "tsc --noEmit --project ./tsconfig.unit-tests.json",
     "check:types:watch": "tsc --noEmit --watch --project .",
     "clean:wasm": "rimraf dist/mpd-parser.wasm && rimraf ./src/parsers/manifest/dash/wasm-parser/target",
     "demo": "node ./scripts/build_demo.mjs --production-mode",
@@ -175,15 +176,15 @@
     "standalone": "node ./scripts/run_standalone_demo.mjs",
     "start": "node ./scripts/start_demo_web_server.mjs",
     "start:wasm": "node ./scripts/start_demo_web_server.mjs --include-wasm",
-    "test:integration": "node tests/integration/run.mjs --bchromehl --bfirefoxhl",
-    "test:integration:chrome": "node tests/integration/run.mjs --bchrome",
-    "test:integration:chrome:watch": "node tests/integration/run.mjs --bchrome --watch",
-    "test:integration:firefox": "node tests/integration/run.mjs --bfirefox",
-    "test:integration:firefox:watch": "node tests/integration/run.mjs --bfirefox --watch",
-    "test:memory": "node tests/memory/run.mjs --bchromehl",
-    "test:memory:chrome:watch": "node tests/memory/run.mjs --bchrome --watch",
-    "test:unit": "jest --maxWorkers=5",
-    "test:unit:coverage": "jest --coverage",
+    "test:integration": "npm run test:integration:chrome && npm run test:integration:firefox",
+    "test:integration:chrome": "cross-env BROWSER_CONFIG=chrome vitest run tests/integration/scenarios",
+    "test:integration:chrome:watch": "cross-env BROWSER_CONFIG=chrome vitest watch tests/integration/scenarios",
+    "test:integration:firefox": "cross-env BROWSER_CONFIG=firefox vitest run tests/integration/scenarios",
+    "test:integration:firefox:watch": "cross-env BROWSER_CONFIG=firefox vitest watch tests/integration/scenarios",
+    "test:memory": "cross-env BROWSER_CONFIG=chrome vitest run tests/memory",
+    "test:memory:chrome:watch": "cross-env BROWSER_CONFIG=chrome vitest watch tests/memory",
+    "test:unit": "vitest --config vitest.config.unit.mjs",
+    "test:unit:watch": "cross-env WATCH=true vitest --config vitest.config.unit.mjs",
     "update-version": "npm run version --git-tag-version=false",
     "version": "./scripts/update-version",
     "wasm-strip": "node scripts/wasm-strip.mjs dist/mpd-parser.wasm"
@@ -193,24 +194,15 @@
     "url": "git://github.com/canalplus/rx-player.git"
   },
   "devDependencies": {
-    "@babel/core": "7.23.6",
-    "@babel/plugin-transform-runtime": "7.23.6",
-    "@babel/preset-env": "7.23.6",
-    "@babel/preset-react": "7.23.3",
     "@canalplus/readme.doc": "0.5.0",
-    "@types/chai": "4.3.11",
-    "@types/jest": "29.5.11",
-    "@types/mocha": "10.0.6",
     "@types/react": "18.2.45",
     "@types/react-dom": "18.2.18",
     "@types/sinon": "17.0.2",
-    "@typescript-eslint/eslint-plugin": "6.16.0",
-    "@typescript-eslint/eslint-plugin-tslint": "6.16.0",
-    "@typescript-eslint/parser": "6.16.0",
-    "arraybuffer-loader": "1.0.8",
-    "babel-loader": "9.1.3",
-    "chai": "4.3.10",
+    "@typescript-eslint/eslint-plugin": "^7.11.0",
+    "@typescript-eslint/parser": "^7.11.0",
+    "@vitest/browser": "^1.6.0",
     "core-js": "3.34.0",
+    "cross-env": "^7.0.3",
     "esbuild": "0.19.10",
     "eslint": "8.56.0",
     "eslint-config-prettier": "^9.1.0",
@@ -219,32 +211,18 @@
     "eslint-plugin-jsdoc": "46.9.1",
     "eslint-plugin-react": "7.33.2",
     "esm": "3.2.25",
-    "express": "^4.19.2",
     "github-buttons": "2.27.0",
     "html-entities": "2.4.0",
-    "jest": "29.7.0",
-    "jest-environment-jsdom": "29.7.0",
-    "karma": "6.4.2",
-    "karma-chrome-launcher": "3.2.0",
-    "karma-firefox-launcher": "2.1.2",
-    "karma-mocha": "2.0.1",
-    "karma-webpack": "5.0.0",
-    "mocha": "10.2.0",
-    "mocha-loader": "5.1.5",
     "prettier": "^3.2.4",
-    "raw-loader": "4.0.2",
     "react": "18.2.0",
     "react-dom": "18.2.0",
     "regenerator-runtime": "0.14.1",
     "rimraf": "5.0.5",
     "semver": "7.5.4",
     "sinon": "17.0.1",
-    "terser-webpack-plugin": "5.3.9",
-    "ts-jest": "29.1.1",
-    "ts-loader": "9.5.1",
     "typescript": "5.3.3",
-    "webpack": "^5.90.3",
-    "webpack-cli": "^5.1.4"
+    "vitest": "^1.6.0",
+    "webdriverio": "^8.38.2"
   },
   "scripts-list": {
     "Build a demo page (e.g. to test a code change)": {
@@ -282,7 +260,7 @@
       },
       "Unit tests (test particular functions)": {
         "test:unit": "Launch unit tests",
-        "test:unit:coverage": "Launch unit tests and produce a coverage report"
+        "test:unit:watch": "Launch unit tests and restart them each one of its file changes"
       },
       "Memory tests (test memory usage to avoid memory leaks)": {
         "test:memory": "Launch memory tests",

package/src/README.md

@@ -0,0 +1,364 @@
+# RxPlayer Architecture documentation
+
+## Preliminary notes
+
+You will find the architecture documentation alongside the code it documents, as
+`README.md` files (like this one).
+
+## Global architecture
+
+The RxPlayer may either run in a multithreaded "mode" or a monothreaded one depending on
+how it is configured. To easily allow for both, files containing its main logic are
+principally organized between two directories:
+
+- `./main_thread` contains code that will always run in the main JS thread regardless of
+  the RxPlayer's current mode.
+
+- `./core` contains code that may either run in a separate Worker thread (in the
+  multithreaded mode) or in main thread (in monothreaded mode).
+
+There are also several other files and directories those two may depend on.
+
+To better understand the player's architecture, you can find below a simplified schema for
+it:
+
+``````
+               +---------------------------------------------+
+               |                                             |
+               |               Application/UI                |
+               |                                             |
+               +---------------------------------------------+
+                         |
+                         | call RxPlayer API
+                         |
+-------------------------|- RxPlayer Main Thread ---------------------------
+                         |
+     Front-facing API    v
+     +---------------------------------------+    +--------------------+
+     |               Public API              |uses|     TracksStore    |
+     |          (./main_thread/api)          |--->|(./main_thread/track|
+     +---------------------------------------+    |s_store)            |
+                 |                                +--------------------+
+                 |                                 Facilitate track switching
+ Initialize      | creates                         for the API
+ playback and    |
+ create/connect  |        Negotiate content
+ modules         v        decryption
+ +--------------------+   +-----------------------+
+ |                    |   |   Content Decryptor   |       Renders text
+ |      Content       |-->|(./main_thread/decrypt)|       tracks to the
+ |    Initializer     |   +-----------------------+       DOM
+ |                    |                             +------------------+
+ |(./main_thread/init)|            creates          |  Text Displayer  |
+ |                    | --------------------------->|(./main_thread/te |
+ +--------------------+                             |xt_displayer)     |
+        |  ^                                        +------------------+
+        |  | Message exchanges                                          ^
+        |  |                                                            |
+--------|--|------ RxPlayer Core (May run in a WebWorker) --------------|---
+        v  |                                                            |
+  +---------------------------+         +----------------------------+  |
+  |                           | creates |                            |  |
+  |        Worker Main*       |-------->|       Manifest Fetcher     |  |
+  |   (./core/main/worker)    |         | (./core/fetchers/manifest) |  |
+  |                           |         |                            |  |
+  +---------------------------+         +----------------------------+  |
+  (*Only if running in a   |            Load and     |                  |
+  WebWorker)               |            refresh the  | Ask to load      |
+  Exchange messages with   |            Manifest     | and parse the    |
+  the main thread and      |                         | Manifest         |
+  process them.            |                         v                  |
+                           |        +--------------------+              |   ` Internet
+                           |        |                    |   request    |   `    ,,,,,
+                           |        |      transport     |--------------+---`-->( CDN )
+                   creates |        | (./core/transport) |              |   `    `````
+                           |        |                    |<---+         |   `
+                           |        +--------------------+     \        |
+                           |        Abstract the streaming      \       |
+                           |        protocol (e.g. DASH)         \      |
+                           |                                      \     |
+Stream (./core/stream)     |                                       \    |
++--------------------------|-------------------------------+        \   |
+|                          v                               |         \  +
+| Create the right        +----------------------------+   |    Ask to\  \
+| PeriodStreams depending |      StreamOrchestrator    |   |    load   \  \
+| on the current position,|(./core/stream/orchestrator)|   |    and     \  \
+| and settings            +----------------------------+   |    parse    \  \
+|                          |            |            |     |    segments  \  \
+|                          | creates    |            |     |               \  \
+|                          |            |            |     |                \  +
+|                 (audio)  v    (video) v     (text) v     |                 + |
+| Create the right +--------+   +--------+    +--------+ uses+------------+  | |
+| AdaptationStream |        |   |        |    |        |---->|SegmentSinks|  | |
+| depending on the | Period |-+ | Period |-+  | Period |-+ | |    Store   |  | |
+| wanted track     | Stream | | | Stream | |  | Stream | | | |(./core/segm|  | |
+| (One per Period  |        | | |        | |  |        | | | |ent_sinks)  |  | |
+| and one per type +--------+ | +--------+ |  +--------+ | | +------------+  | |
+| of media)         |         (./core/stream/period)     | | Create one      | |
+|                   +---------+  +---------+   +---------+ | "sink" per      | |
+|                          |            |             |    | type of media   | |
+|                          | creates    |             |    |                 | |
+|                          |            |             |    |                 | |
+|                          |            |             |    |                 | |
+|                  (audio) v    (video) v     (text)  v  uses+------------+  | |
+|                  +--------+   +--------+    +--------+ --|>|    ARS*    |  | |
+| (Adaptation-     |        |   |        |    |        |   | |(./core/adap|  | |
+| Stream)          |Adapt...|-+ |Adapt...|-+  |Adapt...|-+ | |tive)       |  | |
+| Create the right | Stream | | | Stream | |  | Stream | | | +------------+  | |
+| Representation-  |        | | |        | |  |        | | | *Adaptive       | |
+| Stream depending +--------+ | +--------+ |  +--------+ | | Representation  | |
+| on the current   |        (./core/stream/adaptation)   | | Selector:       | |
+| network,         +---------+  +---------+   +----------+ | Find the best   | |
+| settings...              |            |            |     | Representation  | |
+|                          | creates    |            |     | to play         | |
+|                          |            |            |     |                 | |
+|                          |            |            |     |                 | |
+|                  (audio) v    (video) v     (text) v   uses                | |
+|                  +--------+   +--------+    +--------+ --->+-------------+ | |
+| (Representation- |        |   |        |    |        |   | |   Segment   | | |
+| Stream).         |Repre...|-+ |Repre...|-+  |Repre...|-+ | |   fetcher   |-+ |
+| Download and push| Stream | | | Stream | |  | Stream | | | |(./core/fetc |   |
+| segments based on|        | | |        | |  |        | | | |hers/segment)|   |
+| the current      +--------+ | +--------+ |  +--------+ | | +-------------+   |
+| position and      |     (./core/stream/representation)   | Load media        |
+| buffer state      +---------+  +---------+   +---------+ | segments          |
+|                         |               |              | |                   |
++-------------------------|---------------|--------------|-+                   |
+                          |               |              |                     |
+                          | push media    |              |        add subtitle |
+                          | data          |              |                     |
+                          |               |              |                     |
+                +---------|---------------|--------------|-------+             |
+                |  (audio)v        (video)v        (text)v       |             |
+                |  +------------+  +------------+  +-----------+ |             |
+ Media sinks on |  | Audio/Video|  | Audio/Video|  |   Text    | |             |
+ which media    |  |   Segment  |  |   Segment  |  |  Segment  | |             |
+ data to decode |  |    Sink    |  |    Sink    |  |   Sink    | |             |
+ is pushed.     |  +------------+  +------------+  +-----------+ |             |
+ Also maintain  |        |               |               |       |             |
+ an inventory   |  SegmentSink implementations           |       |             |
+ and history of |  (./core/segment_sinks/implementations)|       |             |
+ pushed media   +--------|---------------|---------------|-------+             |
+                         |               |               |                     |
+                         | push media    |               |                     |
+                         | data          |               |                     |
+                         |               |               |                     |
+                  (audio)V        (video)V         (text)V                     |
+                    +-----------------------+  +-------------------------+     |
+  Actually pushes   |      MediaSource      |  |      TextDisplayer      |     |
+  audio and video   |       Interface       |  |      Message sender     |-----+
+  data to the right |        (./mse)        |  |      (./core/main)      |
+  low-level buffers +-----------------------+  +-------------------------+
+                                               Small interface
+                                               facilitating communication
+                                               with current TextDisplayer
+                                               implementation
+``````
+
+For the subdirectories and files in this directory not represented in that schema:
+
+- `Compat` (_./compat_): Regroups every functions related to improving compatibility with
+  browsers / environments.
+
+- `errors` (_./errors_): Defines error subclasses, most of all for the API.
+
+- `experimental` (_./experimental_): Special directory for "experimental" tools and
+  features.
+
+- `features` (_./features_): Special directory allowing feature switching
+  (enabling/disallowing features to not include unused code when importing the RxPlayer).
+
+- `manifest` (_./manifest_): Defines a `Manifest` structure and its properties, a central
+  structure of the player describing a content.
+
+- `multithread` (_./multithread_): Global code specific to the multithreaded "flavor" of
+  the RxPlayer, that is a specific RxPlayer class which may run its main logic in a
+  WebWorker to improve performance.
+
+- `parsers` (_./parsers_): Various parsers for several formats
+
+- `tools` (_./tools_): Defines "tools", APIs which are not part of the RxPlayer class.
+
+- `utils` (_./utils_): Define utils function, small functions which can be used in several
+  part of the RxPlayer's code.
+
+- `config.ts` (_./config.ts_): Exports an interface allowing to update the RxPlayer's
+  config.
+
+- `index.ts` (_./index.ts_): Exports the main entry point for the RxPlayer, with a default
+  set of features.
+
+- `log.ts` (_./log.ts_): Exports the main RxPlayer's Logger instance.
+
+- `minimal.ts` (_./minimal.ts_): Exports the entry point for the minimal RxPlayer, which
+  is an RxPlayer without any feature. When relying on this build, an application will have
+  to manually add the specific features it wants.
+
+- `multithread_types.ts` (_./multithread_types.ts_): TypeScript types used specifically
+  when running the RxPlayer in multithread mode.
+
+- `public_types.ts` (_./public_types.ts_): List all TypeScript types which are part of the
+  API.
+
+- `worker_entry_point.ts` (_./worker_entry_point.ts_): Entry point for the logic of the
+  RxPlayer which will run in the WebWorker (and which will have to be loaded separately by
+  the application).
+
+## Multithread, Monothread and Directfile code paths
+
+There are actually three different main "code paths" that may be run, depending on the
+current content played.
+
+The previous schema mostly illustrated the most complex code path of the three (the
+"multithread mode"). Yet, to be more exact we need to separate those three cases:
+
+1. For "directfile" contents (contents directly decodable by the browser, e.g. mp4 files
+   or HLS playlists on Safari), the code path is the simplest and follows something like
+   this:
+
+   ```
+                  +---------------------------------------------+
+                  |               Application/UI                |
+                  +---------------------------------------------+
+                            |
+                            | call RxPlayer API
+                            |
+   -------------------------|--- RxPlayer Main Thread ----------------------------
+                            |
+        Front-facing API    v
+        +---------------------------------------+      +-------------------------+
+        |               Public API              | uses | MediaElementTracksStore |
+        |          (./main_thread/api)          |----->|(./main_thread/tracks_sto|
+        +---------------------------------------+      |re)                      |
+                            |                          +-------------------------+
+        Manage playback of  | creates                  Handle track switching
+        a "directfile"      |                          using directly the media
+        content             V                          element's API (`audioTracks`,
+        +---------------------------------------+      `textTracks` etc.)
+        |       DirectfileContentInitializer    |
+        |          (./main_thread/init)         |
+        +---------------------------------------+
+                            |
+                            V
+                           ... Some other RxPlayer modules
+                               (All running in main thread)
+   ```
+
+   As you can see, everything runs in main thread, a specialized module called the
+   `DirectfileContentInitializer` is called by the API to start-up such contents and a
+   specialized `MediaElementTracksStore` is handling tracks specifically for directfile
+   contents (as they are handled differently than for other code paths, here trough API
+   exposed by the browser)have .
+
+2. A second code path, we may call the "monothreaded code path" apply for non-directfile
+   contents (so, contents which rely on MSE API instead) loaded in monothreaded mode,
+   which is the default.
+
+   It is much closer to the schema of the previous chapter:
+
+   ```
+                  +---------------------------------------------+
+                  |               Application/UI                |
+                  +---------------------------------------------+
+                            |
+                            | call RxPlayer API
+                            |
+   -------------------------|- RxPlayer Main Thread ---------------------------
+                            |
+        Front-facing API    v
+        +---------------------------------------+    +--------------------+
+        |               Public API              |uses|     TracksStore    |
+        |          (./main_thread/api)          |--->|(./main_thread/track|
+        +---------------------------------------+    |s_store)            |
+                            |                        +--------------------+
+                            |                        Facilitate track switching
+        Manage playback of  | creates                for the API
+        contents relying    |
+        on a MediaSource,   |
+        all in main thread  v
+        +---------------------------------------+
+        |      MediaSourceContentInitializer    | ----> ... Some other RxPlayer
+        |          (./main_thread/init)         |           modules not in ./core
+        +---------------------------------------+
+                                |
+        Actually load and parse |
+        the right manifest and  | creates
+        media segments          |
+        (here in main thread)   V
+        +--------------------------------------+
+        |              Core modules            |
+        |                (./core)              |
+        +--------------------------------------+
+   ```
+
+   As you can see, the part of `./main_thread/init` run by the API is this time different
+   (`MediaSourceContentInitializer`) and the track handling also goes to a differently
+   named `TracksStore` when compared to directfile contents.
+
+   I also summarized all core modules into a single block, you can refer to the previous
+   chapter to have some examples of what they are (you can look at modules in the `./core`
+   directory in that schema - or at the `./core` directory itself).
+
+3. A third code path, the "multithreaded code path" apply for non-directfile contents (so,
+   contents which rely on MSE API instead) loaded in "multithread mode" (which has to be
+   explicitely enabled by the application).
+
+   Here you get all the complexity of the previous chapter, with two threads running. To
+   repeat the schema than the one used for the other code paths here, you would have
+   something like:
+
+   ```
+                  +---------------------------------------------+
+                  |               Application/UI                |
+                  +---------------------------------------------+
+                            |
+                            | call RxPlayer API
+                            |
+   -------------------------|----- RxPlayer Main Thread ---------------------------
+                            |
+        Front-facing API    v
+        +---------------------------------------+    +--------------------+
+        |               Public API              |uses|     TracksStore    |
+        |          (./main_thread/api)          |--->|(./main_thread/track|
+        +---------------------------------------+    |s_store)            |
+                            |                        +--------------------+
+                            |                        Facilitate track switching
+        Manage playback of  | creates                for the API
+        contents relying    |
+        on a MediaSource,   |
+        in multiple threads v
+        +---------------------------------------+
+        |      MultiThreadContentInitializer    | ----> ... Some other RxPlayer
+        |          (./main_thread/init)         |           modules not in ./core
+        +---------------------------------------+
+                                |  ^
+                                |  | postMessage exchanges
+                                |  |
+        ------------------------|--|- RxPlayer WebWorker --------------------------
+                                |  |
+        Actually load and parse |  |
+        the right manifest and  |  |
+        media segments          |  |
+        (here in a Worker)      V  |
+        +--+--------------------------------+--+
+        |  |            Worker Main         |  |
+        |  |        (./core/main/worker)    |  |
+        |  +--------------------------------+  |
+        |              Core modules            |
+        |                (./core)              |
+        +--------------------------------------+
+   ```
+
+   This time, the part of `./main_thread/init` run by the API is the
+   `MultiThreadContentInitializer` and the track handling also goes through the
+   `TracksStore`, like for the monothreaded code path.
+
+   The main difference however is that now all core modules are running completely in a
+   WebWorker, meaning in another thread. It is the role of the
+   `MultiThreadContentInitializer` to send message to it and to process most of the
+   messages the WebWorker sends back.
+
+   Because this time, the core also has to reception and send backs messages from and to
+   the main thread, there's a supplementary core module involved than on the "monothreaded
+   code path", the "Worker Main". It then however relies on the exact same other core
+   modules than for the "monothreaded code path".