Skip to content

Module: src/core/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.

Version
1.1.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

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

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

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

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

Type
Object
Source
Player.js, line 51

Holds the initialized (live) component tree.

Type
Map
Source
Player.js, line 57

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

Map holding the api methods for proxy access.

Type
Map
Source
Player.js, line 70

The current state of the player.

Type
Object
Source
Player.js, line 76

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

Type
Object
Source
Player.js, line 82

Intersection Observer instance.

Type
IntersectionObserver
Source
Player.js, line 88

Idle callback.

Type
number
Source
Player.js, line 94

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

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

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

Type
Object
Source
Player.js, line 656

Holds global defaults which apply to each instance created.

Type
Object
Source
Player.js, line 662

Internal counter appended to autogenerated IDs.

Type
number
Source
Player.js, line 668

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 189

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 224

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 244

getComponent(componentPath, apiKey) → Object|false

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

Parameters:
Name Type Description
componentPath string

The path to the desired component, e.g. "ui.scrubber".
apiKey symbol

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 267

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 293

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 308

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 323

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 356

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 367

setState(namespace, descriptor, apiKey)

Adds an additional state to the state object.

Parameters:
Name Type 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

Token needed to grant access in secure mode.
Throws

If apiKey does not match in secure mode.

Type Error
Source
Player.js, line 381

removeState(namespaces, apiKey)

Removes one or more states from the state object.

Parameters:
Name Type Description
namespaces Array | string

The namespace(s) of the state property to be removed.
apiKey symbol

Token needed to grant access in secure mode.
Throws

If apiKey does not match in secure mode.

Type Error
Source
Player.js, line 408

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 437

static removeApi(namespaces, apiKey)

Removes a method from the players' instance API.

Parameters:
Name Type Description
namespaces Array | string

The name(space)s of the method to remove.
apiKey symbol

Token needed to grant access in secure mode.
Throws

If apiKey does not match in secure mode.

Type Error
Source
Player.js, line 473

subscribe(topic, handler, optionsopt) → number

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 518

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 530

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 553

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 570

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 677

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 704

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 727

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 737

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 747

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 759

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 771

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 782

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 815

Type Definitions

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 922

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 931