Channel control plugin

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 (view full)

Constructors

Properties

name: string
settings: ChannelSettings
Name: string = CHANNEL_CONTROL_PLUGIN_NAME

Accessors

  • get loaded(): 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.

    Returns boolean

  • set loaded(loaded): void
  • Parameters

    • loaded: boolean

    Returns void

  • get muted(): 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.

    Returns boolean

  • set muted(muted): void
  • Parameters

    • muted: boolean

    Returns void

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

    Returns string

Methods

  • Adds an event listener for a specific event.

    Parameters

    • type: string

      Event type.

    • callback: Listener

      Listener callback function.

    Returns void

  • Prepare for an element being removed, doing necessary cleanup.

    Parameters

    • Rest ...elements: HTMLMediaElement[]

    Returns void

  • Unregisters itself with the player and removes all internal and external event listeners.

    Returns void

  • Get the current waveform data for each track. The return value is a Record<string, Float32Array>, where the keys are track id's and the values are Float32Array's containing the waveform data for that track. The length of the Float32Array is the fftSize (see setting) and each value represent a sample.

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

    Returns Record<string, Float32Array>

  • Return the sample rate of the underlying web audio api AudioContext, or undefined if uninitialized.

    Returns number

  • Return the state of the underlying web audio api AudioContext, or undefined if uninitialized.

    Returns AudioContextState

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

    Parameters

    • idOrSrc: string

      The source url of the track.

    Returns ChannelData

  • Returns the waveforms data for each channel for the loudest part (part size determined by the fftSize setting) of the audio under a given duration.

    Parameters

    • idOrSrc: string | symbol

      The source of the track

    • Optional options: {
          duration: number;
          progress?: ((current) => void);
      }

      The options of the analysis

      • duration: number

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

      • Optional progress?: ((current) => void)

        Optional callback to get the current highest measured value.

          • (current): void
          • Parameters

            • current: number[]

            Returns void

    Returns Promise<MaxRMSDbResult>

    A promise containing the max measured dB value for each channel along with the waveform data for that particular part.

  • 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

  • Return the muted state of all channels for a specific track.

    Parameters

    • idOrSrc: string

      The source url of the track.

    Returns MutedState[]

  • 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[]

  • Returns the gain of the specified track at position index. Returns null if track does not exist or channels are not initialized.

    Parameters

    • idOrSrc: string

      identifier or source of the track

    • index: number

      index of the channel

    Returns number

    gain if available, else null.

  • 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[]

  • Get the max RMS dB value for all tracks combined under a given time.

    Parameters

    • duration: number = 150

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

    • Optional progress: ((current) => void)

      Optional callback to get the current highest measured value.

        • (current): void
        • Parameters

          • current: number[]

          Returns void

    Returns Promise<number>

    A promise containing the max measured combined dB value for all tracks.

    Deprecated

    Use getTrackMaxRMSdB instead.

  • Returns the master output volume.

    Returns 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) => void)

      Optional callback to get the current highest measured value.

        • (current): void
        • Parameters

          • current: number[]

          Returns void

    Returns Promise<number[]>

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

    Deprecated

    Use getChannelMaxRMSdB instead.

  • Returns Uint8Array

  • Returns Float32Array

  • 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.

  • Plugin actions are optional and by default a plugin does not contain any actions.

    Returns PluginAction[]

  • Return the current channel routing for an audio track.

    Parameters

    • idOrSrc: string

      The source url of the track.

    Returns RouteMap

  • Returns the waveforms data for each track for the loudest part (part size determined by the fftSize setting) of the audio under a given duration.

    Parameters

    • Optional options: {
          duration: number;
          progress?: ((current) => void);
      }

      The options of the analysis

      • duration: number

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

      • Optional progress?: ((current) => void)

        Optional callback to get the current highest measured value.

          • (current): void
          • Parameters

            • current: number[]

            Returns void

    Returns Promise<MaxRMSDbResult>

    A promise containing the max measured dB value for each channel along with the waveform data for that particular part.

  • Returns boolean

  • Check if plugins already tracks an element.

    Parameters

    • element: HTMLMediaElement

      The element to check.

    Returns boolean

    true if tracking.

  • 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

  • Mutes the master output volume.

    Returns void

  • Alias method for removeEventListener.

    Parameters

    • type: string

      Event type.

    • callback: Listener

      Listener callback function.

    Returns void

  • Alias method for addEventListener.

    Parameters

    • type: string

      Event type.

    • callback: Listener

      Listener callback function.

    Returns void

  • Register one or more audio tracks.

    Parameters

    Returns void

  • Removes an event listener for a specific event.

    Parameters

    • type: string

      Event type.

    • callback: Listener

      Listener callback function.

    Returns 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

  • Resets channel routing for all current tracks to default routing defined by ChannelSettings.channelRouter

    Returns 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.

  • Method for checking if routing is different from default routing (defined by ChannelSettings.channelRouter) or not.

    Returns boolean

    true if routing != default routing, else false

  • Set the gain on the channel of specified track on specified index.

    Parameters

    • idOrSrc: string

      The identifier or source of the track

    • index: number

      Index of the channel

    • gain: number

      The gain value

    Returns void

    Throws

    Error if track does not exist or channel with index does not exist.

  • 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

  • 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 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

  • 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.

    • Optional newChannelInterpretation: ChannelInterpretation

      the channelInterpretation of the new proxy, keeps previous proxies channel interpretation if unset.

    Returns 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

  • Unmutes the master output volume.

    Returns void

  • Unregisters one or more audio tracks using their native HTML element.

    Parameters

    • Rest ...elements: HTMLMediaElement[]

      The media elements.

    Returns 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 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