Player

The Player class is the core entry point of the entire system. It is responsible for instantiating and configuring all registered subcomponents, setting up the DOM environment, handling component state, managing the overall player configuration, and providing the main API for interacting with the player.

Configuration

Configuration example with defaults:

const playerConfig = {
    player: {
        id: '',
        secureApi: false,
        initOnIntersection: false,
        initOnIdle: false
    }
};

Setting Name	Type	Description
`id`	String	Defines custom player id. To be used in conjunction with the pubsub event system to access events outside the player instance. If omitted, the id will be autogenerated.
`secureApi`	Boolean	If secureApi is enabled, certain APIs are unavailable or restricted to internal use, like `getComponents()`, `getElement()` or `getMediaElement()`. In addition, the instance is sealed after components are intialised.
`initOnIntersection`	Boolean	Intersection Observer config. If `true`, the player will be initialized only if it is visible in the viewport (using Intersection Observer on the target element). If an object is provided, it will be used as the observer config.
`initOnIdle`	Boolean	If `true`, the player will be initialized only when the browser is idle.

API

The following API functions are available:

Method	Arguments	Returns	Description
`getComponent`	`componentPath` (String) `apiKey` (Symbol)	Component Class	Returns a registered component by path, e.g., 'ui.scrubber'. Requires valid apiKey in secure mode.
`initConfig`	`key` (String) `defaults` (Object) = true	Extended Config Value	Initializes a configuration section by providing a key for the desired config section. If the property does not exist yet, it is created using the provided defaults (defaults to true). Used by components to retrieve and initialize their individual configuration.
`getConfig`	`searchPath` (String)	Config Value (object or primitive)	Gets the current config, as a whole or just a fragment based on the searchPath.
`setConfig`	`config` (Object) `reinitialize` (Boolean)		Extends the existing config with the provided object. Optionally re-initializes the player.
`getClient`	`key` (String)	Client Value (object or primitive)	Returns player client information, either a property selected by the key or a clone of the whole client object.
`getState`	`namespace` (String)	State Value (object or primitive)	Returns player state, either a property selected by the key or a clone of the whole state object.
`setState`	`namespace` (String) `descriptor` (Object) [`apiKey`] (Symbol)		Set the internal state property using a namespace (separated by "." like `ui.show`) and a descriptor object (which must contain a getter that returns the new state value). Requires valid `apiKey` in secure mode. State properties should generally be read-only.
`removeState`	`namespaces` (Array) [`apiKey`] (Symbol)		Remove one or more namespaces (provided as an array of strings) from the internal state object. Requires valid apiKey in secure mode.
`setApi`	`namespace` (String) `method` (Function) [`isPrivate`] (Boolean) [`apiKey`] (Symbol)		Adds a component method to the player API. This method adds the api method to the instance, as opposed to Player.setApi, which adds an API method to the constructor. If `isPrivate` is set, the method will only be available on the Player class itself through #privateApi. Requires valid apiKey in secure mode. NOTE: This does not check for existing methods with the same name, effectively allowing to override the API.
`removeApi`	`namespaces` (Array) [`apiKey`] (Symbol)		Removes one or more instance API methods. Requires valid apiKey in secure mode. Not available if instance was frozen.
`subscribe`	`topic` (String) `handler` (Function) [`options`] (Object)	Subscribe Token (Number)	Subscribe to an internal event or topic using the player's Pub/Sub wrapper. handler is a callback function, options may include filtering or priority settings.
`unsubscribe`	`topicOrToken` (Boolean/String/Array) `handler` (Function)		Unsubscribe from an event. You can pass either the topic name & handler or the token returned by subscribe().
`publish`	`topic` (String) `data` (Object) [`options`] (Object) [`apiKey`] (Symbol)		Publish an event to a topic with optional payload data and options. Requires valid apiKey in secure mode.
`destroy`			Clean up and remove the player instance, including all components, event listeners, and DOM references. After calling this, the instance is no longer usable.
Static API
`Player.addComponent`	`path` (String) `Component` (Function) [`config`] (Object)		Register a new component at the given path. The `Component` must be a valid class or factory function. `config` is an optional default configuration used by the component upon instantiation. Only available in non-secure builds (i.e. extensible mode).
`Player.setApi`	`key` (String) `method` (Function)		Globally override or add a new player-wide API method named key. Only available before instantiating any players, and not in the secure build.
`Player.removeApi`	`key` (String)		Remove one or more global API methods before they are bound to any player instance. Not available in the secure build.
`Player.setDefaultConfig`	`config` (Object)		Define a default configuration object that will be applied to all new player instances. Not available in the secure build.
`Player.getFormats`			Returns a cloned list of all supported media formats.
`Player.addFormat`	`format` (Object)		Adds a new format definition to the global format registry

Player

Configuration

API

Settings