MediaDeviceInfo — Schnittstelle · JavaScript-Referenz

Signatur

interface MediaDeviceInfo

Beschreibung

Die Schnittstelle MediaDeviceInfo gehört zur Media Capture and Streams API. Jedes Objekt steht für genau ein Medien-Ein- oder Ausgabegerät. Solche Objekte erzeugt man nie selbst. Man bekommt sie als Array aus dem Promise von navigator.mediaDevices.enumerateDevices().

Die Schnittstelle hat vier schreibgeschützte Eigenschaften und eine Methode:

deviceId (string): eine Kennung für das Gerät. Sie bleibt über Sitzungen hinweg gleich, gilt aber nur für diesen Ursprung (Origin). Wenn der Nutzer Cookies oder Website-Daten löscht, wird sie neu erzeugt.
kind ("videoinput" | "audioinput" | "audiooutput"): die Art des Geräts.
label (string): ein lesbarer Name, z. B. „Integrated Webcam“. Ohne erteilte Berechtigung ist er leer.
groupId (string): Die Kennung ist bei Geräten gleich, die physisch zusammengehören, z. B. Mikrofon und Lautsprecher eines Headsets.
toJSON(): gibt die Eigenschaften als einfaches Objekt zurück.

Typische Anwendungsfälle sind Geräteauswahl-Menüs in Videokonferenz-Apps, das Umschalten zwischen Front- und Rückkamera und die Wahl des Audio-Ausgabegeräts über HTMLMediaElement.setSinkId(). Mit der deviceId fordert man danach über getUserMedia({ video: { deviceId: { exact: id } } }) gezielt ein bestimmtes Gerät an.

Für Eingabegeräte (audioinput, videoinput) liefern Browser Objekte der Unterklasse InputDeviceInfo. Diese bietet zusätzlich getCapabilities(), um z. B. mögliche Auflösungen abzufragen.

Rückgabewert

Typ

MediaDeviceInfo

Beschreibung

Wird nicht per Konstruktor erzeugt. Man erhält die Objekte als Elemente des Arrays, das navigator.mediaDevices.enumerateDevices() liefert (Promise<MediaDeviceInfo[]>).

Beispiele

Alle Mediengeräte auflisten

const listDevices = async () => {
  const devices = await navigator.mediaDevices.enumerateDevices();
  for (const { kind, label, deviceId } of devices) {
    console.log(`${kind}: ${label || '(kein Name – Berechtigung fehlt)'} [${deviceId.slice(0, 8)}…]`);
  }
};

listDevices();

audioinput: Standard - Mikrofon (Realtek) [default…] videoinput: Integrated Webcam [3f9a1c2b…] audiooutput: Lautsprecher (Realtek) [a81d0e44…]

Kamera-Auswahl mit echten Gerätenamen

const select = document.querySelector('#camera');
const video = document.querySelector('video');

const init = async () => {
  // Erst Berechtigung holen, sonst ist label leer
  const tmp = await navigator.mediaDevices.getUserMedia({ video: true });
  tmp.getTracks().forEach((t) => t.stop());

  const cams = (await navigator.mediaDevices.enumerateDevices())
    .filter((d) => d.kind === 'videoinput');

  select.replaceChildren(...cams.map((cam, i) =>
    new Option(cam.label || `Kamera ${i + 1}`, cam.deviceId)));

  select.addEventListener('change', () => start(select.value));
  start(select.value);
};

const start = async (deviceId) => {
  video.srcObject?.getTracks().forEach((t) => t.stop());
  video.srcObject = await navigator.mediaDevices.getUserMedia({
    video: { deviceId: { exact: deviceId } }
  });
};

init();

Audio-Ausgabegerät wählen und Headset-Gruppen finden

const devices = await navigator.mediaDevices.enumerateDevices();
const outputs = devices.filter((d) => d.kind === 'audiooutput');
const audio = document.querySelector('audio');

if (outputs.length && 'setSinkId' in audio) {
  await audio.setSinkId(outputs[0].deviceId);
}

// Mikrofone suchen, die zur gleichen Hardware gehören wie der Ausgang
const mics = devices.filter(
  (d) => d.kind === 'audioinput' && d.groupId === outputs[0]?.groupId
);
console.log(JSON.stringify(mics.map((m) => m.toJSON()), null, 2));

[ { "deviceId": "b2c7…", "kind": "audioinput", "label": "Headset-Mikrofon", "groupId": "9e41…" } ]

// Wichtig · Fallstricke

Datenschutz: Solange keine Medienberechtigung erteilt ist, sind label und oft auch deviceId und groupId leere Zeichenketten. Viele Browser liefern dann auch nur ein Gerät pro Art. Zuerst getUserMedia() aufrufen und danach enumerateDevices().
Sicherer Kontext: navigator.mediaDevices gibt es nur unter HTTPS oder localhost. In iframes muss die Permissions Policy (allow="camera; microphone") den Zugriff erlauben.
Die deviceId gilt nur für den Ursprung und kann sich ändern, z. B. nach dem Löschen von Website-Daten oder in privaten Fenstern. Beim Speichern in localStorage daher immer eine Ausweichlösung vorsehen.
Die Sonderwerte "default" bzw. "communications" als deviceId gibt es nur in Chromium-Browsern.
audiooutput-Geräte und setSinkId() unterstützt Safari nicht oder nur eingeschränkt. Firefox listet Ausgabegeräte teils erst, nachdem der Zugriff über selectAudioOutput() erlaubt wurde.
Wenn Geräte angeschlossen oder entfernt werden, das Event devicechange auf navigator.mediaDevices abhören und die Liste neu laden. Einmal gelesene MediaDeviceInfo-Objekte werden nicht aktualisiert.

Siehe auch

MediaDevices InputDeviceInfo AudioSinkInfo HIDDevice HMDVRDevice