MediaTrackSettings — Schnittstelle · JavaScript-Referenz

Signatur

interface MediaTrackSettings

Beschreibung

MediaTrackSettings ist kein Konstruktor, sondern ein einfaches Dictionary-Objekt. Man bekommt es durch den Aufruf von MediaStreamTrack.getSettings(). Es enthält die Werte, die der Browser tatsächlich auf eine Audio- oder Videospur angewendet hat. Das kann von den gewünschten Werten abweichen, die man über getUserMedia() oder applyConstraints() als Einschränkungen (Constraints) angegeben hat.

Welche Eigenschaften vorhanden sind, hängt von der Art der Spur und vom Browser ab. Die wichtigsten:

Gemeinsam: deviceId, groupId
Video: width, height, aspectRatio, frameRate, facingMode ("user", "environment", …), resizeMode
Audio: sampleRate, sampleSize, channelCount, echoCancellation, autoGainControl, noiseSuppression, latency
Bildschirmfreigabe: displaySurface ("monitor", "window", "browser"), cursor, logicalSurface

Typische Anwendungsfälle sind: die tatsächlich erhaltene Kameraauflösung prüfen, das Seitenverhältnis eines <video>- oder <canvas>-Elements anpassen, Front- und Rückkamera unterscheiden und die deviceId speichern, damit beim nächsten Besuch dasselbe Gerät gewählt wird.

Parameter

Name	Typ	Beschreibung
$deviceId	string	ID des Eingabegeräts; nur innerhalb desselben Ursprungs stabil.
$groupId	string	Gruppen-ID. Geräte mit gleicher ID gehören zum selben physischen Gerät (z. B. Headset).
$width / height	number	Tatsächliche Breite/Höhe des Videobilds in Pixeln.
$aspectRatio	number	Seitenverhältnis (Breite geteilt durch Höhe), z. B. `1.7777`.
$frameRate	number	Bildrate in Bildern pro Sekunde.
$facingMode	string	Kamerarichtung: `"user"`, `"environment"`, `"left"`, `"right"`.
$sampleRate / sampleSize / channelCount	number	Abtastrate (Hz), Bits pro Abtastwert und Anzahl der Audiokanäle.
$echoCancellation / autoGainControl / noiseSuppression	boolean	Ob die jeweilige Audioverarbeitung aktiv ist.
$latency	number	Audiolatenz in Sekunden.
$displaySurface	string	Art der freigegebenen Oberfläche bei `getDisplayMedia()`: `"monitor"`, `"window"` oder `"browser"`.

Rückgabewert

Typ

MediaTrackSettings

Beschreibung

Ein einfaches Objekt, das MediaStreamTrack.getSettings() zurückgibt. Es enthält nur die Eigenschaften, die für die Spur relevant sind und vom Browser unterstützt werden.

Beispiele

Tatsächliche Kameraauflösung auslesen

const stream = await navigator.mediaDevices.getUserMedia({
  video: { width: { ideal: 1920 }, height: { ideal: 1080 } }
});
const [videoTrack] = stream.getVideoTracks();
const { width, height, frameRate, deviceId } = videoTrack.getSettings();
console.log(`Erhalten: ${width}x${height} @ ${frameRate} fps`);
console.log('Gerät:', deviceId);

Erhalten: 1280x720 @ 30 fps Gerät: 3f2a…

Audioverarbeitung prüfen und nachsteuern

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

if (settings.echoCancellation === false) {
  await audioTrack.applyConstraints({ echoCancellation: true });
}
console.log('Echounterdrückung:', audioTrack.getSettings().echoCancellation);
console.log('Abtastrate:', settings.sampleRate, 'Hz');

Echounterdrückung: true Abtastrate: 48000 Hz

Bevorzugte Kamera merken und wiederverwenden

const savedId = localStorage.getItem('cameraId');
const stream = await navigator.mediaDevices.getUserMedia({
  video: savedId ? { deviceId: { exact: savedId } } : { facingMode: 'user' }
});
const track = stream.getVideoTracks()[0];
const { deviceId, facingMode } = track.getSettings();
localStorage.setItem('cameraId', deviceId);
console.log('Kamerarichtung:', facingMode ?? 'unbekannt');

Kamerarichtung: user

Art der Bildschirmfreigabe erkennen

const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
const { displaySurface } = stream.getVideoTracks()[0].getSettings();
if (displaySurface === 'monitor') {
  console.warn('Ganzer Bildschirm wird geteilt – Benachrichtigungen ausblenden!');
}

Ganzer Bildschirm wird geteilt – Benachrichtigungen ausblenden!

// Wichtig · Fallstricke

Einstellungen sind nicht gleich Einschränkungen: getConstraints() gibt zurück, was man angefordert hat, getSettings() das, was tatsächlich gilt. Gerade bei ideal-Werten weichen beide oft voneinander ab.
Schnappschuss: Das Objekt aktualisiert sich nicht von selbst. Nach applyConstraints(), einer Drehung des Geräts oder einer Größenänderung des Fensters bei der Bildschirmfreigabe muss man getSettings() erneut aufrufen.
Eigenschaften können fehlen: Nicht jeder Browser liefert jede Eigenschaft. Firefox kennt z. B. facingMode auf dem Desktop oft nicht, und latency oder sampleSize fehlen häufig. Deshalb immer mit ?. oder ?? absichern und mit navigator.mediaDevices.getSupportedConstraints() prüfen.
Datenschutz: deviceId und groupId gelten nur für den jeweiligen Ursprung und werden beim Löschen der Cookies neu erzeugt. Vor der Zustimmung des Nutzers sind sie leer oder zufällig.
Alle Medien-APIs funktionieren nur in einem sicheren Kontext (HTTPS oder localhost).

Siehe auch

MediaTrackConstraints AudioTrackList CDATASection MediaCapabilities MediaDeviceInfo