MediaTrackSettings.deviceId — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSettings.deviceId

Beschreibung

Die Eigenschaft deviceId im Wörterbuch MediaTrackSettings gibt an, welches Eingabegerät gerade einen Medien-Track liefert. Den Wert erhält man über MediaStreamTrack.getSettings(). Er entspricht der deviceId, die navigator.mediaDevices.enumerateDevices() für dasselbe Gerät in einem MediaDeviceInfo-Objekt zurückgibt.

Die Kennung ist an den Ursprung gebunden, also an die Kombination aus Schema, Host und Port. Eine andere Website bekommt für dieselbe Kamera eine andere ID. Für denselben Ursprung bleibt die ID normalerweise über mehrere Sitzungen gleich, solange der Nutzer Cookies und Website-Daten nicht löscht. Deshalb eignet sie sich dafür, das zuletzt gewählte Gerät zu speichern, zum Beispiel in localStorage, und es beim nächsten Besuch mit dem Constraint { deviceId: { exact: id } } wieder anzufordern.

Typische Einsatzfälle:

In einer Geräteauswahl (<select>) das aktive Gerät markieren.
Die Gerätewahl des Nutzers dauerhaft speichern.
Prüfen, ob der Browser das angeforderte Gerät tatsächlich verwendet oder stillschweigend auf ein anderes ausgewichen ist.

Rückgabewert

Typ

string

Beschreibung

Eine undurchsichtige, an den Ursprung gebundene Kennung des Quellgeräts. Bei Tracks ohne physisches Gerät (z. B. aus canvas.captureStream() oder WebAudio) fehlt die Eigenschaft oft oder ist ein leerer String.

Beispiele

Aktives Kameragerät ermitteln

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

// Passendes Gerät aus der Liste suchen, um die Bezeichnung zu erhalten
const devices = await navigator.mediaDevices.enumerateDevices();
const camera = devices.find((d) => d.kind === 'videoinput' && d.deviceId === deviceId);
console.log(`Aktive Kamera: ${camera?.label ?? 'unbekannt'} (${deviceId})`);

Aktive Kamera: FaceTime HD Camera (3f1a9c...e27b)

Mikrofonwahl speichern und später wiederherstellen

const STORAGE_KEY = 'preferredMicId';

const openMicrophone = async () => {
  const savedId = localStorage.getItem(STORAGE_KEY);
  const constraints = {
    audio: savedId ? { deviceId: { exact: savedId } } : true
  };

  try {
    const stream = await navigator.mediaDevices.getUserMedia(constraints);
    const [track] = stream.getAudioTracks();
    localStorage.setItem(STORAGE_KEY, track.getSettings().deviceId);
    return stream;
  } catch (err) {
    if (err.name === 'OverconstrainedError') {
      // Gerät nicht mehr vorhanden: gespeicherte ID verwerfen, Standardgerät nehmen
      localStorage.removeItem(STORAGE_KEY);
      return navigator.mediaDevices.getUserMedia({ audio: true });
    }
    throw err;
  }
};

const micStream = await openMicrophone();
console.log('Mikrofon aktiv:', micStream.getAudioTracks()[0].getSettings().deviceId);

Mikrofon aktiv: 9b2e...41ac

Geräteauswahl mit aktivem Gerät vorbelegen

const select = document.querySelector('#camera-select');
let stream = await navigator.mediaDevices.getUserMedia({ video: true });

const fillSelect = async () => {
  const activeId = stream.getVideoTracks()[0].getSettings().deviceId;
  const cams = (await navigator.mediaDevices.enumerateDevices())
    .filter((d) => d.kind === 'videoinput');
  select.replaceChildren(...cams.map((cam, i) => {
    const opt = new Option(cam.label || `Kamera ${i + 1}`, cam.deviceId);
    opt.selected = cam.deviceId === activeId;
    return opt;
  }));
};

select.addEventListener('change', async () => {
  stream.getTracks().forEach((t) => t.stop());
  stream = await navigator.mediaDevices.getUserMedia({
    video: { deviceId: { exact: select.value } }
  });
  document.querySelector('video').srcObject = stream;
});

await fillSelect();

// Wichtig · Fallstricke

Datenschutz: Bevor der Nutzer Zugriff gewährt hat, liefert enumerateDevices() meist leere IDs und Bezeichnungen. getSettings().deviceId steht erst nach einem erfolgreichen getUserMedia()-Aufruf zur Verfügung. Löscht der Nutzer Website-Daten oder surft er privat, können sich die IDs ändern. Speichere sie deshalb nur als Vorliebe und nie als festen Schlüssel.
exact oder nicht: { deviceId: id } ist nur ein Wunsch. Ist das Gerät nicht verfügbar, nimmt der Browser ohne Hinweis ein anderes. Mit { exact: id } wird stattdessen ein OverconstrainedError geworfen. Vergleiche nach dem Aufruf die Werte aus getSettings().deviceId, um sicherzugehen.
Nur Lesen: Das Gerät lässt sich nicht über applyConstraints() wechseln. Dafür muss man mit getUserMedia() einen neuen Track anfordern und den alten mit stop() beenden.
Spezielle IDs: Chromium kennt die Pseudo-IDs "default" und "communications" für Audiogeräte. Sie können auf dasselbe physische Gerät verweisen wie eine andere ID. Wer zusätzlich groupId vergleicht, findet solche Doppelungen.
Sicherer Kontext: getUserMedia() und damit auch dieser Wert funktionieren nur über HTTPS oder localhost.

Siehe auch

MediaDeviceInfo.deviceId MediaTrackSettings.groupId MediaTrackSettings.height MediaTrackSettings.volume MediaTrackSettings.width