MediaTrackSupportedConstraints.sampleSize — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSupportedConstraints.sampleSize

Beschreibung

Die Eigenschaft sampleSize gehört zum Wörterbuch MediaTrackSupportedConstraints. Dieses Objekt liefert MediaDevices.getSupportedConstraints() zurück. Kennt der Browser die Einschränkung sampleSize, ist die Eigenschaft vorhanden und hat den Wert true. Kennt er sie nicht, fehlt die Eigenschaft ganz. Den Wert false nimmt sie nie an.

Die Einschränkung sampleSize legt die lineare Bittiefe eines Audio-Samples fest, zum Beispiel 16 oder 24 Bit. Man übergibt sie an getUserMedia() oder MediaStreamTrack.applyConstraints(), wenn eine bestimmte Audioqualität gebraucht wird, etwa bei Aufnahme- oder Musikanwendungen.

Die Eigenschaft sagt nur aus, dass der Browser die Einschränkung versteht. Ob das angeschlossene Gerät eine bestimmte Bittiefe tatsächlich liefern kann, sagt sie nicht. Dafür prüft man den tatsächlichen Wert mit MediaStreamTrack.getSettings() und den möglichen Wertebereich mit MediaStreamTrack.getCapabilities().

Rückgabewert

Typ

boolean | undefined

Beschreibung

true, wenn der Browser die Einschränkung sampleSize unterstützt. Andernfalls fehlt die Eigenschaft, und der Zugriff ergibt undefined.

Beispiele

Unterstützung prüfen

const supported = navigator.mediaDevices.getSupportedConstraints();

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

sampleSize wird unterstützt

24-Bit-Audio anfordern, falls möglich

const startRecording = async () => {
  const supported = navigator.mediaDevices.getSupportedConstraints();
  const audio = supported.sampleSize
    ? { sampleSize: { ideal: 24 } }
    : true;

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

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

Tatsächliche Bittiefe: 16

Bittiefe eines laufenden Tracks ändern

const setSampleSize = async (track, bits) => {
  if (!navigator.mediaDevices.getSupportedConstraints().sampleSize) {
    console.warn('sampleSize nicht verfügbar');
    return;
  }
  const caps = track.getCapabilities?.().sampleSize;
  console.log('Möglicher Bereich:', caps);
  await track.applyConstraints({ sampleSize: { ideal: bits } });
  console.log('Neu:', track.getSettings().sampleSize);
};

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

Möglicher Bereich: { min: 16, max: 16 } Neu: 16

// Wichtig · Fallstricke

Die Eigenschaft ist entweder true oder fehlt ganz. Prüfen Sie deshalb auf Wahrheitswert (if (supported.sampleSize)) und nicht auf === false.
true bedeutet nur, dass der Browser die Einschränkung kennt. Viele Geräte liefern trotzdem nur feste 16 Bit. Verwenden Sie ideal statt exact, sonst kann getUserMedia() mit einem OverconstrainedError scheitern.
Firefox unterstützt sampleSize nicht. Planen Sie deshalb immer eine Ausweichlösung ein.
navigator.mediaDevices gibt es nur in sicheren Kontexten, also über HTTPS oder auf localhost.
Die interne Verarbeitung mit der Web Audio API geschieht ohnehin mit 32-Bit-Gleitkommazahlen. Die Bittiefe spielt daher vor allem bei der Aufnahme bzw. auf der Hardware-Seite eine Rolle.

Siehe auch

MediaTrackConstraints.noiseSuppression MediaTrackSupportedConstraints.sampleRate MediaTrackSupportedConstraints.frameRate MediaTrackSupportedConstraints.deviceId MediaTrackSupportedConstraints.facingMode