MediaStreamTrack.getCapabilities() — Methode · JavaScript-Referenz

Signatur

MediaStreamTrack.prototype.getCapabilities()

Beschreibung

getCapabilities() sagt Ihnen, was das Gerät hinter einem MediaStreamTrack überhaupt kann. Das gilt für Kamera, Mikrofon oder Bildschirmaufnahme. Die Methode gibt ein MediaTrackCapabilities-Objekt zurück. Es enthält für jede einschränkbare Eigenschaft (engl. constrainable property) entweder einen Wertebereich ({ min, max, step? }), eine Liste erlaubter Werte (z. B. facingMode: ["user"]) oder einen einfachen Wert (z. B. deviceId).

Brauchbar ist das vor allem, bevor Sie mit MediaStreamTrack.applyConstraints() Einschränkungen setzen. Sie können zum Beispiel die höchste Auflösung der Webcam ermitteln, den Wertebereich für einen Zoom-Regler festlegen oder prüfen, ob das Mikrofon Echounterdrückung unterstützt. So vermeiden Sie ein OverconstrainedError, weil Sie nur Werte anfordern, die das Gerät auch liefern kann.

Wichtig ist der Unterschied zu verwandten Methoden:

getCapabilities() liefert, was möglich ist.
getConstraints() liefert, was Sie angefordert haben.
getSettings() liefert, was aktuell tatsächlich eingestellt ist.

Welche Schlüssel das zurückgegebene Objekt enthält, hängt vom Track-Typ (audio oder video), vom Gerät und vom Browser ab. Eigenschaften, die der Browser nicht kennt, fehlen einfach im Objekt. Prüfen Sie deshalb immer, ob ein Schlüssel vorhanden ist, bevor Sie ihn benutzen.

Rückgabewert

Typ

MediaTrackCapabilities

Beschreibung

Ein einfaches Objekt mit den unterstützten Werten der einschränkbaren Eigenschaften. Typische Schlüssel sind width, height, frameRate, aspectRatio, facingMode, resizeMode, deviceId, groupId, echoCancellation, noiseSuppression, autoGainControl, sampleRate, channelCount sowie, je nach Browser, zoom, torch und focusMode. Numerische Eigenschaften werden als { min, max } angegeben, optional mit step.

Beispiele

Fähigkeiten der Webcam auslesen

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

const caps = videoTrack.getCapabilities();
console.log('Breite:', caps.width);
console.log('Höhe:', caps.height);
console.log('Bildrate:', caps.frameRate);
console.log('Kamerarichtung:', caps.facingMode);

Breite: { max: 1920, min: 1 } Höhe: { max: 1080, min: 1 } Bildrate: { max: 30, min: 1 } Kamerarichtung: ['user']

Maximale Auflösung anfordern, ohne OverconstrainedError

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

if (width?.max && height?.max) {
  await track.applyConstraints({
    width: { ideal: width.max },
    height: { ideal: height.max }
  });
}

const { width: w, height: h } = track.getSettings();
console.log(`Aktive Auflösung: ${w}x${h}`);

Aktive Auflösung: 1920x1080

Zoom-Regler nur anzeigen, wenn die Kamera Zoom unterstützt

const stream = await navigator.mediaDevices.getUserMedia({ video: { pan: true, zoom: true } });
const [track] = stream.getVideoTracks();
const caps = track.getCapabilities();
const slider = document.querySelector('#zoom');

if ('zoom' in caps) {
  slider.min = caps.zoom.min;
  slider.max = caps.zoom.max;
  slider.step = caps.zoom.step ?? 0.1;
  slider.value = track.getSettings().zoom;
  slider.hidden = false;
  slider.addEventListener('input', () => {
    track.applyConstraints({ advanced: [{ zoom: Number(slider.value) }] });
  });
} else {
  slider.hidden = true;
  console.log('Zoom wird von dieser Kamera nicht unterstützt.');
}

Audio-Fähigkeiten des Mikrofons prüfen

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

const supportsEchoCancel = caps.echoCancellation?.includes(true) ?? false;
console.log('Echounterdrückung möglich:', supportsEchoCancel);
console.log('Kanäle:', caps.channelCount);
console.log('Abtastrate:', caps.sampleRate);

Echounterdrückung möglich: true Kanäle: { max: 2, min: 1 } Abtastrate: { max: 48000, min: 48000 }

// Wichtig · Fallstricke

Browser-Unterstützung: Chrome, Edge und Safari unterstützen die Methode schon lange. Firefox unterstützt sie erst ab Version 132. Für ältere Firefox-Versionen sollten Sie die Methode vorher prüfen: typeof track.getCapabilities === 'function'.
Unterschiedlicher Inhalt: Welche Schlüssel und Wertebereiche geliefert werden, unterscheidet sich stark zwischen Browsern und Geräten. zoom, torch, pan, tilt und focusMode gibt es z. B. nur in Chromium-Browsern und nur bei passender Hardware. Für pan, tilt und zoom muss die Berechtigung außerdem bereits in getUserMedia() angefordert werden.
Nur nach Freigabe aussagekräftig: Die Methode braucht einen Track, und den gibt es erst nach getUserMedia() oder getDisplayMedia(). Die Werte gelten also immer für das Gerät, das bereits freigegeben wurde. Wenn Sie Fähigkeiten vor der Freigabe ermitteln wollen, gibt es InputDeviceInfo.getCapabilities() (aus enumerateDevices()). Diese Methode wird aber nicht überall unterstützt.
Datenschutz: Browser können Werte bewusst ungenau angeben oder Schlüssel weglassen, um Fingerprinting zu erschweren.
Beendete Tracks: Hat der Track den Zustand readyState === 'ended', kann das zurückgegebene Objekt leer sein.
Die Methode ist nur in einem sicheren Kontext (HTTPS oder localhost) sinnvoll nutzbar, weil getUserMedia() dort verfügbar sein muss.

Siehe auch

MediaStreamTrack MediaStreamTrack.getSettings() MediaStreamTrack.getConstraints() MediaStreamTrack.applyConstraints() MediaDevices.getUserMedia() MediaDevices.getSupportedConstraints() InputDeviceInfo.getCapabilities()