RxPlayer Architecture documentation

Overview

The files in this directory and subdirectories establish a documentation about the RxPlayer’s architecture.

They are here to help you understand the way the player works, by describing the different bricks and algorithms that come into play.

Note: As some terms used here might be too foreign or slightly different than the one you’re used to, we also wrote a list of terms and definitions used by the RxPlayer here.

Organization of the documentation

The RxPlayer is heavily modularized.

This helps us maintaining the code and providing evolutions more quickly, as the various modules use few well-defined interfaces with the rest of the code.

Like the code, the documentation is also divided in multiple parts, which link one by one to a module in the code.

Such modules are (with link to their respective documentation, if one):

  • the API

    Defines the public API of the RxPlayer and provides abstractions to help implementing it.

  • the Init

    Initialize playback and connects the different modules between one another.

  • the EMEManager

    Negotiate content decryption.

    Only used for contents with DRM (Digital Right Management).

  • the ABRManager

    Helps to choose the best quality in the current content by analyzing the current network, user settings and viewing conditions.

  • the Buffers

    Choose which media segments to download and push them to SourceBuffers to then be able to decode them.

    Various files documenting the Buffers architecture should be available in the doc/architecture/buffer directory.

  • the SourceBuffers

    Provides abstractions on top of the browser’s SourceBuffers, which are used to push media segments. These files help to handle those “native” SourceBuffers (defined by the browser), but also define custom ones for media managed entirely by the RxPlayer like subtitles and thumbnails.

  • the transports

    Perform manifest/segment requests, and parse them. transports in essence abstracts the transport protocol used (example: Smooth Streaming/DASH) to provide an unified definition of a segment or manifest to the other modules. In theory, it should be the only directory to update when adding / modifying / deleting a transport protocol

  • the Pipelines

    Link the transport module with the rest of the code, to download segments, download/refresh the manifest and collect data (such as the user’s bandwidth) for the other modules.

The RxPlayer also has a multitude of isolated helpers (for manifest management, segment parsing, browser compatibility, feature switching, error handling etc.) which are used by these different modules.

A documentation about the file organization of the project is available here.

Global architecture

To better understand the player’s architecture, you can find below a (simplified!) schema of it:

               +---------------------------------------------+              ,,,,,,,
               |                                             |             (  CDN  )
               |               Application/UI                |              ```````
               |                                             |                 ^
               +---------------------------------------------+                 |
                          | ^                                                  |
                          | ~                                                  |
-----RxPlayer------------------------------------------------------------------|----------
                          | ~                          +-------------------+   |
                          V ~     Front-facing API     |  ---> Call        |   |
     +-------------------------------------------+     |  ~~~> Send events |   |
     |                    API                    |     +-------------------+   |
     +-------------------------------------------+                             |
 +--------------------+    |      | ^                                          |
 | TrackChoiceManager | <--+      | ~                                          |
 +--------------------+           | ~                                          |
 Facilitate track                 | ~                                          |
 switching for                    V ~                                          |
 the API                  +---------------+                                    |
                          |               |           +----------+ ------> +------------+
 +------------+ <-------- |               | --------> | Manifest | <~~~~~~ | transports |
 | EMEManager | ~~~~~~~~> |     Init      | <~~~~~~~~ | Pipeline |         +------------+
 +------------+           |               |           +----------+         Abstract   ^ ~
 Negotiate content        |               |           Download the         the        | ~
 decryption               +---------------+           manifest             streaming  | ~
                                 | ^  Initialize                           protocol   | ~
                                 | ~  playback and                                    | ~
                                 | ~  create/connect                                  | ~
                                 | ~  modules                                         | ~
Buffers                          | ~                                                  | ~
+--------------------------------|-~-----------------------------+                    | ~
|                                V ~                             |                    | ~
|  Create the right         +-------------------------------+    |                    | ~
|  PeriodBuffers depending  |       BufferOrchestrator      |    |                    | ~
|  on the current position, +-------------------------------+    |                    | ~
|  and settings              | ^          | ^            | ^     |                    | ~
|                            | ~          | ~            | ~     |                    | ~
|                            | ~          | ~            | ~     |                    | ~
|                            | ~          | ~            | ~     |                    | ~
|                  (audio)   v ~  (video) V ~     (text) v ~     |                    | ~
| Create the right +----------+   +----------+    +----------+   |  +--------------+  | ~
| AdaptationBuffer |          |   |          |    |          |----> | SourceBuffer |  | ~
| depending on the |  Period  |-+ |  Period  |-+  |  Period  |-+ |  |   Store (1)  |  | ~
| wanted track     |  Buffer  | | |  Buffer  | |  |  Buffer  | | |  +--------------+  | ~
| (One per Period  |          | | |          | |  |          | | |  Create one        | ~
| and one per type +----------+ | +----------+ |  +----------+ | |  SourceBuffer per  | ~
| of media)         |           |  |           |   |           | |  type of media     | ~
|                   +-----------+  +-----------+   +-----------+ |                    | ~
|                          | ^            | ^            | ^     |                    | ~
|                          | ~            | ~            | ~     |                    | ~
|                          | ~            | ~            | ~     |                    | ~
|                          | ~            | ~            | ~     |                    | ~
|                  (audio) v ~    (video) V ~     (text) v ~     |                    | ~
|                  +----------+   +----------+    +----------+ ---> +--------------+  | ~
| Create the right |          |   |          |    |          | <~~~ |ABRManager (1)|  | ~
| Representation-  |Adaptation|-+ |Adaptation|-+  |Adaptation|-+ |  +--------------+  | ~
| Buffer depending |  Buffer  | | |  Buffer  | |  |  Buffer  | | |  Find the best     | ~
| on the current   |          | | |          | |  |          | | |  bitrate           | ~
| network,         +----------+ | +----------+ |  +----------+ | |                    | ~
| settings...       |           |  |           |   |           | |                    | ~
|                   +-----------+  +-----------+   +-----------+ |                    | ~
|                          | ^            | ^            | ^     |                    | ~
|                          | ~            | ~            | ~     |                    | ~
|                          | ~            | ~            | ~     |                    | ~
|                          | ~            | ~            | ~     |                    | ~
|                  (audio) v ~    (video) V ~     (text) v ~     |                    | ~
|                  +----------+   +----------+    +----------+ ----> +------------+   | ~
| (Representation- |          |   |          |    |          | <~~~~ |  Segment   | --+ ~
| Buffer).         |Represe...|-+ |Represe...|-+  |Represe...|-+ |   |Pipeline (1)| <~~~+
| Download and push|  Buffer  | | |  Buffer  | |  |  Buffer  | | |   +------------+
| segments based on|          | | |          | |  |          | | |   Download media
| the current      +----------+ | +----------+ |  +----------+ | |   segments
| position and      |           |  |           |   |           | |
| buffer state      +-----------+  +-----------+   +-----------+ |
|                                                                |
+----------------------------------------------------------------+

(1) The SourceBuffer Store, Segment Pipeline and ABRManager are actually created by the
Init and then used by the Buffers.