Options
All
  • Public
  • Public/Protected
  • All
Menu

The channel control plugin enables features to manipulate individual channels within an audio track. The implemented features consist of:

  • volume control at channel level.
  • rerouting of individual channels.
  • analysing data at channel level.

The plugin heavily depends on the Web Audio Api.

How to use

const player = new ProgressivePlayer(...);
const channelControlPlugin = new ChannelControlPlugin(player);

// Url may be the video url provided to the player or the url of a discrete audio track if DiscreteAudioPlugin is used.
channelControlPlugin.mute(url, channelIndex);
channelControlPlugin.solo(url, channelIndex);

By default the plugin register video and discrete audio tracks automatically. It is possible to disable this feature and register the tracks manually.

const player = new ProgressivePlayer(...);
// Initialize player with auto register disabled.
const channelControlPlugin = new ChannelControlPlugin(player, { autoRegister: false });

// Web Audio Api requires that the used HTMLVideoElement have the crossorigin attribute set to anonymous
// if the source domain of the stream differs from the hosted
mediaElement.crossorigin="anonymous"
channelControlPlugin.registerTracks({
  nativeElement: mediaElement,
  channelCount: 2
});

System requirements

The most robust setup in all cases is to use the setting preferredOutputCount = 2 that will downmux the channels to a stereo output. This will work (at least) in, FireFox (Windows) and Chrome.

To get a surround output to work, the browser needs to be able to detect that the system you are using is capable of such features. The most robust browser to detect this is Chrome in Windows and OS X.

Known limitations

Since this plugin is based on the Web Audio Api there are some browser specific bugs as follows.

AudioContext not allowed to start.

The web audio API have a limitation that it is not allowed to start before a user interaction in the page. if this happens you will se a console error stating, The AudioContext was not allowed to start. It must be resumed (or created) after a user gesture on the page. To recover from this, you need to manually call the method resumeAudioContext after first interaction with the application.

Firefox playback rate issue.

https://bugzilla.mozilla.org/show_bug.cgi?id=966247 When activating the Audio context, the playback rate gets reset to 1x and it is from this point not possible to adjust playback rate.

Firefox Linux, only left channel.

https://bugzilla.mozilla.org/show_bug.cgi?id=1435598

In Firefox Linux edition there are issues related to output 5.1 and 7.1 audio. The result is that all channels are mapped to the left channel. Until the bug is resolved we cannot support surround features in Firefox. The bug appears in some form as soon as Firefox detects that the current sound card has surround capabilities.

Encoding restrictions for ABR.

The channel layout property is sensitive when using MSE (Chrome). In order to make it work the following channel layouts are supported:

channels layout
1 mono
2 stereo
3 3.0
4 4.0
5 5.0
6 5.1
7 N/A
8 7.1

Safari issues.

There are some issues with the implementation of Web Audio Api in Safari that is not handled in the current implementation of the plugin. For now, the channel plugin does not support Safari.

Hierarchy

Index

Constructors

constructor

Properties

Readonly name

name: string

Static Name

Name: string = ...

Accessors

asp

  • Returns AudioScrubPlugin

loaded

  • get loaded(): boolean
  • set loaded(loaded: boolean): void
  • Property that states whether this plugin considers itself ready for continued playback based on internal logic. Triggers internal event of type PlayerInternalEventType.LoadedChanged if property value was changed.

    Returns boolean

  • Property that states whether this plugin considers itself ready for continued playback based on internal logic. Triggers internal event of type PlayerInternalEventType.LoadedChanged if property value was changed.

    Parameters

    • loaded: boolean

    Returns void

muted

  • get muted(): boolean
  • set muted(muted: boolean): void
  • Property that states whether this plugin considers itself muted based on internal logic. Triggers internal event of type PlayerInternalEventType.MutedChanged if property value was changed.

    Returns boolean

  • Property that states whether this plugin considers itself muted based on internal logic. Triggers internal event of type PlayerInternalEventType.MutedChanged if property value was changed.

    Parameters

    • muted: boolean

    Returns void

version

  • get version(): string
  • Property describing the plugin name and version.

    Returns string

Methods

addEventListener

  • addEventListener(type: string, callback: Listener): void
  • Adds an event listener for a specific event.

    Parameters

    • type: string

      Event type.

    • callback: Listener

      Listener callback function.

    Returns void

beforeUnregisterElements

  • beforeUnregisterElements(...elements: HTMLMediaElement[]): void
  • Prepare for an element being removed, doing necessary cleanup.

    Parameters

    • Rest ...elements: HTMLMediaElement[]

    Returns void

destroy

  • destroy(): void
  • Unregisters itself with the player and removes all internal and external event listeners.

    Returns void

getAudioContextState

  • getAudioContextState(): AudioContextState
  • Return the state of the underlying web audio api AudioContext, or undefined if uninitialized.

    Returns AudioContextState

getChannelData

  • Get the current values of a specific audio tracks gain values.

    Parameters

    • idOrSrc: string

      The source url of the track.

    Returns ChannelData

getChannelMutedState

  • getChannelMutedState(idOrSrc: string, channel: number): MutedState
  • Return the current muted status of a specific track.

    Parameters

    • idOrSrc: string

      The source url of the audio track.

    • channel: number

      The channel to mute.

    Returns MutedState

getChannelMutedStates

  • getChannelMutedStates(idOrSrc: string): MutedState[]
  • Return the muted state of all channels for a specific track.

    Parameters

    • idOrSrc: string

      The source url of the track.

    Returns MutedState[]

getFloatTimeDomainData

  • getFloatTimeDomainData(idOrSrc: string): Float32Array[]
  • Get the current waveform data for each channel. The return value is an array of Float32, where each Float32array represent a single channel. The length of the channel arrays is the fftSize (see setting) and each value represent a sample. The elements represent the current waveform.

    See web audio api for details: https://webaudio.github.io/web-audio-api/#AnalyserNode-methods

    Parameters

    • idOrSrc: string

      The element to get current data from.

    Returns Float32Array[]

getGains

  • getGains(idOrSrc: string): number[]
  • Get the current volume of individual channelCount for an audio track. This method will return an empty array if; The audio track cannot be found. The audio channels haven't been initialized (e.g. setChannels hasn't been called) and channelCount hasn't been set.

    Parameters

    • idOrSrc: string

      The source of the track.

    Returns number[]

getMasterOutputVolume

  • getMasterOutputVolume(): number
  • Returns the master output volume.

    Returns number

getMaxRMSdB

  • getMaxRMSdB(idOrSrc: string, duration?: number, progress?: (current: number[]) => void): Promise<number[]>
  • Get the max RMS dB value for a track under a given time.

    Parameters

    • idOrSrc: string

      The source of the track.

    • duration: number = 150

      The duration in ms we should analyse (from now, regardless of players pause state).

    • Optional progress: (current: number[]) => void

      Optional callback to get the current highest measured value.

        • (current: number[]): void
        • Parameters

          • current: number[]

          Returns void

    Returns Promise<number[]>

    A promise containing the max measured dB value for each channel.

getOutputChannelCount

  • getOutputChannelCount(): number
  • Return the destination channel count i.e supported output. May differ from setting preferredOutputCount if system limits is lower than the setting.

    Returns number

    number of output channels or -1 if audio context unsupported.

getPluginActions

  • getPluginActions(): PluginAction[]
  • Plugin actions are optional and by default a plugin does not contain any actions.

    Returns PluginAction[]

getRouteMap

  • getRouteMap(idOrSrc: string): RouteMap
  • Return the current channel routing for an audio track.

    Parameters

    • idOrSrc: string

      The source url of the track.

    Returns RouteMap

isMasterOutputMuted

  • isMasterOutputMuted(): boolean
  • Returns boolean

isTracking

  • isTracking(element: HTMLMediaElement): boolean
  • Check if plugins already tracks an element.

    Parameters

    • element: HTMLMediaElement

      The element to check.

    Returns boolean

    true if tracking.

mute

  • mute(idOrSrc: string, channel: number): void
  • Mutes a specific channel for a track. Leaves the gain value unchanged. Channel will be unmarked as solo if soloed before mute. The analyser node will output 0 for the cpecific channel while muted.

    Parameters

    • idOrSrc: string

      The source url of the audio track.

    • channel: number

      The channel to mute.

    Returns void

muteMasterOutput

  • muteMasterOutput(): void
  • Mutes the master output volume.

    Returns void

off

  • off(type: string, callback: Listener): void
  • Alias method for removeEventListener.

    Parameters

    • type: string

      Event type.

    • callback: Listener

      Listener callback function.

    Returns void

on

  • on(type: string, callback: Listener): void
  • Alias method for addEventListener.

    Parameters

    • type: string

      Event type.

    • callback: Listener

      Listener callback function.

    Returns void

registerTracks

  • Register one or more audio tracks.

    Parameters

    Returns void

removeEventListener

  • removeEventListener(type: string, callback: Listener): void
  • Removes an event listener for a specific event.

    Parameters

    • type: string

      Event type.

    • callback: Listener

      Listener callback function.

    Returns void

rerouteChannels

  • rerouteChannels(idOrSrc: string, routeMap: RouteMap): void
  • Reroute the the channels for an audio track to the specified routeMap.

    Parameters

    • idOrSrc: string

      The source url of the track to reroute.

    • routeMap: RouteMap

      The route configuration.

    Returns void

resumeAudioContext

  • resumeAudioContext(): Promise<void>
  • Resumes the underlying web audio api AudioContext. This is needed to recover if the context get stuck in state suspended.

    Returns Promise<void>

    Promise that is resolved when the context is resumed.

setGains

  • setGains(idOrSrc: string, gains: number[]): void
  • Set the volume of individual channels of a specific registered track. Note that the channels array must contain as many values as there are channels in the track.

    Parameters

    • idOrSrc: string

      The Source url of the track.

    • gains: number[]

      The volume value of each specific channel. Range [0, 1]

    Returns void

setMasterOutputVolume

  • setMasterOutputVolume(volume: number): void
  • Sets the master output volume. The nominal min value is 0, but may be set to negative values for phase inversion. The nominal max value is 1, but higher values are allowed. inversion.

    Parameters

    • volume: number

      the volume to set

    Returns void

solo

  • solo(idOrSrc: string, channel: number): void
  • Solo a specific channel in a track. Unmutes the channel if previously muted.

    Parameters

    • idOrSrc: string

      The source url of the audio track.

    • channel: number

      The channel to solo.

    Returns void

switchProxy

  • switchProxy(element: HTMLMediaElement, newSrc: string, newChannelCount?: number, newId?: string): void
  • Update source url to track native element by. Used if native element already initialized.

    Parameters

    • element: HTMLMediaElement

      The native element.

    • newSrc: string

      The new source url.

    • Optional newChannelCount: number

      The channelCount of the new proxy, keeps previous proxies channel count if unset.

    • Optional newId: string

      The new id of the file.

    Returns void

unmute

  • unmute(idOrSrc: string, channel: number): void
  • Unmutes a specific channel in a track. Any channels marked as solo, will be unsoloed.

    Parameters

    • idOrSrc: string

      The source url of the audio track.

    • channel: number

      The channel to unmute.

    Returns void

unmuteMasterOutput

  • unmuteMasterOutput(): void
  • Unmutes the master output volume.

    Returns void

unregisterElements

  • unregisterElements(...elements: HTMLMediaElement[]): void
  • Unregisters one or more audio tracks using their native HTML element.

    Parameters

    • Rest ...elements: HTMLMediaElement[]

      The media elements.

    Returns void

unregisterSources

  • unregisterSources(...sources: string[]): void
  • Unregister one or more audio tracks using the source url.

    Parameters

    • Rest ...sources: string[]

      The id or source url of the audio track(s).

    Returns void

unsolo

  • unsolo(idOrSrc: string, channel: number): void
  • Unsolo a specific channel in a track. Will mute the channel if another channel is muted.

    Parameters

    • idOrSrc: string

      The source url of the audio track.

    • channel: number

      The channel to unsolo.

    Returns void