MediaTrackSupportedConstraints.sampleRate — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSupportedConstraints.sampleRate

Beschreibung

Die Eigenschaft sampleRate des Wörterbuchs MediaTrackSupportedConstraints steht in dem Objekt, das navigator.mediaDevices.getSupportedConstraints() zurückgibt. Hat sie den Wert true, kennt der Browser die Constraint sampleRate. Mit ihr lässt sich die gewünschte Abtastrate einer Audiospur in Samples pro Sekunde angeben, etwa 48000 oder 44100.

Wird die Constraint nicht unterstützt, fehlt die Eigenschaft ganz. Den Wert false gibt es in der Praxis nicht. Deshalb reicht eine einfache Wahrheitsprüfung wie if (supported.sampleRate).

Diese Prüfung ist nützlich, bevor man in getUserMedia() oder MediaStreamTrack.applyConstraints() eine bestimmte Abtastrate anfordert. Das gilt zum Beispiel für Sprachaufnahmen mit 16 kHz für Spracherkennung oder für Audio in Studioqualität mit 48 kHz. Kennt der Browser eine Constraint nicht, ignoriert er sie ohne Fehlermeldung. Mit der Prüfung erkennt man also, ob die Angabe überhaupt eine Wirkung haben kann.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Browser die Constraint sampleRate unterstützt. Andernfalls fehlt die Eigenschaft, und ein Zugriff liefert undefined.

Beispiele

Unterstützung prüfen

const supported = navigator.mediaDevices.getSupportedConstraints();

if (supported.sampleRate) {
  console.log('sampleRate wird unterstützt');
} else {
  console.log('sampleRate wird nicht unterstützt');
}

sampleRate wird unterstützt

Mikrofon mit gewünschter Abtastrate öffnen

const startRecording = async () => {
  const supported = navigator.mediaDevices.getSupportedConstraints();
  const audio = { echoCancellation: true };

  // Abtastrate nur anfordern, wenn der Browser die Constraint kennt
  if (supported.sampleRate) {
    audio.sampleRate = { ideal: 48000 };
  }

  const stream = await navigator.mediaDevices.getUserMedia({ audio });
  const [track] = stream.getAudioTracks();
  console.log('Tatsächliche Rate:', track.getSettings().sampleRate);
  return stream;
};

startRecording().catch(err => console.error(err.name, err.message));

Tatsächliche Rate: 48000

Abtastrate einer laufenden Spur ändern

const setRate = async (track, rate) => {
  const { sampleRate } = navigator.mediaDevices.getSupportedConstraints();
  if (!sampleRate) {
    console.warn('Abtastrate kann nicht gesteuert werden');
    return;
  }
  const caps = track.getCapabilities?.() ?? {};
  console.log('Möglicher Bereich:', caps.sampleRate);
  await track.applyConstraints({ sampleRate: rate });
  console.log('Neue Rate:', track.getSettings().sampleRate);
};

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

Möglicher Bereich: { min: 8000, max: 96000 } Neue Rate: 16000

// Wichtig · Fallstricke

Nur ein Hinweis auf Unterstützung: true heißt nur, dass der Browser die Constraint kennt. Ob das Gerät die gewünschte Rate liefern kann, zeigt erst track.getCapabilities(). Die tatsächlich verwendete Rate liefert track.getSettings().
Kein false: Wird die Constraint nicht unterstützt, fehlt die Eigenschaft. Ein Vergleich wie === false schlägt deshalb fehl.
Mit Vorsicht festlegen: { exact: 44100 } kann bei getUserMedia() einen OverconstrainedError auslösen. Mit ideal ist man sicherer.
Kompatibilität: Chromium-Browser und Safari unterstützen die Constraint. Firefox meldet sie nicht als unterstützt. Dort wird meist die Rate des Systems verwendet, häufig 48 kHz. Um Audio umzurechnen, kann man einen AudioContext mit der Option sampleRate verwenden.
Sicherer Kontext: navigator.mediaDevices gibt es nur über HTTPS oder auf localhost.

Siehe auch

MediaTrackConstraints.frameRate MediaTrackSupportedConstraints.sampleSize MediaTrackSupportedConstraints.frameRate MediaTrackSupportedConstraints.aspectRatio MediaTrackSupportedConstraints.facingMode