AudioContext: setSinkId()-Methode
Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig, bevor Sie diese produktiv verwenden.
Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.
Die setSinkId()
-Methode der AudioContext
-Schnittstelle legt das Ausgabe-Audiogerät für das AudioContext
fest. Wenn keine sink ID
explizit festgelegt wird, wird das Standard-Audioausgabegerät des Systems verwendet.
Um das Audiogerät auf ein anderes als das Standardgerät einzustellen, benötigt der Entwickler die Berechtigung, auf Audiogeräte zuzugreifen. Falls erforderlich, kann der Benutzer aufgefordert werden, die erforderliche Genehmigung über einen Aufruf von MediaDevices.getUserMedia()
zu erteilen.
Darüber hinaus kann diese Funktion durch eine speaker-selection
Berechtigungsrichtlinie blockiert werden.
Syntax
setSinkId(sinkId)
Parameter
sinkId
-
Die
sink ID
des Geräts, das Sie als Audiowiedergabegerät festlegen möchten. Dies kann einen der folgenden Wertetypen annehmen:- String
-
Ein String, der die
sink ID
darstellt, zum Beispiel abgerufen über diedeviceId
-Eigenschaft derMediaDeviceInfo
-Objekte, die vonMediaDevices.enumerateDevices()
zurückgegeben werden. AudioSinkOptions
-
Ein Objekt, das verschiedene Optionen für eine
sink ID
darstellt. Derzeit nimmt dieses eine einzelne Eigenschaft,type
, mit dem Wertnone
an. Das Festlegen dieses Parameters führt dazu, dass das Audio verarbeitet wird, ohne über ein Audiowiedergabegerät abgespielt zu werden. Dies ist eine nützliche Option, um den Energieverbrauch zu minimieren, wenn keine Wiedergabe zusammen mit der Verarbeitung benötigt wird.
Rückgabewert
Ein Promise
, das mit einem Wert von undefined
erfüllt wird.
Der Versuch, die sink ID
auf ihren bestehenden Wert (d. h. zurückgegeben von AudioContext.sinkId
) zu setzen, erzeugt keine Fehler, bricht jedoch den Prozess sofort ab.
Ausnahmen
InvalidAccessError
DOMException
-
Wird ausgelöst, wenn der Zugriff auf das ausgewählte Audiowiedergabegerät fehlgeschlagen ist.
NotAllowedError
DOMException
-
Wird ausgelöst, wenn der Browser keine Berechtigung hat, auf Audiogeräte zuzugreifen.
NotFoundError
DOMException
-
Wird ausgelöst, wenn die übergebene
sinkId
mit keinem auf dem System gefundenen Audiogerät übereinstimmt.
Beispiele
In unserem SetSinkId-Testbeispiel (sehen Sie sich den Quellcode an), erstellen wir einen Audio-Graphen, der einen dreisekündigen Abbruch von weißem Rauschen über einen AudioBufferSourceNode
erzeugt, den wir auch durch einen GainNode
laufen lassen, um die Lautstärke etwas zu reduzieren.
Wir bieten dem Benutzer auch ein Dropdown-Menü an, das ihnen erlaubt, das Audiowiedergabegerät spontan zu ändern. Dazu:
-
Bieten wir einen Button an, um das Dropdown-Menü zu füllen. Wir rufen zuerst
MediaDevices.getUserMedia()
auf, um die erforderliche Berechtigungsaufforderung auszulösen, die wir benötigen, um die Geräteeinzugserlaubnis zu erhalten, und verwenden dannMediaDevices.enumerateDevices()
, um alle verfügbaren Geräte abzurufen. Wir durchlaufen die verschiedenen Geräte und machen jedes als Option in einem<select>
-Element verfügbar. Wir erstellen auch eine "None"-Option für den Fall, dass Sie Ihr Audio nicht in irgendeiner Ausgabe abspielen möchten.jsmediaDeviceBtn.addEventListener('click', async () => { if ("setSinkId" in AudioContext.prototype) { selectDiv.textContent = ""; const stream = await navigator.mediaDevices.getUserMedia({ audio: true }); const devices = await navigator.mediaDevices.enumerateDevices(); // Most of the DOM scripting to generate the dropdown cut out for brevity const audioOutputs = devices.filter( (device) => device.kind === 'audiooutput' && device.deviceId !== 'default' ); audioOutputs.forEach((device) => { const option = document.createElement('option') option.value = device.deviceId; option.textContent = device.label; select.appendChild(option); }); const option = document.createElement('option') option.value = 'none'; option.textContent = 'None'; select.appendChild(option); //...
-
Fügen wir ein
change
-Ereignislistener zum<select>
-Element hinzu, um diesink ID
und damit das Audiowiedergabegerät zu ändern, wenn ein neuer Wert ausgewählt wird. Wenn "None" im Dropdown ausgewählt wird, rufen wirsetSinkId()
mit dem{ type : 'none' }
-Objektparameter auf, um kein Audiogerät auszuwählen, andernfalls verwenden wir dievalue
-Attribut des<select>
-Elements als Parameter mit der Audiogeräte-ID.js// ... select.addEventListener('change', async () => { if(select.value === 'none') { await audioCtx.setSinkId({ type : 'none' }); } else { await audioCtx.setSinkId(select.value); } }) } });
Das Ausgabegerät kann während der Audiowiedergabe, sowie davor oder zwischen den Wiedergaben geändert werden.
Spezifikationen
Specification |
---|
Web Audio API # dom-audiocontext-setsinkid |
Browser-Kompatibilität
BCD tables only load in the browser