The AudioParamDescriptor
dictionary of the Web Audio API specifies properties for an AudioParam
objects. It is used to create custom AudioParam
s on an AudioWorkletNode
. If the underlying AudioWorkletProcessor
has a parameterDescriptors
static getter, then the returned array of objects based on this dictionary is used internally by AudioWorkletNode
constructor to populate its parameters
property accordingly.
Properties
name
- The
DOMString
which represents the name of theAudioParam
. Under this name theAudioParam
will be available in theparameters
property of the node, and under this name theAudioWorkletProcessor.process
method will acquire the calculated values of thisAudioParam
. automationRate
Optional- Either
"a-rate"
, or"k-rate"
string which represents an automation rate of thisAudioParam
. Defaults to"a-rate"
. minValue
Optional- A
float
which represents minimum value of theAudioParam
. Defaults to-3.4028235e38
. maxValue
Optional- A
float
which represents maximum value of theAudioParam
. Defaults to3.4028235e38
. defaultValue
Optional- A
float
which represents initial value of theAudioParam
. Defaults to0
.
Examples
To demonstrate creation and usage of custom AudioParam
s, we'll expand the example from AudioWorkletNode
page. There we've created a simple node which outputs white noise. Here, additionally, we'll create a custom gain parameter, so we can directly change volume of the output (although you could use GainNode
to achieve this as well).
First, we need to define a custom AudioWorkletProcessor
, and register it. Note that this should be done in a separate file.
We expand the processor by adding a static parameterDescriptors
getter. It will be used internally by the AudioWorkletNode
constructor to populate its parameters
with instantiated AudioParam
objects.
// white-noise-processor.js class WhiteNoiseProcessor extends AudioWorkletProcessor { static get parameterDescriptors () { return [{ name: 'customGain', defaultValue: 1, minValue: 0, maxValue: 1, automationRate: 'a-rate' }] } process (inputs, outputs, parameters) { const output = outputs[0] output.forEach(channel => { for (let i = 0; i < channel.length; i++) { channel[i] = (Math.random() * 2 - 1) * (parameters['customGain'].length > 1 ? parameters['customGain'][i] : parameters['customGain'][0]) // note: a parameter contains an array of 128 values (one value for each of 128 samples), // however it may contain a single value which is to be used for all 128 samples // if no automation is scheduled for the moment. } }) return true } } registerProcessor('white-noise-processor', WhiteNoiseProcessor)
Next, in our main scripts file we'll load the processor, create an instance of AudioWorkletNode
passing it the name of the processor, and connect the node to an audio graph.
const audioContext = new AudioContext() await audioContext.audioWorklet.addModule('white-noise-processor.js') const whiteNoiseNode = new AudioWorkletNode(audioContext, 'white-noise-processor') whiteNoiseNode.connect(audioContext.destination)
Now we can change the gain on the node like this:
const gainParam = whiteNoiseNode.parameters.get('customGain') gainParam.setValueAtTime(0, audioContext.currentTime) gainParam.linearRampToValueAtTime(0.5, audioContext.currentTime + 0.5)
Specifications
Specification | Status | Comment |
---|---|---|
Web Audio API The definition of 'AudioParamDescriptor' in that specification. |
Working Draft | Initial definition. |
Browser compatibility
No compatibility data found. Please contribute data for "api.AudioParamDescriptor" (depth: 1) to the MDN compatibility data repository.