AudioParam.value — Eigenschaft · JavaScript-Referenz

Signatur

AudioParam.value

Beschreibung

Die Eigenschaft value ist der einfachste Weg, einen Parameter eines Audio-Knotens in der Web Audio API zu ändern, zum Beispiel GainNode.gain, OscillatorNode.frequency, BiquadFilterNode.Q oder StereoPannerNode.pan. Der Wert ist eine 32-Bit-Gleitkommazahl (float).

Laut Spezifikation entspricht das Setzen von value einem Aufruf von setValueAtTime(neuerWert, audioContext.currentTime). Die Änderung wird also als Automatisierungsereignis zum aktuellen Zeitpunkt eingeplant und wirkt sofort, allerdings sprunghaft. Beim Lesen erhält man den zuletzt vom Audio-Thread berechneten Wert. Läuft gerade eine Automatisierung, etwa eine Rampe mit linearRampToValueAtTime(), kann der gelesene Wert daher während der Rampe irgendwo zwischen Start- und Zielwert liegen.

Verwende value für einfache, sofortige Einstellungen wie Anfangswerte oder statische Konfigurationen. Für hörbare Änderungen während der Wiedergabe, etwa einen Lautstärkeregler oder Fades, solltest du besser die Automatisierungsmethoden (setTargetAtTime(), linearRampToValueAtTime(), exponentialRampToValueAtTime()) nutzen, um Knackgeräusche zu vermeiden.

Der gültige Wertebereich wird durch minValue und maxValue beschrieben. Werte außerhalb dieses Bereichs lösen keinen Fehler aus. Sie werden bei der Audioberechnung auf den gültigen Bereich begrenzt.

Parameter

Name	Typ	Default	Beschreibung
$value (Setter)	number	defaultValue des jeweiligen AudioParam	Neuer Wert des Parameters. Wird intern in eine 32-Bit-Gleitkommazahl umgewandelt und zur Zeit `currentTime` wie mit `setValueAtTime()` eingeplant.

Rückgabewert

Typ

number

Beschreibung

Der aktuelle Wert des Parameters als 32-Bit-Gleitkommazahl. Weil der Wert als float gespeichert wird, kann der gelesene Wert minimal vom gesetzten abweichen.

Beispiele

Lautstärke und Frequenz direkt setzen

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

osc.frequency.value = 440; // Kammerton A
gain.gain.value = 0.25;    // 25 % Lautstärke

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

// Nach einer Nutzerinteraktion starten (Autoplay-Richtlinie)
document.querySelector('#play').addEventListener('click', async () => {
  await ctx.resume();
  osc.start();
  osc.stop(ctx.currentTime + 1);
});

console.log(osc.frequency.value, gain.gain.value);

440 0.25

Lautstärkeregler ohne Knacken

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

const slider = document.querySelector('#volume'); // <input type="range" min="0" max="1" step="0.01">

slider.addEventListener('input', () => {
  const ziel = Number(slider.value);
  // Statt gain.gain.value = ziel (harter Sprung) sanft angleichen:
  gain.gain.setTargetAtTime(ziel, ctx.currentTime, 0.02);
});

// Den Anfangswert direkt über value setzen
gain.gain.value = Number(slider.value);

Float-Genauigkeit und Wertebereich prüfen

const ctx = new AudioContext();
const gain = ctx.createGain();

gain.gain.value = 0.1;
console.log(gain.gain.value);
console.log(Math.fround(0.1) === gain.gain.value);

const panner = ctx.createStereoPanner();
console.log(panner.pan.minValue, panner.pan.maxValue, panner.pan.defaultValue);

0.10000000149011612 true -1 1 0

Wert während einer Rampe auslesen

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

osc.frequency.setValueAtTime(220, ctx.currentTime);
osc.frequency.linearRampToValueAtTime(880, ctx.currentTime + 2);
osc.start();

setTimeout(() => {
  // Liefert ungefähr den Zwischenwert der Rampe (Browser-abhängig)
  console.log(Math.round(osc.frequency.value));
  osc.stop();
}, 1000);

ca. 550

// Wichtig · Fallstricke

Knackgeräusche: Wenn du value während der Wiedergabe setzt, springt der Wert sofort. Bei Lautstärke oder Frequenz ist das oft als Klicken hörbar. Nutze für Übergänge besser setTargetAtTime() oder Rampen.
Float-Genauigkeit: Der Wert wird als 32-Bit-float gespeichert. Ein Vergleich wie gain.value === 0.1 ergibt deshalb false. Vergleiche stattdessen mit Math.fround() oder mit einer Toleranz.
Konflikt mit Automatisierung: Das Setzen entspricht setValueAtTime(). Überschneidet es sich zeitlich mit einer laufenden setValueCurveAtTime()-Kurve, wird ein NotSupportedError ausgelöst. Bereits geplante Ereignisse bleiben erhalten. Um sie zu verwerfen, rufe vorher cancelScheduledValues(ctx.currentTime) auf.
Wertebereich: Werte außerhalb von minValue bis maxValue lösen keinen Fehler aus. Sie werden bei der Berechnung auf den gültigen Bereich begrenzt. Was der Getter dann zurückgibt, war zwischen den Browsern historisch nicht einheitlich.
Lesen während Automatisierung: Der gelesene Wert stammt aus dem Audio-Thread und kann dem echten Signal leicht hinterherhinken. Er ist nicht für sampelgenaue Auswertungen gedacht.
a-rate/k-rate: Ist ein anderes Signal mit dem Parameter verbunden (node.connect(param)), wird dessen Ausgabe zum Wert addiert. value zeigt diesen Anteil nicht an.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Ältere WebKit-Versionen verwendeten das Präfix webkitAudioContext. Bei Knoten, die nach einer bestimmten Zeit angehalten wurden, ignorierten ältere Chrome-Versionen direkte value-Zuweisungen, wenn schon Automatisierungsereignisse geplant waren.

Siehe auch

AudioParam AudioParam.setValueAtTime() AudioParam.setTargetAtTime() AudioParam.linearRampToValueAtTime() AudioParam.cancelScheduledValues() AudioParam.defaultValue GainNode BaseAudioContext.currentTime