MediaTrackConstraints.volume — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackConstraints.volume

Beschreibung

Die Eigenschaft volume des Wörterbuchs MediaTrackConstraints beschreibt eine Einschränkung für die einschränkbare Eigenschaft volume einer Audiospur. Der Wert ist ein Gleitkommawert zwischen 0.0 (stumm) und 1.0 (maximale Lautstärke) und wirkt als linearer Verstärkungsfaktor auf das Signal der Quelle.

Als ConstrainDouble kann volume entweder eine einfache Zahl sein (gilt als ideal, also Wunschwert) oder ein Objekt mit den Schlüsseln min, max, exact und ideal. Mit exact bzw. min/max wird der Wert zur harten Anforderung – kann der Browser sie nicht erfüllen, wird das Promise mit einem OverconstrainedError abgewiesen.

Wichtig: volume wurde aus der Spezifikation Media Capture and Streams entfernt und ist veraltet. Chromium hat die Einschränkung zeitweise unterstützt, Firefox und Safari nie. Für neue Projekte sollte die Lautstärke stattdessen über die Web-Audio-API (GainNode) oder über HTMLMediaElement.volume bei der Wiedergabe geregelt werden.

Parameter

Name	Typ	Beschreibung
$volume	number	Einfache Zahl zwischen `0.0` und `1.0`; wird als `ideal`-Wert (Wunsch) behandelt.
$volume.ideal	number	Bevorzugter Wert; der Browser nähert sich ihm so gut wie möglich an, ohne Fehler zu werfen.
$volume.exact	number	Exakt geforderter Wert. Nicht erfüllbar → `OverconstrainedError`.
$volume.min	number	Untergrenze der zulässigen Lautstärke (harte Anforderung).
$volume.max	number	Obergrenze der zulässigen Lautstärke (harte Anforderung).

Rückgabewert

Typ

number | ConstrainDoubleRange

Beschreibung

Eine Zahl oder ein Objekt mit min, max, exact und/oder ideal, jeweils im Bereich 0.0–1.0.

Beispiele

Unterstützung prüfen

const supported = navigator.mediaDevices.getSupportedConstraints();

if (supported.volume) {
  console.log('volume-Einschränkung wird unterstützt');
} else {
  console.log('volume wird nicht unterstützt – GainNode verwenden');
}

volume wird nicht unterstützt – GainNode verwenden

Mikrofon mit gewünschter Lautstärke anfordern

const startMic = async () => {
  try {
    const stream = await navigator.mediaDevices.getUserMedia({
      audio: {
        volume: { ideal: 0.8 } // Wunschwert, kein Fehler bei Nichterfüllung
      }
    });
    const [track] = stream.getAudioTracks();
    console.log('Aktuelle Einstellungen:', track.getSettings());
    return stream;
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
  }
};

startMic();

Aktuelle Einstellungen: { deviceId: "…", echoCancellation: true, … }

Harte Anforderung per applyConstraints mit Fehlerbehandlung

const setVolume = async (track, value) => {
  try {
    await track.applyConstraints({ volume: { exact: value } });
    console.log('Lautstärke gesetzt:', track.getSettings().volume);
  } catch (err) {
    if (err.name === 'OverconstrainedError') {
      console.warn(`Einschränkung "${err.constraint}" nicht erfüllbar`);
    } else {
      throw err;
    }
  }
};

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
await setVolume(stream.getAudioTracks()[0], 0.5);

Einschränkung "volume" nicht erfüllbar

Zukunftssichere Alternative: GainNode

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const ctx = new AudioContext();
const source = ctx.createMediaStreamSource(stream);
const gain = ctx.createGain();
const destination = ctx.createMediaStreamDestination();

gain.gain.value = 0.5; // halbe Lautstärke
source.connect(gain).connect(destination);

// destination.stream enthält die geregelte Audiospur, z. B. für WebRTC
console.log(destination.stream.getAudioTracks().length);

1

// Wichtig · Fallstricke

Veraltet: volume ist nicht mehr Teil der Spezifikation. Firefox und Safari haben es nie unterstützt, in Chromium wurde es entfernt. Nicht in neuem Code verlassen.
Immer vorher mit navigator.mediaDevices.getSupportedConstraints().volume prüfen. Unbekannte Einschränkungen werden als ideal stillschweigend ignoriert, mit exact/min/max kann dagegen ein OverconstrainedError auftreten.
Werte außerhalb von 0.0–1.0 sind ungültig; eine Verstärkung über 1 ist nur per GainNode möglich.
Die Einschränkung ändert nicht die Hardware-Mikrofonempfindlichkeit des Betriebssystems, sondern höchstens die Verarbeitung im Browser.
Wie alle Media-Capture-APIs erfordert getUserMedia() einen sicheren Kontext (HTTPS) und die Zustimmung der Nutzerin bzw. des Nutzers.

Siehe auch

MediaTrackConstraints.groupId MediaTrackConstraints.height MediaTrackConstraints.width MediaTrackConstraints.deviceId MediaTrackConstraints.latency