AudioParamMap — Schnittstelle · JavaScript-Referenz

Signatur

interface AudioParamMap

Beschreibung

Die Schnittstelle AudioParamMap der Web Audio API ist eine schreibgeschützte, Map-ähnliche Sammlung. Jeder Schlüssel ist ein Parametername (string), jeder Wert ein AudioParam-Objekt. In der Praxis begegnet man ihr fast ausschließlich über die Eigenschaft AudioWorkletNode.parameters.

Die Parameter entstehen nicht per Code auf der Hauptseite. Sie werden im AudioWorkletProcessor über den statischen Getter parameterDescriptors festgelegt. Beim Erzeugen des AudioWorkletNode baut der Browser daraus die Map auf. Einträge lassen sich danach nicht mehr hinzufügen oder löschen. Die einzelnen AudioParam-Objekte kann man aber ganz normal steuern: mit value, setValueAtTime(), linearRampToValueAtTime() oder durch Anschließen eines anderen Knotens per connect().

Zum Lesen stehen die üblichen Methoden einer Map bereit: get(), has(), keys(), values(), entries(), forEach() und die Eigenschaft size. Die Map ist durchlaufbar, funktioniert also mit for...of und dem Spread-Operator. set(), delete() und clear() fehlen.

Parameter

Name	Typ	Beschreibung
$get(name) Pflicht	string	Gibt den `AudioParam` zum Namen zurück, sonst `undefined`.
$has(name) Pflicht	string	Prüft, ob ein Parameter mit diesem Namen existiert. Rückgabe: `boolean`.
$forEach(callback[, thisArg])	(value: AudioParam, key: string, map: AudioParamMap) => void	Ruft `callback` für jeden Eintrag auf, in der Reihenfolge, in der die Parameter eingefügt wurden.
$keys() / values() / entries()	() => Iterator	Liefern einen Iterator über die Namen, die `AudioParam`-Objekte oder über `[name, param]`-Paare.
$size	number	Schreibgeschützte Eigenschaft: Anzahl der enthaltenen Parameter.

Rückgabewert

Typ

AudioParamMap

Beschreibung

Erhält man über AudioWorkletNode.parameters. Enthält alle im Prozessor über parameterDescriptors festgelegten Parameter als AudioParam-Objekte.

Beispiele

Prozessor mit eigenem Parameter festlegen (gain-processor.js)

// gain-processor.js – wird im AudioWorkletGlobalScope ausgeführt
class GainProcessor extends AudioWorkletProcessor {
  static get parameterDescriptors() {
    return [
      { name: 'gain', defaultValue: 0.5, minValue: 0, maxValue: 1, automationRate: 'a-rate' }
    ];
  }

  process(inputs, outputs, parameters) {
    const input = inputs[0];
    const output = outputs[0];
    const gain = parameters.gain; // Float32Array: Länge 1 oder 128
    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);

Parameter über AudioParamMap lesen und automatisieren

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

const node = new AudioWorkletNode(ctx, 'gain-processor');
const osc = new OscillatorNode(ctx, { frequency: 440 });
osc.connect(node).connect(ctx.destination);

const params = node.parameters; // AudioParamMap
console.log(params.size, params.has('gain'));

const gain = params.get('gain');
console.log(gain.defaultValue, gain.minValue, gain.maxValue);

// Innerhalb von 2 Sekunden einblenden
gain.setValueAtTime(0, ctx.currentTime);
gain.linearRampToValueAtTime(1, ctx.currentTime + 2);
osc.start();

1 true 0.5 0 1

Alle Parameter durchlaufen, z. B. für eine automatische Regler-Oberfläche

const buildControls = (workletNode, container) => {
  for (const [name, param] of workletNode.parameters) {
    const input = document.createElement('input');
    input.type = 'range';
    input.min = param.minValue;
    input.max = param.maxValue;
    input.step = 'any';
    input.value = param.value;
    input.addEventListener('input', () => {
      param.setTargetAtTime(Number(input.value), workletNode.context.currentTime, 0.01);
    });
    container.append(name, input);
  }
};

// Namen als Array
console.log([...node.parameters.keys()]);

["gain"]

// Wichtig · Fallstricke

Schreibgeschützt: Es gibt kein set(), delete() oder clear(). Wer Parameter hinzufügen will, muss parameterDescriptors im Prozessor ändern und den Knoten neu erzeugen.
Unbekannte Namen: get() gibt bei unbekannten Namen undefined zurück. Ein Tippfehler führt deshalb erst später zu einem TypeError, etwa bei params.get('gian').value. Im Zweifel vorher mit has() prüfen.
Startwerte: Anfangswerte kann man schon beim Erzeugen übergeben: new AudioWorkletNode(ctx, 'name', { parameterData: { gain: 0.8 } }).
Regler-Grenzen: Werte außerhalb von minValue/maxValue werden stillschweigend auf diese Grenzen begrenzt.
Werte im Prozessor: In process() kommen die Werte als Float32Array an, nicht als AudioParam. Die Länge ist 1, wenn der Wert im aktuellen Block konstant bleibt, sonst 128. Beide Fälle müssen behandelt werden.
Voraussetzungen: AudioWorklet und damit AudioParamMap gibt es nur in sicheren Kontexten (HTTPS oder localhost). Ältere Safari-Versionen vor 14.1 unterstützen AudioWorklet nicht.
Autoplay-Sperre: Ein AudioContext startet wegen der Autoplay-Regeln oft im Zustand suspended. Er muss dann nach einer Nutzeraktion mit ctx.resume() fortgesetzt werden.

Siehe auch

Map AudioParam AudioData AudioTrack AudioWorklet