MediaTrackSettings.sampleRate — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSettings.sampleRate

Beschreibung

Die Eigenschaft sampleRate des Wörterbuchs MediaTrackSettings gibt an, mit wie vielen Audio-Samples pro Sekunde ein MediaStreamTrack gerade arbeitet. Typische Werte sind 44100 (CD-Qualität) und 48000 (üblicher Standard bei Mikrofonen und im Web). Du erhältst den Wert über track.getSettings().

Der Wert zeigt immer den tatsächlich angewendeten Zustand, nicht den gewünschten. Hast du über getUserMedia() oder applyConstraints() eine bestimmte Abtastrate per Constraint angefordert, kannst du mit getSettings().sampleRate prüfen, ob der Browser und die Hardware sie auch wirklich umgesetzt haben.

Praktisch brauchst du das vor allem bei Audioverarbeitung mit der Web Audio API, bei Aufnahme- oder Streaming-Anwendungen (z. B. um die Abtastrate eines AudioContext passend einzustellen) sowie beim Kodieren oder Hochladen roher PCM-Daten, bei denen der Server die Abtastrate kennen muss.

Rückgabewert

Typ

number | undefined

Beschreibung

Ganzzahlige Abtastrate in Hertz (Samples pro Sekunde), z. B. 48000. Bei Video-Tracks oder wenn der Browser die Eigenschaft nicht unterstützt, fehlt sie im Objekt und ist daher undefined.

Beispiele

Abtastrate des Mikrofons auslesen

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [track] = stream.getAudioTracks();
const { sampleRate } = track.getSettings();

console.log(sampleRate !== undefined
  ? `Mikrofon läuft mit ${sampleRate} Hz`
  : 'sampleRate wird nicht unterstützt');

Mikrofon läuft mit 48000 Hz

Gewünschte Abtastrate anfordern und prüfen

const supported = navigator.mediaDevices.getSupportedConstraints();

if (supported.sampleRate) {
  const stream = await navigator.mediaDevices.getUserMedia({
    audio: { sampleRate: { ideal: 44100 } }
  });
  const [track] = stream.getAudioTracks();
  const actual = track.getSettings().sampleRate;

  if (actual !== 44100) {
    console.warn(`Angefordert: 44100 Hz, erhalten: ${actual} Hz`);
  }
}

Angefordert: 44100 Hz, erhalten: 48000 Hz

AudioContext an die Abtastrate des Tracks anpassen

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [track] = stream.getAudioTracks();
const rate = track.getSettings().sampleRate ?? 48000;

// Gleiche Abtastrate vermeidet unnötiges Resampling
const ctx = new AudioContext({ sampleRate: rate });
const source = ctx.createMediaStreamSource(stream);
source.connect(ctx.destination);

console.log(`Track: ${rate} Hz, AudioContext: ${ctx.sampleRate} Hz`);

Track: 48000 Hz, AudioContext: 48000 Hz

// Wichtig · Fallstricke

Browser-Kompatibilität: Firefox liefert sampleRate in getSettings() derzeit nicht. Prüfe deshalb immer auf undefined oder frag vorher navigator.mediaDevices.getSupportedConstraints().sampleRate ab.
Die Eigenschaft gibt es nur bei Audio-Tracks. Bei Video-Tracks fehlt sie.
Ein Constraint wie { sampleRate: 16000 } ist nur ein Wunsch. Viele Browser und Geräte liefern trotzdem fest 48000 Hz und rechnen intern um. Mit { exact: … } kann getUserMedia() mit einem OverconstrainedError scheitern.
Die Abtastrate des Tracks kann von AudioContext.sampleRate abweichen. Bei Verbindungen mit unterschiedlichen Raten rechnet der Browser automatisch um. Das kostet etwas Leistung und kann in manchen Browsern (z. B. in älteren Firefox-Versionen) sogar einen Fehler auslösen.
Die Mediengeräte-API steht nur in sicheren Kontexten (HTTPS) zur Verfügung und braucht die Zustimmung des Nutzers.

Siehe auch

MediaStreamTrackProcessor.totalFrames MediaTrackSettings.sampleSize MediaTrackSettings.frameRate MediaTrackSettings.aspectRatio MediaTrackSettings.facingMode