AudioWorkletNode.parameters — Eigenschaft · JavaScript-Referenz

Signatur

AudioWorkletNode.parameters

Beschreibung

Die Eigenschaft parameters eines AudioWorkletNode gibt eine AudioParamMap zurück. Darin stehen alle AudioParam-Objekte, die der zugehörige AudioWorkletProcessor über seinen statischen Getter parameterDescriptors festgelegt hat. Schlüssel ist jeweils der Parametername, Wert das passende AudioParam-Objekt.

Mit diesen Parametern steuerst du einen eigenen Audio-Prozessor vom Haupt-Thread aus, genau wie eingebaute Knoten (z. B. GainNode.gain). Du kannst Werte direkt über value setzen, zeitgenau planen (setValueAtTime(), linearRampToValueAtTime() …) oder andere Audioknoten wie einen OscillatorNode als LFO mit dem Parameter verbinden.

Die AudioParamMap verhält sich wie eine schreibgeschützte Map. Sie bietet get(), has(), keys(), values(), entries(), forEach() und size, aber weder set() noch delete(). Neue Parameter kannst du zur Laufzeit nicht hinzufügen. Sie werden allein durch parameterDescriptors im Prozessor bestimmt.

Rückgabewert

Typ

AudioParamMap

Beschreibung

Eine schreibgeschützte, Map-ähnliche Sammlung, die Parameternamen (string) auf AudioParam-Objekte abbildet.

Beispiele

Prozessor mit eigenem Parameter definieren und steuern

// gain-processor.js (läuft im AudioWorkletGlobalScope)
class GainProcessor extends AudioWorkletProcessor {
  static get parameterDescriptors() {
    return [{ name: 'gain', defaultValue: 1, minValue: 0, maxValue: 1, automationRate: 'a-rate' }];
  }
  process(inputs, outputs, parameters) {
    const input = inputs[0];
    const output = outputs[0];
    const gain = parameters.gain; // Länge 1 (konstant) oder 128 (automatisiert)
    for (let ch = 0; ch < input.length; ch++) {
      for (let i = 0; i < input[ch].length; i++) {
        output[ch][i] = input[ch][i] * (gain.length > 1 ? gain[i] : gain[0]);
      }
    }
    return true;
  }
}
registerProcessor('gain-processor', GainProcessor);

// main.js
const ctx = new AudioContext();
await ctx.audioWorklet.addModule('gain-processor.js');
const node = new AudioWorkletNode(ctx, 'gain-processor');
const osc = new OscillatorNode(ctx);
osc.connect(node).connect(ctx.destination);
osc.start();

const gainParam = node.parameters.get('gain');
gainParam.value = 0.5;
console.log(gainParam.value, gainParam.maxValue);

0.5 1

Alle Parameter auflisten

const ctx = new AudioContext();
await ctx.audioWorklet.addModule('gain-processor.js');
const node = new AudioWorkletNode(ctx, 'gain-processor');

console.log(node.parameters.size);
for (const [name, param] of node.parameters) {
  console.log(`${name}: default=${param.defaultValue}, min=${param.minValue}, max=${param.maxValue}`);
}
console.log(node.parameters.has('frequency'));

1 gain: default=1, min=0, max=1 false

Parameter automatisieren und per LFO modulieren

const ctx = new AudioContext();
await ctx.audioWorklet.addModule('gain-processor.js');
const node = new AudioWorkletNode(ctx, 'gain-processor', {
  parameterData: { gain: 0 } // Startwert beim Erzeugen
});
const gain = node.parameters.get('gain');

// Einblenden über 2 Sekunden
const now = ctx.currentTime;
gain.setValueAtTime(0, now);
gain.linearRampToValueAtTime(0.8, now + 2);

// Alternativ: Tremolo über einen LFO
const lfo = new OscillatorNode(ctx, { frequency: 5 });
const depth = new GainNode(ctx, { gain: 0.2 });
lfo.connect(depth).connect(gain); // AudioNode -> AudioParam
lfo.start();

// Wichtig · Fallstricke

Nur lesbar: node.parameters = … hat keine Wirkung. Auch die Map selbst kennt weder set() noch delete(). Werte änderst du immer über das jeweilige AudioParam.
Gibt es einen Namen nicht, liefert get() undefined. Ein Tippfehler führt dann erst beim Zugriff auf .value zu einem TypeError.
Startwerte übergibst du am besten über parameterData im Konstruktor. Das ist zuverlässiger, als value direkt danach zu setzen.
Im process()-Callback ist das Array eines Parameters entweder 1 Element lang (Wert im Block konstant) oder 128 Elemente lang (Wert ändert sich im Block, bei a-rate). Beide Fälle musst du behandeln.
Werte außerhalb von minValue/maxValue werden stillschweigend begrenzt.
Kompatibilität: AudioWorklet funktioniert nur in sicheren Kontexten (HTTPS oder localhost). Chrome unterstützt es seit Version 66, Firefox seit 76, Safari seit 14.1. Das veraltete ScriptProcessorNode hat keine vergleichbaren Parameter.

Siehe auch

AudioWorkletProcessor.parameterDescriptors AudioWorkletNode.port AudioWorklet: port AudioWorkletProcessor.port VRDisplay.stageParameters