MediaDeviceInfo.label — Eigenschaft · JavaScript-Referenz

Signatur

MediaDeviceInfo.label

Beschreibung

Die Eigenschaft label eines MediaDeviceInfo-Objekts enthält den für Menschen lesbaren Namen eines Ein- oder Ausgabegeräts, etwa "FaceTime HD Camera" oder "Mikrofon (Realtek High Definition Audio)". Die Objekte liefert navigator.mediaDevices.enumerateDevices().

Gebraucht wird label vor allem für Geräteauswahl-Menüs in Videokonferenz-, Aufnahme- oder Streaming-Anwendungen. Dort sollen Nutzer zwischen mehreren Kameras, Mikrofonen oder Lautsprechern wählen. Den Namen zeigen Sie an; zum Öffnen des Geräts verwenden Sie die deviceId.

Wichtig für den Datenschutz: Der Browser liefert das Label nur, wenn die Seite bereits Zugriff auf Mediengeräte hat. Das ist der Fall, wenn gerade ein Stream über getUserMedia() aktiv ist oder die Berechtigung dauerhaft erteilt wurde. Andernfalls ist label eine leere Zeichenkette "", und manche Browser geben dann auch nur je ein allgemeines Gerät pro Art zurück.

Rückgabewert

Typ

string

Beschreibung

Lesbarer Gerätename. Ohne Medienberechtigung eine leere Zeichenkette "".

Beispiele

Alle Geräte mit Label auflisten

const listDevices = async () => {
  const devices = await navigator.mediaDevices.enumerateDevices();
  devices.forEach(({ kind, label, deviceId }) => {
    console.log(`${kind}: ${label || '(kein Label – Berechtigung fehlt)'} [${deviceId}]`);
  });
};

listDevices();

videoinput: (kein Label – Berechtigung fehlt) [] audioinput: (kein Label – Berechtigung fehlt) []

Erst Berechtigung holen, dann Labels lesen

const getLabeledDevices = async () => {
  // Kurz einen Stream öffnen, damit der Browser die Labels freigibt
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: true });
  const devices = await navigator.mediaDevices.enumerateDevices();
  // Stream wieder schließen, damit Kamera und Mikrofon nicht aktiv bleiben
  stream.getTracks().forEach((track) => track.stop());
  return devices.map((d) => d.label);
};

getLabeledDevices().then(console.log);

["FaceTime HD Camera", "MacBook Pro-Mikrofon", "MacBook Pro-Lautsprecher"]

Kamera-Auswahlmenü befüllen und Gerät öffnen

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

const fillCameraSelect = async () => {
  const devices = await navigator.mediaDevices.enumerateDevices();
  const cameras = devices.filter((d) => d.kind === 'videoinput');
  select.replaceChildren(
    ...cameras.map((cam, i) => new Option(cam.label || `Kamera ${i + 1}`, cam.deviceId))
  );
};

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

// Labels nach An- oder Abstecken eines Geräts aktualisieren
navigator.mediaDevices.addEventListener('devicechange', fillCameraSelect);
fillCameraSelect();

// Wichtig · Fallstricke

Leeres Label: Ohne aktive oder dauerhafte Medienberechtigung ist label immer "". Planen Sie deshalb einen Ersatznamen ein, etwa „Kamera 1“.
Nicht als Kennung verwenden: Labels sind nicht eindeutig. Zwei baugleiche Webcams können denselben Namen haben, und der Text hängt von Betriebssystem, Treiber und Sprache ab. Zum Auswählen eines Geräts nehmen Sie deviceId.
Fingerprinting: Gerätenamen können einen Nutzer wiedererkennbar machen. Deshalb geben Browser sie nur eingeschränkt heraus. Speichern oder übertragen Sie Labels nicht ohne Grund.
Sicherer Kontext: navigator.mediaDevices gibt es nur über HTTPS oder auf localhost.
Ausgabegeräte: audiooutput-Einträge und ihre Labels liefern die Browser unterschiedlich aus. Firefox zeigt sie zum Beispiel erst nach selectAudioOutput() oder bei bestimmten Berechtigungen.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung hat keine Wirkung.

Siehe auch

MediaDeviceInfo.kind MediaDeviceInfo.deviceId MediaDeviceInfo.groupId GPUDevice.label MediaStreamTrack.label