Life cycle

Once we create the Paella Player instance, it can be in three load states:

• Unloaded: The Paella Player instance is created. In this state all static parameters of the player are defined (configuration, available plugins, etc.).
• Manifest loaded: In this state the configuration, dictionaries, video manifest and some types of early loading plugins (data, keyboard shortcuts, event tracking and the like) have been loaded.
• Loaded: In this state, the video streams, the video layout plugins, the user interface and the rest of the plugins are loaded.

Switch player state

There are different cases in which it is useful to switch between these states, for example, in SPA applications where we want to reload a different video, or in long lists of videos where we want to download some of them to free resources.

They are several APIs with which we can move between theese states:

import { Paella, PlayerState, PlayerStateNames } from 'paella-core';

...

const player = new Paella('container-id', initData);

console.log(PlayerStateNames[player.state]);    // UNLOADED

await player.loadManifest();
console.log(PlayerStateNames[player.state]);    // MANIFEST

await player.loadPlayer();
console.log(PlayerStateNames[player.state]);    // LOADED

await player.unloadPlayer();
console.log(PlayerStateNames[player.state]);    // MANIFEST

await player.unloadManifest();
console.log(PlayerStateNames[player.state]);    // UNLOADED

// Load and unload paella player in one step
await player.load();
console.log(PlayerStateNames[player.state]);    // Loaded

await player.unload();
console.log(PlayerStateNames[player.state]);    // Unloaded

// Reload paella player
await player.reload();

If you are using Paella Player in a SPA application, you can use the reload() function to unload the player, do some action and reload it again. You can specify the action as a parameter using a function that can be asynchronous if you need it:

await player.reload(() => {
  // This code is executed fater unload the player,
  // and before loading it again
  localtion.hash = 'id=other-video-id';
})

In addition, the reload() function can be used while Paella Player is in any loading state. If state is UNLOADED, the reload() function works in the same way as load(). In other cases, the player will be partialy or fully unloaded, depending on the state.

Life cycle exceptions

There are certain functions that can only be called in a specific state. Other functions modify their behavior depending on the player state:

Function	Required state
load()	Any
unload()	Any
reload()	Any
loadManifest()	PlayerState.UNLOADED
loadPlayer()	PlayerState.MANIFEST
unloadManifest()	PlayerState.MANIFEST
unloadPlayer()	PlayerState.LOADED

If any of these functions are used in an unsuitable state, Paella Player will throw an exception.

Life cycle and events

It is important to note that when the player is downloaded, the registered event handlers will be deleted if we do not indicate otherwise. See all the information about event handlers in this document.

Transitional states

The change from one state to another in the lifecycle is usually not instantaneous. For example, depending on the bandwidth of the connection, moving from the MANIFEST state to the LOADED state may take a few seconds. There are four extra states that are generated during these transitions:

Source state	Destination state	Transitional state
PlayerState.UNLOADED	PlayerState.MANIFEST	PlayerState.LOADING_MANIFEST
PlayerState.MANIFEST	PlayerState.LOADED	PlayerState.LOADING_PLAYER
PlayerState.LOADED	PlayerState.MANIFEST	PlayerState.UNLOADING_PLAYER
PlayerState.MANIFEST	PlayerState.UNLOADED	PlayerState.UNLOADING_MANIFEST

Error state

If an error occurs while loading a video, the player will remain in an ‘ERROR’ state. This state is only used to indicate that an error has occurred. Otherwise, the internal state of the player remains the same as in the UNLOADED state.

From the ERROR state it is possible to restart the loading of a video. If the error in the video upload has been solved (for example, if we change the video identifier to be uploaded), the upload can be performed correctly.

It is important to note that, once an error has occurred, the unload() function must first be called to reload the player.