MediaStreamTrack.getSettings() — Methode · JavaScript-Referenz

Signatur

MediaStreamTrack.prototype.getSettings()

Beschreibung

getSettings() liefert die tatsächlich angewendeten Einstellungen eines MediaStreamTrack. Das ist etwas anderes als die gewünschten Werte, die man über getUserMedia() oder applyConstraints() übergibt: Der Browser versucht, die Beschränkungen (Constraints) so gut wie möglich zu erfüllen. Welche Werte er am Ende wirklich gewählt hat, verrät nur getSettings().

Je nach Track-Art (kind ist "video" oder "audio") enthält das Objekt unterschiedliche Eigenschaften, etwa width, height, frameRate, aspectRatio, facingMode und resizeMode bei Video oder sampleRate, channelCount, echoCancellation, noiseSuppression und autoGainControl bei Audio. Allgemein vorhanden sind oft deviceId und groupId. Bei Bildschirmfreigaben kommen z. B. displaySurface, cursor oder logicalSurface hinzu.

Typische Einsatzfälle: die echte Kameraauflösung auslesen, um ein <canvas> passend zu dimensionieren; prüfen, ob die Front- oder Rückkamera aktiv ist; die gewählte deviceId speichern, damit beim nächsten Besuch dasselbe Gerät verwendet wird; oder nach applyConstraints() kontrollieren, ob die Änderung gegriffen hat.

Rückgabewert

Typ

MediaTrackSettings

Beschreibung

Ein einfaches Objekt (Dictionary) mit den aktuellen Werten der beschränkbaren Eigenschaften. Es enthält nur die Eigenschaften, die der Browser für diesen Track unterstützt; es handelt sich um eine Momentaufnahme, die sich später nicht automatisch aktualisiert.

Beispiele

Tatsächliche Kameraauflösung ermitteln

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(`Aktiv: ${width}x${height} @ ${frameRate} fps`);
console.log('Geräte-ID:', deviceId);

Aktiv: 1280x720 @ 30 fps Geräte-ID: 3f1a9c…

Canvas an die Videogröße anpassen

const video = document.querySelector('video');
const canvas = document.querySelector('canvas');

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
video.srcObject = stream;

const { width, height } = stream.getVideoTracks()[0].getSettings();
canvas.width = width;
canvas.height = height;

// Einzelbild aufnehmen
const snapshot = () => {
  canvas.getContext('2d').drawImage(video, 0, 0, width, height);
};
document.querySelector('#foto').addEventListener('click', snapshot);

Wirkung von applyConstraints() überprüfen

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const track = stream.getVideoTracks()[0];

console.log('Vorher:', track.getSettings().frameRate);

try {
  await track.applyConstraints({ frameRate: { ideal: 15 } });
  console.log('Nachher:', track.getSettings().frameRate);
} catch (err) {
  console.error('Constraint nicht erfüllbar:', err.constraint);
}

Vorher: 30 Nachher: 15

Audio-Einstellungen und Kameraausrichtung prüfen

const stream = await navigator.mediaDevices.getUserMedia({
  audio: { echoCancellation: true },
  video: { facingMode: 'user' }
});

const audio = stream.getAudioTracks()[0].getSettings();
console.log('Echounterdrückung:', audio.echoCancellation);
console.log('Abtastrate:', audio.sampleRate ?? 'unbekannt');

const video = stream.getVideoTracks()[0].getSettings();
const frontkamera = video.facingMode === 'user';
console.log('Frontkamera aktiv:', frontkamera);

Echounterdrückung: true Abtastrate: 48000 Frontkamera aktiv: true

// Wichtig · Fallstricke

Momentaufnahme: Das zurückgegebene Objekt ändert sich nicht mit. Nach applyConstraints(), einem Gerätewechsel oder einer Drehung des Mobilgeräts muss getSettings() erneut aufgerufen werden.
Nicht jede Eigenschaft ist vorhanden: Fehlende Unterstützung bedeutet, dass der Schlüssel fehlt (undefined). Mit navigator.mediaDevices.getSupportedConstraints() prüfen, welche Eigenschaften der Browser kennt, und auf Fallbacks achten (z. B. sampleRate fehlt in manchen Browsern, facingMode auf Desktop-Rechnern oft).
Nicht mit getConstraints() verwechseln: Dieses liefert die angeforderten Werte, getSettings() die tatsächlich wirksamen. getCapabilities() liefert dagegen den möglichen Wertebereich.
Ausrichtung auf Mobilgeräten: width und height können im Hochformat vertauscht sein. Für die Darstellung sind video.videoWidth/videoHeight nach loadedmetadata oft verlässlicher.
Datenschutz: deviceId ist pro Ursprung eindeutig und bleibt nur bestehen, wenn die Berechtigung erteilt wurde; sie wird beim Löschen der Website-Daten zurückgesetzt. getUserMedia() funktioniert nur in sicheren Kontexten (HTTPS oder localhost).
Nach track.stop() (readyState === "ended") können die Werte veraltet oder unvollständig sein.

Siehe auch

MediaStreamTrack.getConstraints() MediaStreamTrack.stop() MediaStreamTrack.clone() MediaStreamTrack.getCapabilities() MediaStreamTrack.applyConstraints()