Signatur
Beschreibung
Die Eigenschaft sinkId eines HTMLMediaElement (also eines <audio>- oder <video>-Elements) gibt als String die deviceId des Audio-Ausgabegeräts zurück, über das das Element gerade abspielt. Ein leerer String ("") steht für das vom Betriebssystem bzw. Browser festgelegte Standard-Ausgabegerät.
Die Eigenschaft ist schreibgeschützt. Das Ausgabegerät ändern Sie nicht per Zuweisung, sondern über die asynchrone Methode HTMLMediaElement.setSinkId(). Hat deren Promise erfüllt, gibt sinkId den neuen Wert zurück.
Typische Einsatzfälle sind Videokonferenz-Anwendungen, Softphones und Medienplayer, in denen man zwischen Lautsprechern, Kopfhörer und Headset wählen kann. Die verfügbaren Geräte-IDs liefert navigator.mediaDevices.enumerateDevices() (Einträge mit kind === "audiooutput"). In Firefox gibt es außerdem navigator.mediaDevices.selectAudioOutput().
Rückgabewert
deviceId des aktuellen Audio-Ausgabegeräts oder "" (leerer String), wenn das Standard-Ausgabegerät verwendet wird.Beispiele
Aktuelles Ausgabegerät auslesen
const audio = document.querySelector('audio');
if ('sinkId' in HTMLMediaElement.prototype) {
console.log(audio.sinkId === '' ? 'Standard-Ausgabegerät' : `Gerät: ${audio.sinkId}`);
} else {
console.log('Auswahl des Ausgabegeräts wird nicht unterstützt');
}Ausgabegerät wechseln und sinkId prüfen
const video = document.querySelector('video');
const switchOutput = async (deviceId) => {
try {
await video.setSinkId(deviceId);
console.log('Neue sinkId:', video.sinkId);
} catch (err) {
console.error('Wechsel fehlgeschlagen:', err.name, err.message);
}
};
// Zurück zum Standardgerät
switchOutput('');Geräteauswahl für eine Videokonferenz-App
const audio = document.querySelector('#remote-audio');
const select = document.querySelector('#speaker-select');
const fillSpeakerList = async () => {
// Ohne Berechtigung sind Labels (und teils IDs) leer
await navigator.mediaDevices.getUserMedia({ audio: true });
const devices = await navigator.mediaDevices.enumerateDevices();
const outputs = devices.filter((d) => d.kind === 'audiooutput');
select.replaceChildren(
...outputs.map((d) => new Option(d.label || 'Unbenanntes Gerät', d.deviceId, false, d.deviceId === audio.sinkId))
);
};
select.addEventListener('change', async () => {
await audio.setSinkId(select.value);
console.log('Aktiv:', audio.sinkId);
});
fillSpeakerList();// Wichtig · Fallstricke
- Schreibgeschützt:
audio.sinkId = 'xyz'hat keine Wirkung (im Strict Mode wird einTypeErrorgeworfen). Zum Ändern verwenden SiesetSinkId(). - Browser-Kompatibilität: Unterstützt in Chromium-basierten Browsern und ab Firefox 116. Safari unterstützt die Eigenschaft nicht (Stand 2024). Prüfen Sie vorher per
'sinkId' in HTMLMediaElement.prototype, ob sie vorhanden ist. - Nur in sicheren Kontexten (HTTPS) verfügbar.
setSinkId()kann außerdem durch die Permissions-Policyspeaker-selectionblockiert sein, etwa in iframes ohne entsprechendesallow-Attribut. - Datenschutz: Geräte-IDs gelten nur für den jeweiligen Ursprung (Origin) und können sich z. B. nach dem Löschen von Cookies ändern. Speichern Sie sie deshalb nicht dauerhaft, ohne sie beim nächsten Laden erneut zu prüfen.
- Wird das Gerät getrennt, bleibt
sinkIdunter Umständen auf der alten ID stehen. Reagieren Sie auf das Ereignisdevicechangevonnavigator.mediaDevices.