AudioNode.numberOfOutputs — Eigenschaft · JavaScript-Referenz

Signatur

AudioNode.numberOfOutputs

Beschreibung

Die Eigenschaft numberOfOutputs gibt als ganze Zahl (unsigned long) an, wie viele Ausgänge ein Audioknoten hat. Über jeden Ausgang kann der Knoten mit connect() an andere Knoten oder an einen AudioParam angeschlossen werden. Die Eigenschaft ist schreibgeschützt. Der Wert wird beim Erzeugen des Knotens festgelegt und ändert sich danach nicht mehr.

Welcher Wert herauskommt, hängt vom Knotentyp ab:

0 Ausgänge: AudioDestinationNode (Endpunkt des Graphen, also context.destination).
1 Ausgang: fast alle anderen Knoten, z. B. OscillatorNode, GainNode, BiquadFilterNode, AnalyserNode, ChannelMergerNode und MediaElementAudioSourceNode.
Frei wählbar: ChannelSplitterNode (Option numberOfOutputs, Standard 6) und AudioWorkletNode (Option numberOfOutputs, Standard 1).

Nützlich ist die Eigenschaft vor allem, wenn man Audiographen generisch aufbaut oder prüft, etwa in Hilfsfunktionen, Visualisierungen des Graphen oder Bibliotheken. Damit lässt sich vor einem Aufruf von connect(ziel, outputIndex) prüfen, ob der gewünschte Ausgangsindex überhaupt existiert. Bei Knoten mit mehreren Ausgängen wie dem ChannelSplitterNode kann man so alle Ausgänge in einer Schleife ansprechen.

Rückgabewert

Typ

number

Beschreibung

Nicht-negative ganze Zahl mit der Anzahl der Ausgänge des Knotens. Bei einem AudioDestinationNode ist der Wert 0.

Beispiele

Anzahl der Ausgänge verschiedener Knoten auslesen

const ctx = new AudioContext();

const osc = ctx.createOscillator();
const gain = ctx.createGain();
const splitter = ctx.createChannelSplitter(4);

console.log('Oscillator:', osc.numberOfOutputs);
console.log('Gain:', gain.numberOfOutputs);
console.log('Splitter:', splitter.numberOfOutputs);
console.log('Destination:', ctx.destination.numberOfOutputs);

Oscillator: 1 Gain: 1 Splitter: 4 Destination: 0

Alle Ausgänge eines ChannelSplitterNode einzeln verarbeiten

const ctx = new AudioContext();
const osc = new OscillatorNode(ctx, { frequency: 440 });
const splitter = new ChannelSplitterNode(ctx, { numberOfOutputs: 2 });
const merger = new ChannelMergerNode(ctx, { numberOfInputs: 2 });

osc.connect(splitter);

// Jeden Ausgang des Splitters mit eigener Lautstärke an den Merger führen
const gains = [];
for (let i = 0; i < splitter.numberOfOutputs; i++) {
  const g = new GainNode(ctx, { gain: i === 0 ? 1 : 0.3 });
  splitter.connect(g, i);   // Ausgang i des Splitters
  g.connect(merger, 0, i);  // an Eingang i des Mergers
  gains.push(g);
}

merger.connect(ctx.destination);
console.log(`${gains.length} Kanäle verdrahtet`);

2 Kanäle verdrahtet

Sicheres Verbinden mit Prüfung des Ausgangsindex

const safeConnect = (source, target, outputIndex = 0, inputIndex = 0) => {
  if (source.numberOfOutputs === 0) {
    throw new Error(`${source.constructor.name} hat keine Ausgänge`);
  }
  if (outputIndex >= source.numberOfOutputs) {
    throw new RangeError(
      `Ausgang ${outputIndex} existiert nicht (max. ${source.numberOfOutputs - 1})`
    );
  }
  return source.connect(target, outputIndex, inputIndex);
};

const ctx = new AudioContext();
const gain = ctx.createGain();

safeConnect(gain, ctx.destination);

try {
  safeConnect(gain, ctx.destination, 1);
} catch (err) {
  console.log(err.message);
}

Ausgang 1 existiert nicht (max. 0)

AudioWorkletNode mit mehreren Ausgängen

// processor.js muss per addModule geladen werden und 'multi-out' registrieren
const ctx = new AudioContext();
await ctx.audioWorklet.addModule('processor.js');

const node = new AudioWorkletNode(ctx, 'multi-out', {
  numberOfInputs: 1,
  numberOfOutputs: 3,
  outputChannelCount: [2, 1, 1]
});

console.log(node.numberOfOutputs);

3

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie node.numberOfOutputs = 2 wird im nicht-strikten Modus stillschweigend ignoriert und löst im Strict Mode einen TypeError aus. Die Anzahl lässt sich nur beim Erzeugen festlegen, und das auch nur bei ChannelSplitterNode und AudioWorkletNode.
Ungültiger Index: Ist bei connect(ziel, outputIndex) der outputIndex größer oder gleich numberOfOutputs, wirft der Browser eine IndexSizeError-DOMException.
Ausgänge und Kanäle sind verschieden: Ein einzelner Ausgang kann mehrere Kanäle führen, zum Beispiel stereo. Die Kanalzahl steuern channelCount und channelCountMode, nicht numberOfOutputs.
Ein ChannelSplitterNode kann höchstens so viele Ausgänge haben, wie AudioContext Kanäle unterstützt (mindestens 32). Bei 0 oder einem zu großen Wert wirft der Konstruktor eine IndexSizeError.
Browserunterstützung: Die Eigenschaft funktioniert in allen modernen Browsern. Ältere WebKit-Versionen brauchen unter Umständen webkitAudioContext. Außerdem startet AudioContext ohne Benutzerinteraktion im Zustand suspended. Das Auslesen der Eigenschaft klappt trotzdem.

Siehe auch

AudioNode.numberOfInputs AudioNode.prototype.connect() AudioNode.prototype.disconnect() AudioNode.channelCount ChannelSplitterNode AudioWorkletNode AudioNode