MediaTrackConstraints.sampleRate — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackConstraints.sampleRate

Beschreibung

Die Eigenschaft sampleRate des Wörterbuchs MediaTrackConstraints beschreibt, welche Abtastrate in Hertz (z. B. 44100 oder 48000) für eine Audiospur angefordert wird. Sie wird an navigator.mediaDevices.getUserMedia() oder an MediaStreamTrack.applyConstraints() übergeben.

Der Wert ist ein ConstrainULong. Das heißt, er kann angegeben werden als:

eine ganze Zahl – ein idealer Wert, den der Browser möglichst gut erfüllen soll,
ein Objekt mit min, max, exact und/oder ideal, um Bereiche oder Pflichtwerte festzulegen.

Sinnvoll ist das bei Anwendungen, die auf eine bestimmte Rate angewiesen sind, z. B. Spracherkennung (oft 16 kHz), Aufnahmen in Studioqualität (48 kHz) oder wenn die Rate zu einem vorhandenen AudioContext passen muss. Ob ein Browser die Eigenschaft unterstützt, verrät navigator.mediaDevices.getSupportedConstraints().sampleRate. Welche Rate tatsächlich verwendet wird, zeigt track.getSettings().sampleRate.

Parameter

Name	Typ	Beschreibung
$sampleRate	number	Einfache Zahl = idealer Wert in Hertz, z. B. `48000`.
$sampleRate.ideal	number	Bevorzugte Abtastrate. Der Browser wählt einen möglichst nahen Wert, ohne dass der Aufruf fehlschlägt.
$sampleRate.exact	number	Pflichtwert. Lässt er sich nicht erfüllen, wird das Promise mit einem `OverconstrainedError` abgelehnt.
$sampleRate.min	number	Kleinste zulässige Abtastrate (Pflicht-Untergrenze).
$sampleRate.max	number	Größte zulässige Abtastrate (Pflicht-Obergrenze).

Rückgabewert

Typ

number | ConstrainULongRange

Beschreibung

Die im Constraints-Objekt hinterlegte Einschränkung, entweder als Zahl oder als Objekt mit min/max/exact/ideal. Die tatsächlich verwendete Rate steht in MediaTrackSettings.sampleRate.

Beispiele

Ideale Abtastrate beim Mikrofonzugriff anfordern

const startMic = async () => {
  const supported = navigator.mediaDevices.getSupportedConstraints();
  if (!supported.sampleRate) {
    console.warn('sampleRate wird nicht unterstützt');
  }

  const stream = await navigator.mediaDevices.getUserMedia({
    audio: { sampleRate: 48000 } // Wunschwert, kein Zwang
  });

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

startMic();

Tatsächliche Rate: 48000

Bereich festlegen und OverconstrainedError abfangen

const getSpeechStream = async () => {
  try {
    return await navigator.mediaDevices.getUserMedia({
      audio: {
        sampleRate: { min: 16000, max: 48000, ideal: 16000 },
        channelCount: 1
      }
    });
  } catch (err) {
    if (err.name === 'OverconstrainedError') {
      console.error('Keine passende Rate verfügbar:', err.constraint);
      // Rückfall ohne Einschränkung
      return navigator.mediaDevices.getUserMedia({ audio: true });
    }
    throw err;
  }
};

getSpeechStream().then((s) => console.log('Spuren:', s.getAudioTracks().length));

Spuren: 1

Constraint auf eine laufende Spur anwenden

const adjustRate = async (track) => {
  console.log('Vorher:', track.getSettings().sampleRate);
  try {
    await track.applyConstraints({ sampleRate: { exact: 44100 } });
  } catch (err) {
    console.warn('Nicht änderbar:', err.name);
  }
  console.log('Nachher:', track.getSettings().sampleRate);
  console.log('Aktive Constraints:', track.getConstraints());
};

navigator.mediaDevices.getUserMedia({ audio: true })
  .then((s) => adjustRate(s.getAudioTracks()[0]));

Vorher: 48000 Nicht änderbar: OverconstrainedError Nachher: 48000 Aktive Constraints: {}

// Wichtig · Fallstricke

Die Browser setzen die Einschränkung sehr unterschiedlich um: Viele liefern das Mikrofon mit der Rate des Systems bzw. der Hardware (oft 48000 Hz) und ignorieren ideal stillschweigend. Prüfe deshalb immer track.getSettings().sampleRate.
exact, min und max sind Pflichtwerte. Lassen sie sich nicht erfüllen, schlägt der Aufruf mit OverconstrainedError fehl. Wenn die Rate nicht zwingend ist, verwende lieber ideal.
Wenn du Audio für die Web Audio API umrechnen willst, ist oft new AudioContext({ sampleRate: 16000 }) der verlässlichere Weg. Ein MediaStreamAudioSourceNode passt die Rate automatisch an den Kontext an. Manche Browser (ältere Firefox-Versionen) werfen allerdings einen Fehler, wenn die Rate des Kontexts und die des Streams nicht übereinstimmen.
Die Einschränkung gilt nur für Audiospuren. Bei Videospuren hat sie keine Wirkung.
getUserMedia() funktioniert nur in sicheren Kontexten (HTTPS) und braucht die Zustimmung des Nutzers.

Siehe auch

MediaTrackConstraints.sampleSize MediaTrackConstraints.frameRate MediaTrackConstraints.aspectRatio MediaTrackConstraints.facingMode MediaTrackConstraints.latency