AudioParam — Schnittstelle · JavaScript-Referenz

Signatur

interface AudioParam

Beschreibung

Das Interface AudioParam der Web Audio API steht für einen einzelnen, zeitlich steuerbaren Parameter eines AudioNode, etwa die Lautstärke (GainNode.gain), die Frequenz eines Oszillators (OscillatorNode.frequency) oder die Grenzfrequenz eines Filters (BiquadFilterNode.frequency). Instanzen werden nicht selbst erzeugt. Sie sind immer schon als Eigenschaften der jeweiligen Knoten vorhanden.

Man kann einen Wert direkt über value setzen. Die eigentliche Stärke liegt aber in der Automatisierung: Mit Methoden wie setValueAtTime(), linearRampToValueAtTime(), exponentialRampToValueAtTime(), setTargetAtTime() und setValueCurveAtTime() plant man Wertänderungen sample-genau auf der Zeitachse von AudioContext.currentTime. Damit lassen sich Fades, Hüllkurven (ADSR), Glissandi oder LFO-Effekte ohne Knackser umsetzen.

Es gibt zwei Arten von Parametern: a-rate-Parameter werden für jedes Sample einzeln berechnet, k-rate-Parameter nur einmal pro Render-Block mit 128 Samples. Außerdem kann man einen AudioParam als Ziel einer Verbindung nutzen (node.connect(param)). Das Ausgangssignal eines anderen Knotens wird dann zum Grundwert addiert. So entstehen Modulationen wie Vibrato oder Tremolo.

Eigenschaften: value, defaultValue (nur lesbar), minValue (nur lesbar), maxValue (nur lesbar), automationRate ("a-rate" | "k-rate", nicht bei allen Parametern änderbar)
Methoden: setValueAtTime(value, startTime), linearRampToValueAtTime(value, endTime), exponentialRampToValueAtTime(value, endTime), setTargetAtTime(target, startTime, timeConstant), setValueCurveAtTime(values, startTime, duration), cancelScheduledValues(startTime), cancelAndHoldAtTime(cancelTime). Alle Methoden geben den AudioParam zurück und lassen sich daher verketten.

Parameter

Name	Typ	Default	Beschreibung
$value	number	defaultValue	Aktueller Wert des Parameters. Wird er gesetzt, entspricht das einem sofortigen `setValueAtTime(value, currentTime)`.
$automationRate	"a-rate" \| "k-rate"	abhängig vom Knoten	Legt fest, ob der Parameter pro Sample (`a-rate`) oder pro Render-Block mit 128 Samples (`k-rate`) berechnet wird.
$startTime / endTime Pflicht	number		Zeitpunkte der Automatisierungsmethoden in Sekunden, gemessen auf der Zeitachse von `AudioContext.currentTime`.
$timeConstant	number		Nur bei `setTargetAtTime()`: Zeitkonstante der exponentiellen Annäherung. Nach etwa 5 × `timeConstant` ist der Zielwert praktisch erreicht.
$values	Float32Array \| number[]		Nur bei `setValueCurveAtTime()`: Werte der Kurve. Sie werden gleichmäßig über `duration` verteilt und linear interpoliert.

Rückgabewert

Typ

AudioParam

Beschreibung

Alle Automatisierungsmethoden geben den AudioParam selbst zurück, sodass man Aufrufe verketten kann. value liefert eine number.

Beispiele

Lautstärke direkt setzen und Grenzwerte auslesen

const ctx = new AudioContext();
const gain = ctx.createGain();
const param = gain.gain; // AudioParam

param.value = 0.5;
console.log(param.value, param.defaultValue, param.automationRate);

0.5 1 a-rate

Fade-in und Fade-out ohne Knacksen

const ctx = new AudioContext();
const osc = ctx.createOscillator();
const gain = ctx.createGain();
osc.connect(gain).connect(ctx.destination);

const now = ctx.currentTime;
gain.gain
  .setValueAtTime(0, now)                    // Startpunkt festlegen
  .linearRampToValueAtTime(0.8, now + 0.5)   // 0,5 s Fade-in
  .setValueAtTime(0.8, now + 2)
  .exponentialRampToValueAtTime(0.0001, now + 3); // weiches Ausklingen

osc.start(now);
osc.stop(now + 3);

Vibrato: einen LFO mit einem AudioParam verbinden

const ctx = new AudioContext();
const osc = ctx.createOscillator();
osc.frequency.value = 440;

const lfo = ctx.createOscillator();
lfo.frequency.value = 5;        // 5 Hz Modulation
const depth = ctx.createGain();
depth.gain.value = 10;          // ±10 Hz

lfo.connect(depth).connect(osc.frequency); // Signal wird zu 440 Hz addiert
osc.connect(ctx.destination);
lfo.start();
osc.start();

Laufende Automatisierung abbrechen und Wert halten

const ctx = new AudioContext();
const filter = ctx.createBiquadFilter();
const now = ctx.currentTime;

filter.frequency.setValueAtTime(200, now);
filter.frequency.linearRampToValueAtTime(5000, now + 4);

// Nach 1 s abbrechen und den aktuellen Wert beibehalten
setTimeout(() => {
  filter.frequency.cancelAndHoldAtTime(ctx.currentTime);
  filter.frequency.setTargetAtTime(800, ctx.currentTime, 0.1);
}, 1000);

// Wichtig · Fallstricke

Rampen brauchen einen Startpunkt: linearRampToValueAtTime() und exponentialRampToValueAtTime() beginnen beim vorherigen geplanten Ereignis. Setze deshalb vorher setValueAtTime(param.value, ctx.currentTime), sonst springt der Wert oder die Rampe beginnt zu einem unerwarteten Zeitpunkt.
Exponentielle Rampen dürfen weder bei 0 beginnen noch bei 0 enden, und Start- und Zielwert müssen dasselbe Vorzeichen haben. Sonst wird ein RangeError geworfen. Nimm stattdessen einen sehr kleinen Wert wie 0.0001 oder setTargetAtTime().
Wenn man value setzt, während eine Automatisierung läuft, wird die Zuweisung je nach Browser ignoriert oder von der Automatisierung überschrieben. Nutze dann besser cancelScheduledValues() oder cancelAndHoldAtTime().
setValueCurveAtTime() wirft einen Fehler, wenn sich die Kurve zeitlich mit anderen geplanten Ereignissen überschneidet.
Werte außerhalb von minValue/maxValue werden stillschweigend begrenzt (Clamping).
Kompatibilität: cancelAndHoldAtTime() wird von Firefox erst seit neueren Versionen unterstützt. Prüfe vor der Verwendung, ob die Methode vorhanden ist. automationRate ist bei manchen Parametern (z. B. AudioBufferSourceNode.playbackRate) fest vorgegeben, ein Änderungsversuch wirft einen InvalidStateError.
Viele Browser starten einen AudioContext wegen der Autoplay-Regeln im Zustand "suspended". Rufe ctx.resume() nach einer Nutzeraktion auf.

Siehe auch

AudioData AudioParamMap AudioTrack AudioNode EcdsaParams