VisionPlayer Documentation | Module: src/core/Player

Version: 1.2.0
Author: Frank Kudermann - alphanull
License: MIT
Requires: publisher; object
Source: Player.js, line 14

Constructor

new Player(target, mediaData, playerConfigopt)

Creates a new Player instance.

Parameters:

Name	Type	Attributes	Description
`target`	string \| HTMLElement		HTML element (or a selector) to which the player should be attached to (or which should be replaced).
`mediaData`	Object		The media data object.
`playerConfig`	Object	optional	Player configuration object.

Throws: If player id is invalid.

Type Error; If query selector is invalid.

Type Error; If player config is invalid.

Type Error

Members

private #config :Object

Holds the global player configuration as the central storage.

Properties

Name	Type	Attributes	Default	Description
`secureApi`	boolean	optional	false	If secure mode is enabled, certain APIs are restricted to internal use, like getComponents(), getElement() or getMediaElement(). In addition, the instance is sealed after components are intialised.
`id`	string	optional	''	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.
`initOnIntersection`	boolean \| Player~intersectionObserverConfig	optional	false	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	optional	false	If `true`, the player will be initialized only when the browser is idle.

Type: Object
Source: Player.js, line 24

private #id :string

Internal client ID, used for connecting via PubSub. Can be generated internally or filled with a custom value when instantiating.

Type: string
Source: Player.js, line 38

private #apiKey :symbol

Secret key only known to the player instance and initialized components. Used to be able to restrict access to API methods in conjunction with secure mode.

Type: symbol
Source: Player.js, line 45

private #privateApi :Object

Holds functions provided by other components which are private to this class.

Type: Object
Source: Player.js, line 51

private #components :Map

Holds the initialized (live) component tree.

Type: Map
Source: Player.js, line 57

private #namespaces :Set

Stores references to any namesets that+0may have been created using addApi(). Used to freeze namespaces in secure mode.

Type: Set
Source: Player.js, line 64

private #apiMethods :Map

Map holding the api methods for proxy access.

Type: Map
Source: Player.js, line 70

private #state :Object

The current state of the player.

Type: Object
Source: Player.js, line 76

private #client :Object

Object containing various information about the client. Can be used by other components for feature detection etc.

Type: Object
Source: Player.js, line 82

private #engines :Object

Object containing the available media engines.

Type: Object
Source: Player.js, line 88

private #currentEngine :Object

The current engine.

Type: Object
Source: Player.js, line 94

private #intersectionObserver :IntersectionObserver

Intersection Observer instance.

Type: IntersectionObserver
Source: Player.js, line 100

private #idleCallback :number

Idle callback.

Type: number
Source: Player.js, line 106

private, static #formats :Array<Player~mediaFormat>

Array holding supported media formats, containing associated extensions and mime type.

Type: Array<Player~mediaFormat>
Source: Player.js, line 737

private, static #registeredComponents :Object

Holds component objects available to be initialized with each player instance.

Type: Object
Source: Player.js, line 804

private, static #defaultConfig :Object

Holds global defaults which apply to each instance created.

Type: Object
Source: Player.js, line 810

private, static #idCounter :number

Internal counter appended to autogenerated IDs.

Type: number
Source: Player.js, line 816

Methods

private #initialise(mergedData)

Initializes the player. May be invoked by intersection observer or directly.

Parameters:

Name	Type	Description
`mergedData`	Object	The merged media data.

Source: Player.js, line 199

private #launchComponents(parent, registeredTree, activeTree)

Launches all registered components by recursively walking the component tree.

Parameters:

Name	Type	Description
`parent`	Object	Parent component (equals `this` on the first call).
`registeredTree`	Map	Static "component registry" in Player.components.
`activeTree`	Map	Tree of currently instantiated components (under `this.components`).

Source: Player.js, line 234

private #removeComponents(compsopt, excludesopt)

Recursively removes components from the component tree, optionally excluding a certain key.

Parameters:

Name	Type	Attributes	Description
`comps`	Object	optional	The sub-tree of components to remove.
`excludes`	Array<string>	optional	If specified, skip removing components.

Source: Player.js, line 254

getComponent(componentPath, apiKeyopt) → Object|false

Returns a "live" component instance by a path. Not recommended for external usage.

Parameters:

Name	Type	Attributes	Description
`componentPath`	string		The path to the desired component, e.g. "ui.scrubber".
`apiKey`	symbol	optional	Token needed to grant access in secure mode.

Returns: The found component or false.; Type Object | false
Throws: If apiKey does not match in secure mode.

Type Error
Source: Player.js, line 277

canPlay(metaData) → Object|false

Checks if the player can play the given media data. Looks for the first engine that can play the media data and returns the engine id and canPlay result.

Parameters:

Name	Type	Description
`metaData`	Object	The meta data to check. Contains the source and mime type.

Returns: The engine id and canPlay result if found, otherwise false.; Type Object | false
Source: Player.js, line 301

addEngine(engineId, engine, config, apiKeyopt)

Adds a media engine to the player.

Parameters:

Name Type Attributes Description

engineId

string

The id of the engine to add.

engine

Object

The media engine object.

config

Object

The config for the engine.

Parameters:

Name	Type	Description
`capabilities`	Object	The capabilities of the engine, like playback capabilities, audio filtering capabilities, etc.

apiKey

symbol

optional

Token needed to grant access in secure mode.

Throws: If apiKey does not match in secure mode.

Type Error; If engine already exists.

Type Error
Source: Player.js, line 323

removeEngine(engineId, apiKeyopt)

Removes a media engine from the player.

Parameters:

Name	Type	Attributes	Description
`engineId`	string		The id of the engine to remove.
`apiKey`	symbol	optional	Token needed to grant access in secure mode.

Throws: If apiKey does not match in secure mode.

Type Error; If engine does not exist.

Type Error
Source: Player.js, line 338

getEngine(engineIdopt, apiKeyopt) → Object|false

Returns the current engine.

Parameters:

Name	Type	Attributes	Description
`engineId`	string	optional	The id of the engine to get.
`apiKey`	symbol	optional	Token needed to grant access in secure mode.

Returns: The engine object or false if not found.; Type Object | false
Throws: If apiKey does not match in secure mode.

Type Error
Source: Player.js, line 353

async setEngine(newEngine, optionsopt, apiKeyopt)

Sets the current engine, disabling the old engine.

Parameters:

Name Type Attributes Description

newEngine

string

The id of the engine to set.

options

Object

optional

The options for the engine.

Parameters:

Name	Type	Description
`suspend`	boolean	If `true`, the current engine will be suspended.
`resume`	boolean	If `true`, the new engine will be resumed.
`params`	Object	Additional parameters for engine switching.

apiKey

symbol

optional

Token needed to grant access in secure mode.

Fires: engine/set
Throws: If apiKey does not match in secure mode.

Type Error; If engine does not exist.

Type Error
Source: Player.js, line 377

initConfig(key, defaultsopt) → Object

Initializes a configuration section. If the property does not exist yet, it is created using the provided defaults. Used by components to retrieve and initialize their individual configuration.

Parameters:

Name	Type	Attributes	Default	Description
`key`	string			The configuration key to initialize.
`defaults`	Object	optional	true	The default values to apply (used with `extend`). If set to `true`, the current config object is reused as-is.

Returns: The (possibly newly created) config section associated with the given key.; Type Object
Source: Player.js, line 420

getConfig(searchPathopt) → nullable Object

Gets the current config, as a whole or just a fragment based on the searchPath.

Parameters:

Name	Type	Attributes	Description
`searchPath`	string	optional	If provided, only return a fragment of the config matching the key. The key can also hold "sub-paths", which are separated by a dot. Example: `rootKey.childKey`.

Returns: Returns a copy of the desired config object, or null if nothing was found.; Type Object
Source: Player.js, line 435

setConfig(config, reinitializeopt)

Extends the existing config with the provided object. Optionally re-initializes the player.

Parameters:

Name	Type	Attributes	Description
`config`	string \| Object		The config object.
`reinitialize`	boolean	optional	If `true`, remove and re-launch components after changing config.

Throws: If config is not an object.

Type Error
Source: Player.js, line 450

getClient(keyopt) → Object|boolean

Returns player client information, either a property selected by the key or a clone of the whole client object.

Parameters:

Name	Type	Attributes	Description
`key`	string	optional	The key of the desired client property.

Returns: The resulting client info.; Type Object | boolean
Source: Player.js, line 484

getState(namespaceopt) → Object|any

Returns player state, either a property selected by the key or a clone of the whole state object.

Parameters:

Name	Type	Attributes	Description
`namespace`	string	optional	The namespace of the desired state property.

Returns: The resulting state.; Type Object | any
Source: Player.js, line 495

setState(namespace, descriptor, apiKeyopt)

Adds an additional state to the state object.

Parameters:

Name	Type	Attributes	Description
`namespace`	string		The namespace of the new state.
`descriptor`	Object		A property descriptor which must contain a getter that returns the state value. State properties should be readonly, so a setter should not be defined.
`apiKey`	symbol	optional	Token needed to grant access in secure mode.

Throws: If apiKey does not match in secure mode.

Type Error
Source: Player.js, line 509

removeState(namespaces, apiKeyopt)

Removes one or more states from the state object.

Parameters:

Name	Type	Attributes	Description
`namespaces`	Array \| string		The namespace(s) of the state property to be removed.
`apiKey`	symbol	optional	Token needed to grant access in secure mode.

Throws: If apiKey does not match in secure mode.

Type Error
Source: Player.js, line 534

static setApi(namespace, method, isPrivateopt, apiKeyopt)

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 Class itself. NOTE: This does not check for existing methods with the same name, effectively allowing to override the API.

Parameters:

Name	Type	Attributes	Description
`namespace`	string		The API name(space) of the method.
`method`	function		A reference to the method itself.
`isPrivate`	boolean	optional	If `true`, the method will only be available on the Player class itself.
`apiKey`	symbol	optional	Token for extended access to the player API.

Throws: If apiKey does not match in secure mode.

Type Error
Source: Player.js, line 561

static removeApi(namespaces, apiKeyopt)

Removes a method from the players' instance API.

Parameters:

Name	Type	Attributes	Description
`namespaces`	Array \| string		The name(space)s of the method to remove.
`apiKey`	symbol	optional	Token needed to grant access in secure mode.

Throws: If apiKey does not match in secure mode.

Type Error
Source: Player.js, line 612

This should be used by all components when subscribing to some events. In essence this just calls the external publisher library, but prefixes each event topic with 'vip' and the player id, so that they don't need to be added each time manually.

Parameters:

Name Type Attributes Description

topic

string

The topic in which the subscriber is interested. Note that you can use wildcards, ie. The topic * will subscribe to all messages.

handler

function

The handler to execute when a matching message is found.

options

Object

optional

Additional options.

Parameters:

Name	Type	Attributes	Description
`async`	boolean	optional	Specify if we should deliver this message directly or with a timeout. Overrides the global setting.
`handleExceptions`	boolean	optional	Specify if we should catch any exceptions while sending this message. Overrides the global setting.
`persist`	boolean	optional	If this is set to `true`, the subscriber is notified of any former, persistent messages.
`condition`	function	optional	A function which receives this topic and data just before execution, if present. If this returns anything but `true`, the message is not delivered.
`priority`	number	optional	Specifies with which priority the handler should be executed. The higher the number, the higher the priority. Default is `0`, negative values are allowed.

Returns: The internal token of the new subscriber. Can be used for later unsubscribing.; Type number
Source: Player.js, line 665

unsubscribe(topicOrToken, handleropt)

This should be used by all components when UNsubscribing some events. In essence this just calls the external publisher library, but prefixes each event topic with "vip" and the player id, so that they don't need to be added each time manually.

Parameters:

Name	Type	Attributes	Description
`topicOrToken`	number \| string \| Array		The token or the topic to unsubscribe. In the first case, these also can be in an array to support multiple unsubscriptions.
`handler`	function	optional	If specified, the message is only unsubscribed if the handler also matches.

Source: Player.js, line 677

publish(topic, dataopt, optionsopt, apiKeyopt)

Publishes a message to all matching subscribers. In essence this just calls the external publisher library, but prefixes each event topic with "vip" and the player id, so that they don't need to be added each time manually.

Parameters:

Name Type Attributes Default Description

topic

string

The topic of this message, may be separated with '/' for subtopics.

data

Object

optional

The data that should be sent along with the event. Can be basically any javascript object.

options

Object

optional

{}

Additional options.

Parameters:

Name	Type	Attributes	Description
`async`	boolean	optional	Specify if we should deliver this message directly or with a timeout. Overrides the global setting.
`handleExceptions`	boolean	optional	Specify if we should catch any exceptions while sending this message. Overrides the global setting.
`persist`	boolean	optional	If this is set to `true`, the messages is saved for later subscribers which want to be notified of persistent messages.
`cancelable`	boolean	optional	If set to `true`, this message cannot be cancelled (when sending synchronously).

apiKey

symbol

optional

Token for extended access to the player API.

Throws: If apiKey does not match in secure mode.

Type Error
Source: Player.js, line 700

destroy()

This is the "cleanup method" which should be called when removing the player. It is strongly recommended to do so to prevent memory leaks and possible other unwanted side effects. This method removes all component, as well as the player root element.

Source: Player.js, line 717

static addComponent(path, Component, configopt)

Adds (registers) a new component. This method must be invoked on the Class itself, and only components added before creating a player instance will be considered.

Parameters:

Name	Type	Attributes	Description
`path`	string		The path of the component to add. Path segments are separated by `'.'`.
`Component`	Object		The component object or class to be added.
`config`	Object	optional	Additional component config to be injected at build time.

Source: Player.js, line 825

static removeComponent(path)

Removes a component from the global registry. This method must be invoked on the constructor, not the instance. Only components added before creating a player instance will be considered.

Parameters:

Name	Type	Description
`path`	string	The path of the component to add. Path segments are separated by ".".

Source: Player.js, line 852

static setApi(key, method)

Adds a component method to the player API. This method adds the api method to the Class, as opposed to the instance setApi method (see below), which adds an API method to the instance. Warning: this does not check for existing methods with the same name, effectively allowing to override the API.

Parameters:

Name	Type	Description
`key`	string	The API name of the method.
`method`	function	A reference to the method itself.

Source: Player.js, line 875

static removeApi(key)

Removes a method from the players' Class API.

Parameters:

Name	Type	Description
`key`	string	The name of the method to remove.

Source: Player.js, line 885

static setDefaultConfig(config)

Sets the default config for new Player instances.

Parameters:

Name	Type	Description
`config`	Object	The default config to set globally.

Source: Player.js, line 895

static getFormats() → Array<Player~mediaFormat>

Returns a cloned list of all supported media formats. This list defines which file extensions and MIME types are recognized by the player. Formats can be audio, video, or both. Use this method for inspection or debugging purposes.

Returns: A deep clone of the registered format definitions.; Type Array<Player~mediaFormat>
Source: Player.js, line 907

static addFormat(format)

Adds a new format definition to the global format registry. This allows components to register support for additional media types. The format object should contain at least one file extension and a MIME type for either audio or video.

Parameters:

Name	Type	Description
`format`	Player~mediaFormat	The format object to register.

Source: Player.js, line 919

static autoLoad(selector)

Tries to query and convert HTML Elements that match a certain selector into VisionPlayer instances. Also tries to extract config and Media Data.

Parameters:

Name	Type	Default	Description
`selector`	string	[data-vision-player]	The selector to apply.

Source: Player.js, line 930

private, static #extractElementData(ele) → Object

Parses elements and extracts meta- and config data. Looks for data-vip-media and data-vip-config attributes and tries to parse them as string or JSON. If ele is a video or audio element, also tries to get the media data from additional element properties, including subtitles and poster image.

Parameters:

Name	Type	Description
`ele`	HTMLElement	The element to parse.

Returns: Returns an object with extracted data & config from the element.; Type Object
Throws: Throws if no matching element is found or if the selector is invalid.

Type Error
Source: Player.js, line 963

Type Definitions

intersectionObserverConfig

Defines the Intersection Observer config.

Properties

Name	Type	Attributes	Default	Description
`root`	HTMLElement	optional	document	The root element to observe.
`rootMargin`	string	optional	'250px'	The margin around the root element.
`scrollMargin`	string	optional	'0px'	The margin around the scroll container.
`threshold`	number	optional	0	The threshold for the intersection ratio.

Type: Object
Source: Player.js, line 1098

mediaFormat

Defines a supported media format for the player. A format is characterized by its file extensions and optionally by the MIME type for audio and/or video. This structure is used by the player to detect whether a given media file is supported natively or by a plugin.

Properties

Name	Type	Attributes	Description
`extensions`	Array<string>		List of associated file extensions (e.g. `['mp4', 'm4v']`).
`mimeTypeAudio`	string	optional	Optional MIME type for audio streams (e.g. `'audio/mp4'`).
`mimeTypeVideo`	string	optional	Optional MIME type for video streams (e.g. `'video/mp4'`).

Type: Object
Source: Player.js, line 1107

Events

player/engine/set

Fired when a new engine is about to be set.

Parameters:

Name Type Description

data

Object

The data for the event.

Parameters:

Name Type Description

from.id

string

The id of the old engine.

from.capabilities

Object

The capabilities of the old engine.

to.id

string

The id of the new engine.

to.capabilities

Object

The capabilities of the new engine.

options

Object

The options for the engine switch.

Parameters:

Name	Type	Description
`suspend`	boolean	If `true`, the old engine was suspended.
`resume`	boolean	If `true`, the new engine will be resumed.
`params`	Object	Additional parameters for engine switching.

Listeners: AirPlay#disable; Loop#onEngineSet; PictureInPicture#onEngineSet; Play#onEngineSet; PlayOverlay#onEngineSet; Volume#onEngineSet; PlaybackRate#onEngineSet; Subtitles#onEngineSet; Time#onEngineSet; AudioChain#enable; AudioChain#disable; AnalyserVideo#disable
Source: Player.js, line 1070

player/engine/switched

Fired when an engine has been set.

Parameters:

Name Type Description

data

Object

The data for the event.

Parameters:

Name Type Description

from.id

string

The id of the old engine.

from.capabilities

Object

The capabilities of the old engine.

to.id

string

The id of the new engine.

to.capabilities

Object

The capabilities of the new engine.

options

Object

The options for the engine switch.

Parameters:

Name	Type	Description
`suspend`	boolean	If `true`, the old engine was suspended.
`resume`	boolean	If `true`, the new engine will be resumed.
`params`	Object	Additional parameters for engine switching.

Listeners: AirPlay#enable; Scrubber#onEngineSwitched
Source: Player.js, line 1084

Module: src/core/Player

Constructor

new Player(target, mediaData, playerConfigopt)

Members

private #config :Object

private #id :string

private #apiKey :symbol

private #privateApi :Object

private #components :Map

private #namespaces :Set

private #apiMethods :Map

private #state :Object

private #client :Object

private #engines :Object

private #currentEngine :Object

private #intersectionObserver :IntersectionObserver

private #idleCallback :number

private, static #formats :Array<Player~mediaFormat>

private, static #registeredComponents :Object

private, static #defaultConfig :Object

private, static #idCounter :number

Methods

private #initialise(mergedData)

private #launchComponents(parent, registeredTree, activeTree)

private #removeComponents(compsopt, excludesopt)

getComponent(componentPath, apiKeyopt) → Object|false

canPlay(metaData) → Object|false

addEngine(engineId, engine, config, apiKeyopt)

removeEngine(engineId, apiKeyopt)

getEngine(engineIdopt, apiKeyopt) → Object|false

async setEngine(newEngine, optionsopt, apiKeyopt)

initConfig(key, defaultsopt) → Object

getConfig(searchPathopt) → nullable Object

setConfig(config, reinitializeopt)

getClient(keyopt) → Object|boolean

getState(namespaceopt) → Object|any

setState(namespace, descriptor, apiKeyopt)

removeState(namespaces, apiKeyopt)

static setApi(namespace, method, isPrivateopt, apiKeyopt)

static removeApi(namespaces, apiKeyopt)

subscribe(topic, handler, optionsopt) → number

unsubscribe(topicOrToken, handleropt)

publish(topic, dataopt, optionsopt, apiKeyopt)

destroy()

static addComponent(path, Component, configopt)

static removeComponent(path)

static setApi(key, method)

static removeApi(key)

static setDefaultConfig(config)

static getFormats() → Array<Player~mediaFormat>

static addFormat(format)

static autoLoad(selector)

private, static #extractElementData(ele) → Object

Type Definitions

intersectionObserverConfig

mediaFormat

Events

player/engine/set

player/engine/switched

Settings