Signatur
Beschreibung
Die Eigenschaft sampleSize des Wörterbuchs MediaTrackConstraints beschreibt die gewünschte oder zwingende Sample-Größe in Bit einer Audiospur, also die lineare Bittiefe eines einzelnen Samples (typisch 8, 16, 24 oder 32 Bit). Sie wird beim Aufruf von navigator.mediaDevices.getUserMedia() oder später mit MediaStreamTrack.applyConstraints() übergeben.
Der Wert ist ein ConstrainULong. Du kannst also entweder eine einfache Zahl angeben, die als Idealwert gilt, oder ein Objekt mit den Schlüsseln exact, ideal, min und max. Mit exact, min oder max wird die Einschränkung zwingend: Kann das Gerät sie nicht erfüllen, schlägt die Anfrage mit einem OverconstrainedError fehl.
In der Praxis ist die Eigenschaft vor allem für Audio-Anwendungen wie Aufnahme-Tools, Musik-Software oder Messanwendungen interessant, bei denen die Bittiefe relevant ist. Bei Videospuren hat sie keine Bedeutung. Ob der Browser die Einschränkung überhaupt auswertet, prüfst du vorher mit navigator.mediaDevices.getSupportedConstraints().sampleSize. Den tatsächlich verwendeten Wert erhältst du über MediaStreamTrack.getSettings().sampleSize.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $sampleSize | number | { exact?: number, ideal?: number, min?: number, max?: number } | Gewünschte Bittiefe pro Sample. Eine reine Zahl gilt als ideal. Mit exact, min und max wird die Einschränkung zwingend. |
Rückgabewert
exact/ideal/min/max. Das ist nicht der tatsächlich verwendete Wert, den liefert getSettings().Beispiele
16-Bit-Audio als Idealwert anfordern
const startAudio = async () => {
const supported = navigator.mediaDevices.getSupportedConstraints();
if (!supported.sampleSize) {
console.warn('sampleSize wird von diesem Browser nicht unterstützt');
}
const stream = await navigator.mediaDevices.getUserMedia({
audio: { sampleSize: 16 } // gilt als ideal
});
const [track] = stream.getAudioTracks();
console.log('Tatsächliche Sample-Größe:', track.getSettings().sampleSize);
return stream;
};
startAudio();Mindestens 24 Bit erzwingen und Fehler abfangen
const getHighResAudio = async () => {
try {
const stream = await navigator.mediaDevices.getUserMedia({
audio: { sampleSize: { min: 24, ideal: 24 } }
});
console.log('24-Bit-Aufnahme möglich');
return stream;
} catch (err) {
if (err.name === 'OverconstrainedError') {
console.error(`Nicht erfüllbar: ${err.constraint}`);
// Ohne zwingende Einschränkung erneut versuchen
return navigator.mediaDevices.getUserMedia({ audio: true });
}
throw err;
}
};
getHighResAudio();Einschränkung nachträglich mit applyConstraints ändern
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [track] = stream.getAudioTracks();
const caps = track.getCapabilities?.() ?? {};
console.log('Mögliche Bereiche:', caps.sampleSize);
await track.applyConstraints({ sampleSize: { ideal: 16 } });
console.log('Angefordert:', track.getConstraints().sampleSize);
console.log('Aktiv:', track.getSettings().sampleSize);// Wichtig · Fallstricke
- Nur für Audio: Bei Videospuren wird
sampleSizeignoriert. - Eingeschränkte Wirkung: Viele Browser verarbeiten Mikrofon-Audio intern mit festen Formaten, zum Beispiel 16 Bit oder 32-Bit-Float. Deshalb melden
getCapabilities()undgetSettings()oft nur einen einzigen Wert, und zwingende Werte, die davon abweichen, führen zu einemOverconstrainedError. - Web Audio: Innerhalb eines
AudioContextwerden Samples immer als 32-Bit-Float verarbeitet.sampleSizebetrifft nur die Erfassung auf Geräteseite. - Verwende möglichst
idealstattexact, damit die Anfrage auf unterschiedlicher Hardware nicht fehlschlägt. getUserMedia()funktioniert nur in einem sicheren Kontext (HTTPS oder localhost) und erfordert die Zustimmung des Nutzers.- Firefox unterstützt
getCapabilities()erst in neueren Versionen. Prüfe die Unterstützung deshalb vorher mitgetSupportedConstraints().