Skip to content

Module: src/util/AudioChain

The AudioChain component implements an own audio processing chain for the player, where other components can insert their own processing chains in order to add effects, filters, analyzers or other processing. This component ensures that all audio is routed through a consistent and controllable flow and also automatically suspends or resumes audio processing based on the media's playback state. If no external AudioNodes are attached, the audio is simply passed through. As soon as other modules insert nodes into the chain, they are automatically connected in a logical sequence, and disconnected when removed. Please note that this component has some limitations when building the audio graph, so it is recommended to add AudioNodes early during initialization and not change the graph later on.

Version
1.1.0
Author
Frank Kudermann - alphanull
License
MIT
Source
AudioChain.js, line 11

Constructor

new AudioChain(player, parent, optionsopt)

Creates an instance of the AudioChain component.

Parameters:
Name Type Attributes Description
player Player

The player instance.
parent Player

Reference to the parent instance.
options Object optional

Additional options.

Parameters:
Name Type Attributes Description
apiKey symbol optional

Token for extended access to the player API.

Members

Reference to the main player instance.

Type
Player
Source
AudioChain.js, line 17

Holds tokens of subscriptions to player events, for later unsubscribe.

Type
Array<number>
Source
AudioChain.js, line 23

Holds tokens of subscriptions to engine events, for later unsubscribe.

Type
Array<number>
Source
AudioChain.js, line 29

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
AudioChain.js, line 36

The Web Audio API context.

Type
AudioContext
Source
AudioChain.js, line 42

The Master Gain Node. All nodes will eventually connect to masterGain -> speakers.

Type
AudioNode
Source
AudioChain.js, line 48

List of registered audio nodes.

Type
Array<{input: AudioNode, output: (AudioNode|null), order: number}>
Source
AudioChain.js, line 54

The MediaElementSourceNode connected to the video element. Will be set in connectVideo().

Type
MediaElementAudioSourceNode | null
Source
AudioChain.js, line 60

Timeout id delaying suspending.

Type
number
Source
AudioChain.js, line 66

Methods

private #getContext(apiKey) → AudioContext

Provides the audio context of this component.

Parameters:
Name Type Description
apiKey symbol

Token needed to grant access in secure mode.
Returns

The current AudioContext.

Type AudioContext
Throws

If safe mode access was denied.

Type Error
Source
AudioChain.js, line 106

private #addNode(input, output, orderopt, apiKey)

Inserts an audio node into the internal processing chain. This method expects the input and output (or null if no output is defined, as with analysers) of the processing chain to be inserted, and optionally an order value which determines when the inserted chain will be executed.

Parameters:
Name Type Attributes Description
input AudioNode

Input node receiving audio.
output AudioNode | null

Output node passing audio forward (null if not chaining).
order number optional

Sorting index for node processing order.
apiKey symbol

Token needed to grant access in secure mode.
Throws

If safe mode access was denied.

Type Error
Source
AudioChain.js, line 125

private #removeNode(input, output, apiKey)

Removes a previously added audio node from the processing chain. This method expects the input and outputs of the processing chain to be removed from the 'master chain'.

Parameters:
Name Type Description
input AudioNode

Input node to remove.
output AudioNode | null

Output node to remove.
apiKey symbol

Token needed to grant access in secure mode.
Throws

If safe mode access was denied.

Type Error
Source
AudioChain.js, line 146

private #connectVideo()

Connects the MediaElementAudioSourceNode to the Web Audio graph. Ensures that only one instance of mediaSource exists.

Listens
media/ready
Source
AudioChain.js, line 170

private #disconnectVideo()

Disconnects the MediaElementAudioSourceNode.

Listens
data/ready
Source
AudioChain.js, line 184

private #suspendAudio()

Suspends the audio context with a delay after pausing.

Listens
media/pause
Source
AudioChain.js, line 196

private #resumeAudio()

Resumes the audio context immediately when playback starts.

Listens
media/play
Source
AudioChain.js, line 207

private #connectAudio()

Builds the audio processing chain and connects nodes in the correct order.

Source
AudioChain.js, line 216

private #disconnectAudio()

Disconnects all audio nodes and resets the processing chain.

Source
AudioChain.js, line 241

private #enable()

Enables the audio chain subscriptions and (re)connects on media events.

Listens
player/engine/set
Source
AudioChain.js, line 259

private #disable(optionsopt)

Disables the audio chain subscriptions and optionally disconnects.

Parameters:
Name Type Attributes Description
options Object optional

Options controlling teardown.

Parameters:
Name Type Attributes Default Description
suspend boolean optional false

If true, keep connections (no disconnect).
Listens
player/engine/set
Source
AudioChain.js, line 276

destroy()

Completely tears down the audio system. Unsubscribes from all events, removes nodes, and closes the audio context.

Source
AudioChain.js, line 286