# The `ContentInitializer`

| Consideration           | Status                                            |
| ----------------------- | ------------------------------------------------- |
| Preferred import style  | Either through `features` or directory-only _[1]_ |
| Multithread environment | Main thread, WebWorker or both depending on file  |

_[1]_ The right `ContentInitializer` implementation wanted should be imported through the
global `features` object. This improves feature-switching and thus may reduce bundle size
for an application. Other imports should be performed through the `init` directory
itself - which means that inner files of that directory shouldn't be imported by outside
code (thus `./index.ts` should export everything that may be imported directly by outside
code).

## Overview

The ContentInitializer is the part of the code actually starting and running the logic
behind playing a content.

Its code is written in the `src/main_thread/init` directory.

Every time you're calling the API to load a new video, a ContentInitializer is called by
it (with multiple options).

The ContentInitializer then starts loading the content and communicate back its progress
to the API through events.

```
                 +-----------+
 1. loadVideo    |           |      2. Instanciate
---------------> |    API    | -------------------+
                 |           |                    |
                 +-----------+                    |
                       ^                          v
                       |                    +--------------------+
                       |   3. Emit events   |                    |
                       +------------------- | ContentInitializer |
                                            |                    |
                                            +--------------------+
```

During the various events happening on content playback, the ContentInitializer will
create / destroy / update various player submodules.

Example of such submodules are:

- Adaptive streaming management
- DRM handling
- Manifest loading, parsing and refreshing
- Buffer management
- ...

## Usage

Concretely, the ContentInitializer is a class respecting a given interface, allowing to:

- prepare a future content for future play - without influencing a potentially
  already-playing content (e.g. by pre-loading the next content's Manifest).

- start loading the content on a given media element

- communicate about various playback events

### Emitted Events

Events allows the ContentInitializer to reports milestones of the content playback, such
as when the content is ready to play.

It's also a way for the `ContentInitializer` to communicate information about the content
and give some controls to the user.

For example, as available audio languages are only known after the manifest has been
downloaded and parsed, and as it is most of all a user preference, the ContentInitializer
can emit to the API, objects allowing the API to "choose" at any time the wanted language.

### Playback rate management

The playback rate (or speed) is updated by the ContentInitializer.

There can be three occasions for these updates:

- the API set a new speed

- the content needs to build its buffer.

  In which case, the playback speed will be set to 0 (paused) even if the API set another
  speed.

- the content has built enough buffer to un-pause. The regular speed set by the user will
  be set again in that case.
