Signatur
Beschreibung
Die Eigenschaft groupId des Dictionaries MediaTrackSettings gibt an, zu welcher physischen Gerätegruppe die Quelle eines Tracks gehört. Geräte mit derselben groupId gehören zum selben Gerät, z. B. Mikrofon und Lautsprecher eines USB-Headsets oder Kamera und eingebautes Mikrofon einer Webcam. Den Wert erhält man über MediaStreamTrack.getSettings().
Typische Anwendung: Man findet zu einem verwendeten Mikrofon oder einer Kamera passende weitere Geräte. Dazu vergleicht man den Wert mit MediaDeviceInfo.groupId aus navigator.mediaDevices.enumerateDevices(). So lässt sich z. B. automatisch der Lautsprecher des Headsets auswählen, dessen Mikrofon gerade aktiv ist.
Der Wert ist undurchsichtig: Er enthält keine Information über den Gerätetyp und ist pro Ursprung (Origin) und Browsersitzung vergeben. Um Fingerprinting zu erschweren, kann er sich zwischen Sitzungen ändern. Er ist also nicht dazu gedacht, dauerhaft gespeichert und später wiederverwendet zu werden. Dafür eignet sich eher deviceId.
groupId kann in getUserMedia() auch als Einschränkung (Constraint) genutzt werden. Das ist nur innerhalb derselben Sitzung sinnvoll.
Rückgabewert
Beispiele
groupId eines Mikrofon-Tracks auslesen
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [track] = stream.getAudioTracks();
const { groupId, deviceId } = track.getSettings();
console.log('Gerät:', track.label);
console.log('groupId:', groupId);
console.log('deviceId:', deviceId);Passenden Lautsprecher zum aktiven Headset-Mikrofon wählen
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const { groupId } = stream.getAudioTracks()[0].getSettings();
const devices = await navigator.mediaDevices.enumerateDevices();
const speaker = devices.find(
(d) => d.kind === 'audiooutput' && d.groupId === groupId
);
const audio = document.querySelector('audio');
if (speaker && 'setSinkId' in audio) {
await audio.setSinkId(speaker.deviceId);
console.log('Ausgabe auf:', speaker.label);
} else {
console.log('Kein passender Lautsprecher gefunden – Standardausgabe bleibt aktiv.');
}Mikrofon derselben Webcam anfordern
const video = await navigator.mediaDevices.getUserMedia({ video: true });
const { groupId } = video.getVideoTracks()[0].getSettings();
// Mikrofon aus derselben Gerätegruppe bevorzugen
const mic = await navigator.mediaDevices.getUserMedia({
audio: { groupId: { ideal: groupId } }
});
const micSettings = mic.getAudioTracks()[0].getSettings();
console.log('Gleiche Gruppe:', micSettings.groupId === groupId);// Wichtig · Fallstricke
- Nicht dauerhaft speichern: Der Wert kann sich zwischen Sitzungen ändern und gilt nur für den aktuellen Ursprung. Für eine gespeicherte Geräteauswahl ist
deviceIdbesser geeignet. Man sollte aber auch dafür einen Fallback vorsehen. - Berechtigungen: Solange keine Medienberechtigung erteilt wurde, liefert
enumerateDevices()leere oder eingeschränktegroupId-Werte. Ein Abgleich klappt meist erst nach einem erfolgreichengetUserMedia()-Aufruf. - Einschränkung mit
exact:{ groupId: { exact: … } }führt zu einemOverconstrainedError, wenn kein passendes Gerät existiert.idealist toleranter. - Kompatibilität: Wird von allen modernen Browsern unterstützt. Die Gruppierung hängt jedoch von Betriebssystem und Treiber ab. Nicht jedes Gerät meldet eine sinnvolle Gruppe, z. B. virtuelle Kameras.
setSinkId()für die Ausgabewahl ist in Safari erst in neueren Versionen verfügbar. - Nur in sicheren Kontexten (HTTPS) verfügbar, wie die gesamte
mediaDevices-API.