MediaTrackConstraints.groupId — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackConstraints.groupId

Beschreibung

Die Eigenschaft groupId des Wörterbuchs MediaTrackConstraints schränkt die Auswahl eines Eingabegeräts über seine Gruppenkennung ein. Mehrere Geräte haben dieselbe groupId, wenn sie zum selben physischen Gerät gehören – typisch ist ein Headset mit Mikrofon und Kopfhörer oder eine Webcam mit eingebautem Mikrofon.

Den Wert erhältst du von MediaDeviceInfo.groupId (über navigator.mediaDevices.enumerateDevices()) oder aus MediaStreamTrack.getSettings().groupId. Damit kannst du z. B. passend zur gewählten Kamera das zugehörige Mikrofon anfordern.

Als ConstrainDOMString kann der Wert sein:

ein string oder string[] – wird als ideal behandelt (Wunsch, kein Zwang),
ein Objekt { exact: ... } – verbindliche Vorgabe; ist sie nicht erfüllbar, schlägt getUserMedia() mit OverconstrainedError fehl,
ein Objekt { ideal: ... } – ausdrücklicher Wunschwert.

Die Gruppenkennung ist pro Ursprung (Origin) und Browsersitzung spezifisch, um Fingerprinting zu erschweren. Du solltest sie daher nicht dauerhaft speichern und seitenübergreifend verwenden.

Parameter

Name	Typ	Default	Beschreibung
$groupId	string \| string[] \| { exact?: string \| string[], ideal?: string \| string[] }		Gewünschte oder verbindliche Gruppenkennung(en). Ein bloßer String gilt als `ideal`, `exact` erzwingt die Übereinstimmung.

Rückgabewert

Typ

ConstrainDOMString | undefined

Beschreibung

Der gesetzte Einschränkungswert; undefined, wenn keine Einschränkung für groupId angegeben wurde.

Beispiele

Passendes Mikrofon zur gewählten Kamera anfordern

const startWithMatchingMic = async () => {
  // Zuerst Kamera öffnen
  const videoStream = await navigator.mediaDevices.getUserMedia({ video: true });
  const { groupId } = videoStream.getVideoTracks()[0].getSettings();

  // Mikrofon desselben physischen Geräts bevorzugen
  const audioStream = await navigator.mediaDevices.getUserMedia({
    audio: { groupId: { ideal: groupId } }
  });

  console.log('Kamera-Gruppe:', groupId);
  console.log('Mikro-Gruppe:', audioStream.getAudioTracks()[0].getSettings().groupId);
};

startWithMatchingMic().catch(console.error);

Kamera-Gruppe: 3f2a… Mikro-Gruppe: 3f2a…

Headset-Mikrofon verbindlich anfordern

const useHeadsetMic = async () => {
  const devices = await navigator.mediaDevices.enumerateDevices();
  const headsetOut = devices.find(
    (d) => d.kind === 'audiooutput' && /headset/i.test(d.label)
  );
  if (!headsetOut) throw new Error('Kein Headset gefunden');

  try {
    const stream = await navigator.mediaDevices.getUserMedia({
      audio: { groupId: { exact: headsetOut.groupId } }
    });
    console.log('Headset-Mikro aktiv:', stream.getAudioTracks()[0].label);
    return stream;
  } catch (err) {
    if (err.name === 'OverconstrainedError') {
      console.warn('Headset hat kein Mikrofon:', err.constraint);
    }
    throw err;
  }
};

useHeadsetMic().catch(console.error);

Headset-Mikro aktiv: Jabra Evolve 65 (Headset)

Unterstützung prüfen und Einschränkung auslesen

const supported = navigator.mediaDevices.getSupportedConstraints();
console.log('groupId unterstützt:', Boolean(supported.groupId));

const constraints = { audio: { groupId: ['abc123', 'def456'] } };
console.log(constraints.audio.groupId);

groupId unterstützt: true ["abc123", "def456"]

// Wichtig · Fallstricke

Labels und IDs erst nach Berechtigung: Vor einer erteilten Kamera-/Mikrofonfreigabe liefert enumerateDevices() oft leere label- und groupId-Werte.
Keine dauerhafte Kennung: groupId ist pro Origin gebunden und kann sich zwischen Sitzungen ändern (z. B. im privaten Modus oder nach dem Löschen der Cookies). Zum Wiedererkennen besser deviceId mit Rückfallebene verwenden.
exact vorsichtig einsetzen: Hat die Gruppe kein Gerät der angeforderten Art, wirft getUserMedia() einen OverconstrainedError. Mit ideal fällt der Browser auf ein anderes Gerät zurück.
Browser-Unterschiede: Die Zuordnung zu Gruppen übernimmt das Betriebssystem bzw. der Browser. Sie ist nicht immer zuverlässig, z. B. bei Bluetooth-Geräten oder in Safari.
Nur in sicheren Kontexten (HTTPS) verfügbar, wie die gesamte getUserMedia()-API.

Siehe auch

MediaStreamTrackGenerator.writable MediaTrackConstraints.deviceId MediaTrackConstraints.volume MediaTrackConstraints.height MediaTrackConstraints.latency