AudioSinkInfo — Schnittstelle · JavaScript-Referenz

Signatur

interface AudioSinkInfo

Beschreibung

AudioSinkInfo gehört zur Web Audio API. Du bekommst ein solches Objekt von AudioContext.sinkId, wenn der Kontext mit einem Optionsobjekt statt mit einer Geräte-ID erzeugt oder umgeschaltet wurde. Die Eigenschaft sinkId gibt also einen von zwei Typen zurück: einen String ("" für das Standardgerät oder die ID eines Ausgabegeräts) oder ein AudioSinkInfo-Objekt.

Die Schnittstelle hat nur eine schreibgeschützte Eigenschaft: AudioSinkInfo.type. Derzeit ist dort nur der Wert "none" möglich. Er bedeutet, dass der Audiograph weiterläuft, der Ton aber an kein Ausgabegerät geht. Das ist praktisch für Offline-ähnliche Analysen, für Aufnahmen über einen MediaStreamAudioDestinationNode oder um Audio stummzuschalten, ohne den Kontext mit suspend() anzuhalten. Die Zeit (currentTime) läuft dabei weiter.

Einen eigenen Konstruktor hat AudioSinkInfo nicht. Das Objekt entsteht durch new AudioContext({ sinkId: { type: "none" } }) oder durch audioContext.setSinkId({ type: "none" }). Bevor du auf .type zugreifst, prüfst du deshalb mit typeof ctx.sinkId === "object", welcher Typ vorliegt.

Parameter

Name	Typ	Default	Beschreibung
$type	"none"		Schreibgeschützte Eigenschaft der Instanz, kein Konstruktor-Parameter. Gibt die Art des Sinks an. Aktuell ist nur `"none"` definiert (keine Ausgabe an ein Gerät).

Rückgabewert

Typ

AudioSinkInfo

Beschreibung

Das Objekt, das AudioContext.sinkId zurückgibt, wenn als Sink ein Optionsobjekt statt einer Geräte-ID gesetzt wurde.

Beispiele

AudioContext ohne Ausgabegerät erzeugen

// Der Kontext rendert Audio, gibt aber nichts auf den Lautsprechern aus
const ctx = new AudioContext({ sinkId: { type: "none" } });

console.log(ctx.sinkId instanceof AudioSinkInfo);
console.log(ctx.sinkId.type);

true none

sinkId sicher auswerten (String oder AudioSinkInfo)

const describeSink = (ctx) => {
  const sink = ctx.sinkId;
  if (typeof sink === "object") {
    return `Kein Ausgabegerät (type: ${sink.type})`;
  }
  return sink === "" ? "Standard-Ausgabegerät" : `Gerät mit ID ${sink}`;
};

const ctx = new AudioContext();
console.log(describeSink(ctx));

Standard-Ausgabegerät

Stummschalten per setSinkId, ohne den Kontext anzuhalten

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { frequency: 440 });
osc.connect(ctx.destination);
osc.start();

const toggleOutput = async (muted) => {
  if (!("setSinkId" in AudioContext.prototype)) {
    console.warn("setSinkId wird nicht unterstützt");
    return;
  }
  // { type: "none" } erzeugt ein AudioSinkInfo, "" nimmt das Standardgerät
  await ctx.setSinkId(muted ? { type: "none" } : "");
  console.log("Aktueller Sink:", typeof ctx.sinkId === "object" ? ctx.sinkId.type : "Standard");
};

document.querySelector("#mute").addEventListener("click", () => toggleOutput(true));
document.querySelector("#unmute").addEventListener("click", () => toggleOutput(false));

Aktueller Sink: none

Auf Sink-Wechsel reagieren

const ctx = new AudioContext();

ctx.addEventListener("sinkchange", () => {
  const sink = ctx.sinkId;
  console.log("Sink gewechselt:", typeof sink === "object" ? `AudioSinkInfo(${sink.type})` : sink || "Standard");
});

await ctx.setSinkId({ type: "none" });

Sink gewechselt: AudioSinkInfo(none)

// Wichtig · Fallstricke

Experimentell: Die Schnittstelle wird nur von Chromium-Browsern (Chrome/Edge ab Version 110) unterstützt, nicht von Firefox und Safari. Prüfe vorher mit typeof AudioSinkInfo !== "undefined" oder "setSinkId" in AudioContext.prototype, ob sie vorhanden ist.
AudioContext.sinkId kann ein String oder ein AudioSinkInfo-Objekt sein. Wenn du ohne Typprüfung direkt sinkId.type liest, bekommst du bei einem String undefined.
Jeder Zugriff auf sinkId kann ein anderes Objekt liefern. Vergleiche deshalb sinkId.type und nicht die Objekte selbst mit ===.
{ type: "none" } ist nicht dasselbe wie suspend(): Der Audiograph läuft weiter und verbraucht Rechenzeit.
setSinkId() mit einer echten Geräte-ID kann durch die Permissions-Policy speaker-selection blockiert werden und erfordert in der Regel einen sicheren Kontext (HTTPS).

Siehe auch

AudioListener AudioSession AudioContext AudioEncoder AudioNode