MediaTrackSupportedConstraints.volume — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSupportedConstraints.volume

Beschreibung

Die Eigenschaft volume gehört zum Wörterbuch MediaTrackSupportedConstraints. Du bekommst dieses Wörterbuch von navigator.mediaDevices.getSupportedConstraints(). Kennt der Benutzeragent die Einschränkung volume, ist die Eigenschaft vorhanden und hat den Wert true. Kennt er sie nicht, fehlt sie ganz – auf false steht sie also nie. Rufst du sie dann ab, erhältst du undefined.

Mit der Einschränkung volume ließ sich früher bei getUserMedia() oder MediaStreamTrack.applyConstraints() eine gewünschte Lautstärke als Gleitkommazahl zwischen 0.0 (stumm) und 1.0 (volle Lautstärke) anfordern. Aus der Spezifikation wurde sie inzwischen entfernt. Die Eigenschaft ist daher vor allem nützlich, um vor der Nutzung zu prüfen, ob ein Browser diese alte Einschränkung noch versteht.

Für neuen Code solltest du die Lautstärke nicht über Einschränkungen steuern. Nimm stattdessen die Web Audio API, zum Beispiel einen GainNode, oder die Eigenschaft HTMLMediaElement.volume beim Abspielen.

Rückgabewert

Typ

boolean | undefined

Beschreibung

true, wenn der Browser die Einschränkung volume kennt. Wird sie nicht unterstützt, fehlt die Eigenschaft und der Zugriff liefert undefined.

Beispiele

Unterstützung der volume-Einschränkung prüfen

const supported = navigator.mediaDevices.getSupportedConstraints();

if (supported.volume) {
  console.log('Die Einschränkung "volume" wird unterstützt.');
} else {
  console.log('Die Einschränkung "volume" wird nicht unterstützt.');
}

Die Einschränkung "volume" wird nicht unterstützt.

volume nur anfordern, wenn verfügbar – sonst GainNode verwenden

const startMicrophone = async (level = 0.5) => {
  const supported = navigator.mediaDevices.getSupportedConstraints();
  const audio = supported.volume ? { volume: level } : true;

  const stream = await navigator.mediaDevices.getUserMedia({ audio });

  if (supported.volume) {
    return stream;
  }

  // Ersatzweg: Lautstärke über die Web Audio API regeln
  const ctx = new AudioContext();
  const source = ctx.createMediaStreamSource(stream);
  const gain = ctx.createGain();
  gain.gain.value = level;
  const dest = ctx.createMediaStreamDestination();
  source.connect(gain).connect(dest);
  return dest.stream;
};

startMicrophone(0.3)
  .then((stream) => console.log('Audiospuren:', stream.getAudioTracks().length))
  .catch((err) => console.error('Kein Mikrofonzugriff:', err.name));

Audiospuren: 1

Alle unterstützten Audio-Einschränkungen auflisten

const audioKeys = ['autoGainControl', 'channelCount', 'echoCancellation', 'noiseSuppression', 'sampleRate', 'sampleSize', 'latency', 'volume'];
const supported = navigator.mediaDevices.getSupportedConstraints();

const report = Object.fromEntries(
  audioKeys.map((key) => [key, supported[key] === true])
);
console.table(report);

{ autoGainControl: true, channelCount: true, echoCancellation: true, noiseSuppression: true, sampleRate: true, sampleSize: true, latency: true, volume: false }

// Wichtig · Fallstricke

Veraltet: Die Einschränkung volume wurde aus der Spezifikation „Media Capture and Streams“ entfernt. Aktuelle Browser melden sie in der Regel nicht mehr (die Eigenschaft fehlt). Verlass dich in neuem Code nicht darauf.
Fehlt die Unterstützung, steht die Eigenschaft nicht auf false, sondern fehlt ganz. Prüfe deshalb mit if (supported.volume) oder 'volume' in supported und nicht mit === false.
true bedeutet nur, dass der Browser die Einschränkung kennt. Ob das Gerät den angeforderten Wert wirklich umsetzt, verrät das nicht. Zur Kontrolle kannst du nach der Anfrage track.getSettings() aufrufen.
navigator.mediaDevices steht nur in sicheren Kontexten (HTTPS oder localhost) zur Verfügung.
Als Alternative zur Lautstärkeregelung eignen sich GainNode aus der Web Audio API oder HTMLMediaElement.volume.

Siehe auch

MediaTrackConstraints.height MediaTrackSupportedConstraints.groupId MediaTrackSupportedConstraints.height MediaTrackSupportedConstraints.width MediaTrackSupportedConstraints.deviceId