MediaTrackConstraints.deviceId — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackConstraints.deviceId

Beschreibung

Die Eigenschaft deviceId im Wörterbuch MediaTrackConstraints legt fest, welches konkrete Gerät (Kamera, Mikrofon) für einen Medien-Track verwendet werden soll. Sie wird in den Constraints von navigator.mediaDevices.getUserMedia() oder bei MediaStreamTrack.applyConstraints() angegeben. Die passenden IDs erhält man über navigator.mediaDevices.enumerateDevices().

Der Wert ist ein ConstrainDOMString, also entweder:

ein einzelner string oder ein Array von Strings: Wird als ideal behandelt – der Browser bevorzugt das Gerät, weicht aber notfalls auf ein anderes aus.
ein Objekt { exact: … }: Das Gerät ist zwingend; ist es nicht verfügbar, schlägt der Aufruf mit OverconstrainedError fehl.
ein Objekt { ideal: … }: explizite Wunschangabe, gleichbedeutend mit dem einfachen String.

Typischer Einsatz ist eine Geräteauswahl in Videokonferenz- oder Aufnahme-Apps: Die Nutzerin wählt aus einer Liste die Kamera oder das Mikrofon, und die App fordert genau dieses Gerät an. Die deviceId ist pro Ursprung (Origin) stabil und kann z. B. in localStorage gespeichert werden, um die Auswahl beim nächsten Besuch wiederherzustellen.

Parameter

Name	Typ	Default	Beschreibung
$deviceId	string \| string[] \| { exact?: string \| string[], ideal?: string \| string[] }		ID des gewünschten Geräts aus `MediaDeviceInfo.deviceId`. Einfache Werte gelten als ideal, `exact` erzwingt das Gerät.

Rückgabewert

Typ

ConstrainDOMString

Beschreibung

Der gesetzte Constraint-Wert: String, String-Array oder Objekt mit exact/ideal. Den tatsächlich verwendeten Wert liefert track.getSettings().deviceId.

Beispiele

Bestimmte Kamera zwingend anfordern

const startCamera = async (deviceId) => {
  try {
    const stream = await navigator.mediaDevices.getUserMedia({
      video: { deviceId: { exact: deviceId } },
      audio: false
    });
    document.querySelector('video').srcObject = stream;
    const [track] = stream.getVideoTracks();
    console.log('Aktive Kamera:', track.label);
  } catch (err) {
    if (err.name === 'OverconstrainedError') {
      console.warn('Gewählte Kamera nicht verfügbar.');
    } else {
      console.error(err);
    }
  }
};

Aktive Kamera: FaceTime HD Camera

Geräteauswahl aus enumerateDevices() befüllen

const select = document.querySelector('#mic-select');

// Zuerst Berechtigung holen, sonst sind Labels/IDs leer
const tmp = await navigator.mediaDevices.getUserMedia({ audio: true });
tmp.getTracks().forEach((t) => t.stop());

const devices = await navigator.mediaDevices.enumerateDevices();
for (const d of devices.filter((d) => d.kind === 'audioinput')) {
  select.add(new Option(d.label || 'Mikrofon', d.deviceId));
}

select.addEventListener('change', async () => {
  const stream = await navigator.mediaDevices.getUserMedia({
    audio: { deviceId: { exact: select.value } }
  });
  localStorage.setItem('micId', select.value);
  console.log(stream.getAudioTracks()[0].getSettings().deviceId === select.value);
});

true

Gespeichertes Gerät bevorzugen (ideal) mit Fallback

const savedId = localStorage.getItem('camId');

const stream = await navigator.mediaDevices.getUserMedia({
  // ideal: nutzt das gespeicherte Gerät, fällt sonst auf ein anderes zurück
  video: savedId ? { deviceId: { ideal: savedId } } : true
});

const settings = stream.getVideoTracks()[0].getSettings();
console.log(settings.deviceId === savedId ? 'Gespeicherte Kamera' : 'Fallback-Kamera');

Gespeicherte Kamera

// Wichtig · Fallstricke

String allein ist nur ein Wunsch: { deviceId: id } ist ideal. Wer genau dieses Gerät braucht, muss { exact: id } verwenden – sonst liefert der Browser ggf. stillschweigend ein anderes Gerät.
Datenschutz: Vor erteilter Berechtigung liefert enumerateDevices() leere Labels und oft leere oder zufällige IDs. Die IDs sind pro Origin unterschiedlich und werden beim Löschen der Website-Daten zurückgesetzt – gespeicherte IDs daher immer mit Fallback nutzen.
In privaten Fenstern (Inkognito) ändern sich IDs pro Sitzung.
applyConstraints() mit einer anderen deviceId wechselt in vielen Browsern das Gerät nicht; zum Umschalten besser den alten Track stoppen und neu getUserMedia() aufrufen.
Nur in sicheren Kontexten (HTTPS, localhost) verfügbar. Unterstützung in allen aktuellen Browsern; ob deviceId unterstützt wird, zeigt navigator.mediaDevices.getSupportedConstraints().deviceId.
Für Kamera-Ausrichtung auf Mobilgeräten ist facingMode oft robuster als eine feste deviceId.

Siehe auch

MediaTrackConstraints.groupId MediaTrackConstraints.height MediaTrackConstraints.volume MediaTrackConstraints.width MediaTrackConstraints.facingMode