rx-player 4.0.0-dev.2023121900 → 4.0.0-rc.2

package/CONTRIBUTING.md

@@ -1,272 +0,0 @@
-# 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
-repository](https://github.com/canalplus/rx-player/issues).
-We'll try to acknowledge it as soon as possible.
-
-If that issue is not already worked on, we will usually accept pull requests.
-Those have to follow the conventions defined below.
-
-
-
-## Important code concepts
-
-### Code documentation
-
-We try to put `README.md` files inside every significant directories inside
-`/src` to provide a global architecture documentation of that directory
-specifically.
-
-You can try to start understanding a piece of RxPlayer code by navigating
-to that file. Understand that the documented behavior may be out of date
-(in which case you're welcome to update it or open an issue) though even in
-that case, it is a good starting point to understand the directory's role.
-Likewise, don't forget to update it if a change you made to the code
-necessitates a documentation change.
-
-Also, for a more exhaustive approach to the documentation of the project's file
-organization, you can look at [`FILES.md`](./FILES.md).
-
-### When renaming or deleting functions, classes or variables
-
-When Refactoring/Renaming, make sure to grep any of the renamed class / function
-/ variable's name as they may also be referenced in documentation and code
-comments. Same thing for a directory or file name.
-
-If the name is hard to grep (e.g. the name is too generic and thus has too many
-false positives), you can generally reduce the area to comments in the same file
-and documentation files in the same directory.
-
-### `features` object
-
-Some files should not be imported directly but only be accessed by going through
-the `features` object exported at `/src/features`. This is to reduce bundle size
-when an application doesn't need all of the RxPlayer's features.
-
-
-
-## Code style
-
-### Linting
-
-The code style in `src` is automatically checked by a "linter", `eslint`.
-
-It basically follows those principles:
-  - 2 spaces indentation
-  - 90 columns maximum
-  - 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`.
-
-You can also check the style of the demo page (in the `demo` directory) by
-calling `npm run lint:demo`, or the style of the test files (in the `tests`
-directory) by calling `npm run lint:tests`.
-
-
-### Types
-
-We try to be as strict as possible with types:
-
-  - the `any` type should be avoided
-
-  - the `as` TypeScript keyword, used for type casting, should also be avoided
-    as much as possible.
-
-This is to be sure we can detect as much as possible type errors automatically
-with TypeScript.
-
-### `type` and `interface` typing
-
-TypeScript's `type` and `interface` should all be named beginning with the
-letter `I`, for easier identification purposes\*:
-```ts
-interface IMyObject {
-  someKey: string;
-}
-
-type IStringOrNumber = string |
-                       number;
-```
-
-`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,
-}
-
-const enum MyConstEnum {
-  Value1 = 1,
-  Value2 = 2,
-}
-```
-
-\*We know that this rule is a controversial subject amongst TypeScript
-developpers, yet we still decide to enforce it for now.
-
-### Forbidden functions and classes
-
-Some native functions, methods or classes should never be used to ensure
-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
-
-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
-  - `Promise.prototype.finally`: Use `then` or both `then` and `catch` of that
-    Promise's methods instead.
-
-
-## The demo page
-
-### Building the demo and serving it
-
-You might want to quickly test your code modification(s) on a real use case.
-
-For those types of need, we developped two demo pages:
-
-  - the _full demo_ page, which is also the one used to showcase the player.
-
-    This demo has a user-friendly interface and allow the most frequent API
-    interactions.
-
-    It also exposes both the RxPlayer class through `window.RxPlayer` and the
-    rxPlayer instance through `window.rxPlayer` - both in the global scope. You
-    can thus open a debugger/inspector in your favorite browser to exploit
-    directly the player's API.
-
-  - the _standalone demo_ page, which is just a `<video />` tag linked to a
-    RxPlayer instance.
-
-    In this demo too, `window.RxPlayer` and `window.rxPlayer` link to the
-    RxPlayer class and the rxPlayer instance respectively.
-
-To use the full demo page, you can build it and run a local HTTP server on the
-port 8000 by running the following npm script.
-```sh
-npm run start
-```
-
-To use the standalone demo page, you can build it and run a local HTTP server on
-the port 8001 by running the following npm script.
-```sh
-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. Note however that hot-reload is
-not enabled currently, you'll have to refresh the page yourself.
-
-### 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.
-
-Thankfully, we have an npm script which generates a local self-signed
-certificate with the help of `openssl`:
-```sh
-npm run certificate
-```
-
-You can then run the same demo script defined previously.
-The _full demo_ will now serve HTTPS through the port 8443 and the _standalone
-demo_ through the port 8444. Both still serve HTTP on the same ports than
-before.
-
-Note that such self-signed certificates are usually (rightfully) considered
-suspicious by web browsers. As such, you might first encounter a warning screen
-when going to one of the demo pages in HTTPS. In most browsers, you can however
-safely ignore that warning.
-
-
-## Creating a commit
-
-### Checks
-
-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`.
-
-
-## The test suite
-
-### Unit tests
-
-Unit tests test function implementations. Mostly to check if they give a sane
-output for every input given.
-
-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 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.
-
-
-### Integration tests
-
-What we call integration tests are tests testing the entire API of the RxPlayer.
-
-New integration tests are not required when a new code is added. Just make sure
-that all those tests pass before doing a pull request by running:
-`npm run test:integration`.
-
-It you want to improve our integration tests, you are welcome to do so.
-Those are wrote in `tests/integration` with the help of the Mocha, Chai and
-Sinon libraries.
-
-We also use a homemade library and server to serve media contents to our tests.
-If you want to know how it works, we invite you to rely on the already created
-tests and to read the corresponding files.
-
-
-### Memory tests
-
-Memory tests replicate simple scenarios and try to detect memory leaks.
-
-You can also help us improving our memory tests. Those are written in
-`test/memory`. The testing stack used is Mocha, Chai and Sinon.
-
-
-
-## Documentation
-
-The documentation is written in the `doc` directory, at the root of the project.
-
-The content of `doc/generated` contains an HTML version of the Markdown files
-written in the other directories. It is automatically generated from those by
-calling the `doc` script through `npm run doc`.
-
-
-
-## Opening a pull request
-
-### Which branch to merge to
-
-Pull requests for bug fixes, new tests or documentation should be done on the
-`master` branch.
-
-Pull requests for new features and breaking changes will have to be performed
-on the `next` branch.
-
-If you don't know on which branch to do a pull request, please open it on
-`master`, we will know how to redirect it to the right one.

package/FILES.md

@@ -1,277 +0,0 @@
-# File architecture
-
-This page describes how the player files are organized. Each chapter go through
-a single directory or subdirectory, in alphabetical order.
-
-
-## `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
-
-  - _standalone_: Just expose the rx-player in ``window``, to allow scripted
-    interactions with it in the console. The player is linked to a video tag in
-    the displayed page.
-
-
-## `dist/`: Builds
-
-The `dist/` directory stores the player builds of the last version released.
-
-Directories can also be generated in here if the right scripts are called.
-These allow to publish more modular codebases to npm.
-
-
-## `doc/`: Documentation
-
-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.
-
-
-## `scripts/`: Project-managing scripts
-
-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
-  - deploying the demo or doc to github pages
-  - updating the player version
-  - generating the rx-player build before publishing on npm
-
-
-## `src/`: The source code
-
-The `src` directory contains the entire source code of the rx-player.
-
-It is subdivized into subdirectories which are defined here.
-
-
-### `src/compat/`: Compatibility files
-
-``src/compat`` contains functions allowing to use browser APIs in a
-cross-browser manner.
-
-For example, if an event does not have the same name depending on the browser,
-the compat files will expose a simple function allowing to make sure the event
-is catched, taking the task of registering the right event on the callback
-given.
-
-Every functions needed in the rest of the code are exported in
-``compat/index.js``, making it easier to import (e.g. by just doing
-``import { whatINeed } from "../compat";``)
-
-
-### `src/core/`: Core logic
-
-Defines the logic and behavior of the player, regardless of the browser and of
-the streaming technology used.
-
-That's where:
-  - the api is defined
-  - the MSE and EME APIs are called and managed
-  - the segments are downloaded and pushed to then be decoded by the browser
-  - adaptive bitrate strategies are set
-
-This directory contains other subdirectories which are listed in the next
-chapter.
-
-
-### `src/errors/`: Error definitions
-
-Contains the definition of the error classes used in the rx-player and
-accessible through the API.
-
-
-### `src/experimental/`: Experimental features
-
-You will find here experimental features. Those are tested features who might
-completely change their API in new player versions.
-
-
-### `src/features/`: Feature switching
-
-This manage activated or deactivated features (e.g. DASH, TTML subtitles
-parsing).
-
-It exports an object defining the different activated features and provide utils
-to initialize and update them.
-
-
-### `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.
-
-
-### `src/transports/`: Streaming protocols implementation
-
-Defines a common interface for multiple streaming technologies (DASH, HSS).
-
-What is exported there are functions to load:
-  - Manifests/MPDs
-  - video/audio segments
-  - subtitles tracks
-
-For different streaming technologies.
-
-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.
-
-
-### `src/parsers/`: The parsers
-
-Functions to parse various formats into the same interface.
-
-The parsed data being either:
-  - Manifest documents: DASH's MPD, HSS's Manifest...
-  - containers: ISOBMFF (CMAF, fMP4, MP4), Matroska (MKV, WEBM)
-  - text tracks: TTML, SAMI, SRT, WebVTT
-  - image containers: BIF
-
-
-### `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.
-
-
-### `src/utils/`: Util functions
-
-This directory contains general helpers which are used in different parts of the
-rx-player code.
-
-
-## Inside `src/core/`
-
-As written in the previous chapter, this is the "core" of the player, where the
-logic is defined.
-
-As this directory is versatile and complicated, it also deserves its own chapter.
-
-
-### `src/core/adaptive/`: Adaptive BitRate logic
-
-Defines functions which manages the adaptive streaming part of the player.
-
-This manager takes various observables/options as inputs to record the current
-situation of the player, give an opinion about the best media tracks to choose,
-and provide methods allowing to get/set various adaptive-related options.
-
-Despite containing several files and using several classes, only the
-`AdaptiveRepresentationSelector` exported in `adaptive/index.js` should be
-needed by the rest of the core.
-This allows to isolate this complex part and facilitate future refactoring and
-improvements.
-
-
-### `src/core/api/`: API definition
-
-Defines the rx-player API. This is the part the library user will directly
-interact with.
-
-
-### `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`.
-
-
-### `src/core/decrypt/`: Decryption handling
-
-Defines functions allowing to handle encrypted contents through the EME browser
-APIs.
-
-
-### `src/core/fetchers/`: Load resources
-
-Handle the segments and Manifest downloading pipelines (load and parse) as
-defined in the ``src/transports/`` directory.
-
-This is the layer directly interacting with the transport part (HSS, DASH).
-It facilitates the role of loading the Manifest and new segments for the rest of
-the core.
-
-
-### `src/core/segment_buffers/`: Media buffers
-
-Code allowing to interact with the media buffers called `SegmentBuffers`.
-
-Those are the Objects to which segments are pushed so they can be decoded at the
-right time.
-
-For Audio and Video, `SegmentBuffers` rely on a native `SourceBuffer` object,
-already provided by the browser,
-for other type of contents (like subtitles), we rely on completely custom media
-buffers implementations.
-
-
-### `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
-push segments so the content can play) and link together many subparts of the
-player.
-
-
-## `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
-tests.
-
-Most unit tests files contain only tests for a single source file. Those will
-be put directly at the root of `__tests__` under the name
-`<ORIGINAL_SRC_FILE>.test.ts` (where `<ORIGINAL_SRC_FILE>` is the filename of
-the tested file).
-
-`__tests__` directories can also contain files defining tests for multiple files
-contained in the tested directory.
-Those can be quicker to write and easier to maintain at the expense of being
-less thorough.
-
-Those type of "global" unit tests are put in a special `__global__` directory,
-itself directly at the root of the corresponding `__tests__` directory.
-Their filename don't follow the same convention than single-source unit tests
-but should still be suffixed by `.test.ts`.
-
-
-## `tests/`: The RxPlayer's general tests
-
-This directory contains most testing code for the RxPlayer.
-
-The rx-player contains multiple type of tests:
-
-  - integration tests: test the whole player API and its behavior when playing
-    different contents. The main goal of those tests is to quickly detect
-    regressions.
-
-    Those are entirely written in the ``tests/integration`` sub-directory.
-
-  - conformance tests: Provide standalone page which allows to quickly test the
-    support of various media-related API on a given device and/or browser.
-
-    The html documents you will find here are basic templates that can be easily
-    modified and deployed for quick testing.
-
-  - unit tests: test specific parts of the code. The main goal here is to check
-    the implementation of smaller units of code.
-
-    They are written alongside the code, in ``__tests__``
-    directories. All its configuration can be found at the root of the project,
-    in `jest.config.js` (we use the jest library for unit tests).
-
-  - memory tests: test the memory usage of the player.
-
-    They are entirely written in the ``tests/memory`` subdirectory.

package/dist/_esm5.processed/compat/add_class_name.d.ts

@@ -1,22 +0,0 @@
-/**
- * Copyright 2015 CANAL+ Group
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-/**
- * Add className to an HTMLElement. Do nothing if the className was already
- * added.
- * @param {HTMLElement} elt
- * @param {string} className
- */
-export default function addClassName(elt: HTMLElement, className: string): void;

package/dist/_esm5.processed/compat/add_class_name.js

@@ -1,39 +0,0 @@
-/**
- * Copyright 2015 CANAL+ Group
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-var hasClassList;
-/**
- * Add className to an HTMLElement. Do nothing if the className was already
- * added.
- * @param {HTMLElement} elt
- * @param {string} className
- */
-export default function addClassName(elt, className) {
-    if (hasClassList === undefined) {
-        hasClassList = elt.classList !== undefined &&
-            /* eslint-disable @typescript-eslint/unbound-method */
-            typeof elt.classList.add === "function";
-        /* eslint-enable @typescript-eslint/unbound-method */
-    }
-    if (hasClassList) {
-        elt.classList.add(className);
-    }
-    else {
-        var classNamesWithSpaces = " " + elt.className + " ";
-        if (classNamesWithSpaces.indexOf(" " + className + " ") < 0) {
-            elt.className += " " + className;
-        }
-    }
-}

package/dist/_esm5.processed/compat/add_text_track.d.ts

@@ -1,33 +0,0 @@
-/**
- * Copyright 2015 CANAL+ Group
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import { ICompatTextTrack } from "./browser_compatibility_types";
-/**
- * Add text track to the given media element.
- *
- * Returns an object with the following properties:
- *   - track {TextTrack}: the added text track
- *   - trackElement {HTMLElement|undefined}: the added <track> element.
- *     undefined if no trackElement was added.
- *
- * @param {HTMLMediaElement} mediaElement
- * @param {Boolean} hidden - If `true`, the text track will be hidden by
- * default. If `false`, the text track will be directly showing.
- * @returns {Object}
- */
-export default function addTextTrack(mediaElement: HTMLMediaElement, hidden: boolean): {
-    track: ICompatTextTrack;
-    trackElement: HTMLTrackElement | undefined;
-};

package/dist/_esm5.processed/compat/add_text_track.js

@@ -1,50 +0,0 @@
-/**
- * Copyright 2015 CANAL+ Group
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import { isIEOrEdge } from "./browser_detection";
-/**
- * Add text track to the given media element.
- *
- * Returns an object with the following properties:
- *   - track {TextTrack}: the added text track
- *   - trackElement {HTMLElement|undefined}: the added <track> element.
- *     undefined if no trackElement was added.
- *
- * @param {HTMLMediaElement} mediaElement
- * @param {Boolean} hidden - If `true`, the text track will be hidden by
- * default. If `false`, the text track will be directly showing.
- * @returns {Object}
- */
-export default function addTextTrack(mediaElement, hidden) {
-    var _a, _b;
-    var track;
-    var trackElement;
-    var kind = "subtitles";
-    if (isIEOrEdge) {
-        var tracksLength = mediaElement.textTracks.length;
-        track = (tracksLength > 0 ? mediaElement.textTracks[tracksLength - 1] :
-            mediaElement.addTextTrack(kind));
-        track.mode = hidden ? ((_a = track.HIDDEN) !== null && _a !== void 0 ? _a : "hidden") :
-            ((_b = track.SHOWING) !== null && _b !== void 0 ? _b : "showing");
-    }
-    else {
-        trackElement = document.createElement("track");
-        mediaElement.appendChild(trackElement);
-        track = trackElement.track;
-        trackElement.kind = kind;
-        track.mode = hidden ? "hidden" : "showing";
-    }
-    return { track: track, trackElement: trackElement };
-}