AudioParamDescriptor — Schnittstelle · JavaScript-Referenz

Signatur

dictionary AudioParamDescriptor { name, defaultValue, minValue, maxValue, automationRate }

Beschreibung

AudioParamDescriptor ist ein Wörterbuch (Dictionary) der Web Audio API, also keine Klasse, die man mit new erzeugt. Es ist ein einfaches Objekt mit festgelegten Eigenschaften. Solche Objekte gibt die statische Getter-Eigenschaft parameterDescriptors einer eigenen AudioWorkletProcessor-Unterklasse als Array zurück. Aus jedem Deskriptor legt der Browser einen passenden AudioParam am zugehörigen AudioWorkletNode an.

So bekommen eigene Audio-Effekte und Synthesizer dieselben automatisierbaren Parameter wie die eingebauten Knoten, etwa GainNode.gain oder OscillatorNode.frequency. Im Haupt-Thread lassen sich diese Parameter über node.parameters.get(name) ansprechen und mit setValueAtTime(), linearRampToValueAtTime() usw. steuern. Andere Audioknoten können auch direkt an sie angeschlossen werden (Modulation).

In der Methode process(inputs, outputs, parameters) kommen die aktuellen Werte als Float32Array an, gespeichert unter dem name des Deskriptors. Bei "a-rate" hat das Array 128 Werte (einen pro Sample-Frame) oder genau 1 Wert, wenn sich der Parameter im aktuellen Block nicht ändert. Bei "k-rate" hat es immer genau 1 Wert pro Block.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Eindeutiger Name des Parameters. Unter diesem Schlüssel steht er in `AudioWorkletNode.parameters` und im `parameters`-Objekt von `process()`.
$defaultValue	number	0	Startwert des `AudioParam`. Er muss zwischen `minValue` und `maxValue` liegen.
$minValue	number	-3.4028235e38	Untere Grenze des Wertebereichs (nominaler Mindestwert). Standard ist der kleinste 32-Bit-Float-Wert.
$maxValue	number	3.4028235e38	Obere Grenze des Wertebereichs (nominaler Höchstwert). Standard ist der größte 32-Bit-Float-Wert.
$automationRate	"a-rate" \| "k-rate"	"a-rate"	`"a-rate"`: ein Wert pro Sample-Frame. `"k-rate"`: ein Wert pro Block mit 128 Frames. Kann später über `AudioParam.automationRate` geändert werden.

Beispiele

Eigenen Gain-Prozessor mit Parameter definieren (gain-processor.js)

// Datei: gain-processor.js – läuft im AudioWorkletGlobalScope
class GainProcessor extends AudioWorkletProcessor {
  static get parameterDescriptors() {
    return [
      {
        name: 'gain',
        defaultValue: 1,
        minValue: 0,
        maxValue: 2,
        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 < output.length; ch++) {
      const inCh = input[ch];
      const outCh = output[ch];
      if (!inCh) continue;
      for (let i = 0; i < outCh.length; i++) {
        // Länge 1 = konstanter Wert im ganzen Block
        outCh[i] = inCh[i] * (gain.length > 1 ? gain[i] : gain[0]);
      }
    }
    return true; // Prozessor aktiv halten
  }
}

registerProcessor('gain-processor', GainProcessor);

Parameter im Haupt-Thread automatisieren

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

const osc = new OscillatorNode(ctx, { frequency: 440 });
const gainNode = new AudioWorkletNode(ctx, 'gain-processor', {
  parameterData: { gain: 0.5 } // überschreibt defaultValue
});

osc.connect(gainNode).connect(ctx.destination);

const gain = gainNode.parameters.get('gain');
console.log(gain.defaultValue, gain.minValue, gain.maxValue, gain.value);

// Sanftes Ausblenden über 2 Sekunden
gain.setValueAtTime(0.5, ctx.currentTime);
gain.linearRampToValueAtTime(0, ctx.currentTime + 2);
osc.start();
osc.stop(ctx.currentTime + 2);

1 0 2 0.5

k-rate-Parameter für einen Bitcrusher

// Datei: bitcrusher.js
class Bitcrusher extends AudioWorkletProcessor {
  static get parameterDescriptors() {
    return [
      { name: 'bits', defaultValue: 8, minValue: 1, maxValue: 16, automationRate: 'k-rate' }
    ];
  }

  process([input], [output], { bits }) {
    // k-rate: immer genau ein Wert pro Block
    const step = 2 ** -(Math.round(bits[0]) - 1);
    input.forEach((inCh, ch) => {
      const outCh = output[ch];
      for (let i = 0; i < inCh.length; i++) {
        outCh[i] = step * Math.floor(inCh[i] / step + 0.5);
      }
    });
    return true;
  }
}

registerProcessor('bitcrusher', Bitcrusher);

// Wichtig · Fallstricke

Kein Konstruktor: AudioParamDescriptor gibt es nicht als globales Objekt. Du schreibst einfach ein normales Objekt-Literal.
Länge des Arrays beachten: Bei "a-rate" kann das Werte-Array in process() auch nur ein Element haben, wenn sich der Wert im Block nicht ändert. Wer blind gain[i] liest, bekommt ab Index 1 undefined und damit NaN im Ausgangssignal.
Fehlerfälle: Doppelte name-Werte oder ein defaultValue außerhalb von minValue/maxValue führen beim Aufruf von registerProcessor() zu einem NotSupportedError bzw. einem InvalidStateError.
Werte werden begrenzt: Außerhalb des Bereichs wird der tatsächliche Wert auf minValue/maxValue begrenzt. Automationskurven können aber trotzdem Zielwerte außerhalb des Bereichs haben.
Deskriptoren werden nur einmal gelesen: parameterDescriptors wird nur bei der Registrierung ausgewertet. Spätere Änderungen am Getter haben keine Wirkung.
Kompatibilität: Funktioniert in allen aktuellen Browsern (Chrome 66+, Firefox 76+, Safari 14.1+). AudioWorklet braucht einen sicheren Kontext (HTTPS oder localhost).

Siehe auch

AudioParamMap CSSPageDescriptors AudioParam CSSFontFaceDescriptors AudioDecoder