Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Bring multiple feature switching improvements #1287

Merged
merged 2 commits into from
Sep 26, 2023
Merged

Bring multiple feature switching improvements #1287

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9a50edb
Bring nice feature switching improvements
peaBerberian Sep 22, 2023
5ce7aeb
Re-document now-deprecated features
peaBerberian Sep 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
278 changes: 13 additions & 265 deletions doc/Getting_Started/Minimal_Player.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,33 +8,18 @@ Smooth streaming, VTT or SRT parsing.

Because each implementation has its need, we permit multiple ways to import
the player with limited features.
This principally leads to a smaller file size.

This customization can be done through two principal ways:
This customization can be done by importing the minimal version of the RxPlayer
and then adding only the features your want.
This allows to greatly reduce the final bundle size, if your bundler (esbuild,
webpack, rollup, vite...) support
[tree-shaking](https://en.wikipedia.org/wiki/Tree_shaking), like most do.

- by importing a minimal version and then adding only the features your want
## How it works

- by setting environment variables at build time

The first solution is the most straightforward and should be used in most
usecases. The main disadvantages of this solution are that to reduce file size:

- you will need to use a module-bundler or minifier which performs
[tree-shaking](https://en.wikipedia.org/wiki/Tree_shaking), like webpack's
production mode or rollup.

- you will need to use the package published on npm (as opposed to the git
repository directly).

The second solution will always work but needs you to build the bundle yourself
through our npm scripts.

## Importing a minimal version

### How it works

If you imported the RxPlayer library through the npm package (like via the `npm install rx-player` command), you can import a minimal version of the player by
importing it from `"rx-player/minimal"`:
If you imported the RxPlayer library through the npm package (like via the
`npm install rx-player` command), you can import a minimal version of the player
by importing it from `"rx-player/minimal"`:

```js
import MinimalRxPlayer from "rx-player/minimal";
Expand All @@ -56,8 +41,7 @@ import { DASH, SMOOTH } from "rx-player/features";
```

At last you can add those features to the imported RxPlayer class by calling the
special `addFeatures` static method, which is only present on the minimal
version of the Player:
`addFeatures` static method:

```js
// addFeatures takes an array of features as argument
Expand Down Expand Up @@ -100,242 +84,6 @@ By using the minimal version, you will reduce the final bundle file **if
tree-shaking is performed on the final code (like in webpack's production
mode)**.

The key is just to know which feature does what. The next chapter will list
and explain the role of every one of them.

### List of features

Features, which are variables imported from the `"rx-player/features"` path,
are all objects declared in upper-case.

Here is the anotated exhaustive list (notes are at the bottom of the table):

| Feature | Description of the feature |
| ------------------------ | --------------------------------------------------------- |
| `SMOOTH` | Enable Smooth streaming (HSS) playback |
| `DASH` | Enable DASH playback using a JavaScript-based MPD parser |
| `DIRECTFILE` | Enable playback of "directfile" contents |
| `EME` | Enable playback of encrypted contents |
| `NATIVE_TEXT_BUFFER` [1] | Allow to display text tracks through \<tracks\> elements |
| `HTML_TEXT_BUFFER` [1] | Allow to display richer text tracks through HTML elements |
| `IMAGE_BUFFER` [1] | Allow to display thumbnails through the image buffer |
| `NATIVE_SRT_PARSER` [2] | Parse SRT text tracks for the native text buffer |
| `NATIVE_VTT_PARSER` [2] | Parse VTT text tracks for the native text buffer |
| `NATIVE_TTML_PARSER` [2] | Parse TTML text tracks for the native text buffer |
| `NATIVE_SAMI_PARSER` [2] | Parse SAMI text tracks for the native text buffer |
| `HTML_SRT_PARSER` [3] | Parse SRT text tracks for the HTML text buffer |
| `HTML_VTT_PARSER` [3] | Parse VTT text tracks for the HTML text buffer |
| `HTML_TTML_PARSER` [3] | Parse TTML text tracks for the HTML text buffer |
| `HTML_SAMI_PARSER` [3] | Parse SAMI text tracks for the HTML text buffer |
| `BIF_PARSER` [4] | Parse BIF image tracks for the image buffer |
| `DASH_WASM` [5] [6] | Enable DASH playback using a WebAssembly-based MPD parser |
| `LOCAL_MANIFEST` [5] | Enable playback of "local" contents |
| `METAPLAYLIST` [5] | Enable playback of "metaplaylist" contents |
| `DEBUG_ELEMENT` [5] | Allows to use the `createDebugElement` RxPlayer method |

---

**Notes**:

**[1]**: You will need to also add at least one parser for this type of buffer
for those features to be useful.
(example: `NATIVE_SRT_PARSER` will parse srt subtitles for the
`NATIVE_TEXT_BUFFER`)

**[2]**: Those features will only be used if `NATIVE_TEXT_BUFFER` is an added
feature.

**[3]**: Those features will only be used if `HTML_TEXT_BUFFER` is an added
feature.

**[4]**: This feature will only be used if `IMAGE_BUFFER` is an added feature.

**[5]**: Those type of contents are experimental. They should be imported
from `rx-player/experimental/features`.

**[6]**: In cases where both the `DASH` and `DASH_WASM` features are added
(which are both parsers for DASH contents), the RxPlayer will default using the
WebAssembly parser (provided by `DASH_WASM`) and fallback on the JavaScript
parser (provided by `DASH`) when it cannot do so.

---

### Examples

To help you choose your features, are some examples that represents common
usecases.

#### unencrypted DASH contents with native webVTT subtitles

```js
import RxPlayer from "rx-player/minimal";
import {
DASH,
NATIVE_TEXT_BUFFER,
NATIVE_VTT_PARSER,
} from "rx-player/features";

RxPlayer.addFeatures([DASH, NATIVE_TEXT_BUFFER, NATIVE_VTT_PARSER]);
```

#### possibly-encrypted DASH contents with HMTL webVTT and TTML subtitles

```js
import RxPlayer from "rx-player/minimal";
import {
DASH,
EME,
HTML_TEXT_BUFFER,
HTML_VTT_PARSER,
HTML_HTML_PARSER,
} from "rx-player/features";

RxPlayer.addFeatures([
DASH,
EME,
HTML_TEXT_BUFFER,
HTML_VTT_PARSER,
HTML_TTML_PARSER,
]);
```

#### Smooth contents with thumbnails (BIF) support

```js
import RxPlayer from "rx-player/minimal";
import { SMOOTH, IMAGE_BUFFER, BIF_PARSER } from "rx-player/features";

RxPlayer.addFeatures([SMOOTH, IMAGE_BUFFER, BIF_PARSER]);
```

## Building with environment variables

### How it works

You can also include only the features you need on the RxPlayer library by
building it while having specific environment variables.

The code related to the unwanted features should be removed when the final code
is minified (as the corresponding code is made unreachable).

To avoid any conflict with other environment variables, they all are named
`RXP_<FEATURE-NAME>`.

For example, the following will remove all code related to Microsoft Smooth
Streaming from the build:

```sh
RXP_SMOOTH=false npm run build:min
```

### List of environment variables

#### RXP_SMOOTH

True by default. If set to "false", all code relative to HSS streaming will be
ignored during a build.

#### RXP_DASH

True by default. If set to "false", all code relative to DASH streaming will be
ignored during a build.

#### RXP_DIRECTFILE

True by default. If set to "false", all code relative to directfile streaming
will be ignored during a build.

#### RXP_LOCAL_MANIFEST

False by default. If set to "true", all code relative to the "local" transport
(to be able to play content offline for example) will be included during a
build.

#### RXP_METAPLAYLIST

False by default. If set to "true", all code relative to metaplaylist streaming
will be included during a build.

#### RXP_DEBUG_ELEMENT

False by default. If set to "true", the method RxPlayer's `createDebugElement`
method will be callable.

#### RXP_EME

True by default. If set to "false", all code relative to encrypted contents will
be ignored during a build.

#### RXP_NATIVE_TTML

True by default. If set to "false", all code relative to TTML parsing for native
text tracks will be ignored during a build.

#### RXP_NATIVE_SAMI

True by default. If set to "false", all code relative to SAMI parsing for native
text tracks will be ignored during a build.

#### RXP_NATIVE_VTT

True by default. If set to "false", all code relative to VTT parsing for native
text tracks will be ignored during a build.

#### RXP_NATIVE_SRT

True by default. If set to "false", all code relative to SRT parsing for native
text tracks will be ignored during a build.

#### RXP_HTML_TTML

True by default. If set to "false", all code relative to TTML parsing for html
text tracks [1] will be ignored during a build.

#### RXP_HTML_SAMI

True by default. If set to "false", all code relative to SAMI parsing for html
text tracks [1] will be ignored during a build.

#### RXP_HTML_VTT

True by default. If set to "false", all code relative to VTT parsing for html
text tracks [1] will be ignored during a build.

#### RXP_HTML_SRT

True by default. If set to "false", all code relative to SRT parsing for html
text tracks [1] will be ignored during a build.

#### RXP_BIF_PARSER

True by default. If set to "false", all code relative to BIF image parsing will
be ignored during a build.

#### RXP_BAREBONE

If set to true, no feature is activated by default and all other environment
variables are considered as false by default (unless set).

For example, to only activate DASH, you could do:

```sh
RXP_BAREBONE=true RXP_DASH=true npm run build:min
```

#### RXP_ENV

Either "production" or "development". "production" as a default.
In the "development" case:

- logs will be activated
- the code will be less tolerant towards unwanted behavior
- the code will be less optimized

---

**Notes**:

DOM element instead of a `<track>` (the latter here being called "native") tag
for a richer formatting.

---
The key is just to know which feature does what.
You can refer to the [RxPlayer Features documentation page](../api/RxPlayer_Features.md) for
this.
4 changes: 4 additions & 0 deletions doc/api/.docConfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@
"path": "./Creating_a_Player.md",
"displayName": "Creating a Player"
},
{
"path": "./RxPlayer_Features.md",
"displayName": "Feature switching"
},
{
"path": "./Loading_a_Content.md",
"displayName": "Loading a Content"
Expand Down
21 changes: 10 additions & 11 deletions doc/api/Loading_a_Content.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,8 @@ Can be either:
player](../Getting_Started/Minimal_Player.md), you will need to add at least
either one of the following features to be able to play DASH contents:

- the `DASH` feature (rely on a generally-sufficient JavaScript parser)
- the `DASH` [feature](./RxPlayer_Features.md) (rely on a generally-sufficient
JavaScript parser)

- the `DASH_WASM` experimental feature (backed by a WebAssembly parser, more
efficient when handling very large MPDs).
Expand All @@ -50,17 +51,17 @@ Can be either:
- **`"smooth"` - for Microsoft Smooth Streaming contents**

If you're using the [minimal build of the player](../Getting_Started/Minimal_Player.md), you
will need to add at least the `SMOOTH` feature to be able to play Smooth
contents.
will need to add at least the `SMOOTH` [feature](./RxPlayer_Features.md) to be
able to play Smooth contents.

- **`"directfile"` - for loading a video in _DirectFile_ mode, which allows to
directly play media files** (example: `.mp4` or `.webm` files) without
using a transport protocol. With that option, you can even play HLS
contents on multiple browsers (mainly safari and iOS browsers).

If you're using the [minimal build of the player](../Getting_Started/Minimal_Player.md), you
will need to add at least the `DIRECTFILE` feature to be able to play those
contents.
will need to add at least the `DIRECTFILE` [feature](./RxPlayer_Features.md)
to be able to play those contents.

<div class="warning">
In that mode, multiple APIs won't have any effect.
Expand All @@ -71,17 +72,15 @@ Can be either:
- `"metaplaylist"` for [MetaPlaylist](./Miscellaneous/MetaPlaylist.md) streams,
which are a concatenation of multiple smooth and DASH contents

If you're using the [minimal build of the player](../Getting_Started/Minimal_Player.md), you
will need to add at least the `METAPLAYLIST` experimental feature to be able
to play those contents.
You will need to add at least the `METAPLAYLIST` experimental [feature](./RxPlayer_Features.md)
to be able to play those contents.

- `"local"` for [local manifests](./Miscellaneous/Local_Contents.md), which
allows to play downloaded DASH, Smooth or MetaPlaylist contents (when offline
for example).

If you're using the [minimal build of the player](../Getting_Started/Minimal_Player.md), you
will need to add at least the `LOCAL_MANIFEST` experimental feature to be able
to play those contents.
You will need to add at least the `LOCAL_MANIFEST` experimental [feature](./RxPlayer_Features.md)
to be able to play those contents.

Example:

Expand Down
Loading
Loading