AudioNode.numberOfInputs — Eigenschaft · JavaScript-Referenz

Signatur

AudioNode.numberOfInputs

Beschreibung

Die schreibgeschützte Eigenschaft numberOfInputs eines AudioNode gibt als ganze Zahl an, wie viele Eingänge der Knoten hat. An diese Eingänge können andere Knoten mit connect() angeschlossen werden. Den Wert legt der Knotentyp fest oder man bestimmt ihn beim Erzeugen des Knotens. Danach lässt er sich nicht mehr ändern.

Typische Werte:

0 bei Quellknoten wie OscillatorNode, AudioBufferSourceNode, ConstantSourceNode, MediaElementAudioSourceNode und MediaStreamAudioSourceNode. Diese Knoten erzeugen selbst ein Signal.
1 bei den meisten Verarbeitungsknoten wie GainNode, BiquadFilterNode, AnalyserNode, DelayNode, ChannelSplitterNode und beim AudioDestinationNode (context.destination).
Frei wählbar beim ChannelMergerNode (Standard: 6, festgelegt über createChannelMerger(n)) und beim AudioWorkletNode (Option numberOfInputs, Standard: 1).

Die Eigenschaft ist vor allem nützlich, wenn man Audiographen generisch aufbaut, prüft oder darstellt, etwa in Editoren für Knotengraphen oder in Hilfsfunktionen. Damit lässt sich vorher prüfen, ob ein Eingangsindex für source.connect(ziel, ausgang, eingang) gültig ist. Auch ob ein Knoten überhaupt ein Ziel sein kann, lässt sich so feststellen.

Rückgabewert

Typ

number

Beschreibung

Eine nicht negative ganze Zahl (unsigned long): die Anzahl der Eingänge des Knotens.

Beispiele

Eingänge verschiedener Knotentypen abfragen

const ctx = new AudioContext();

const osc = ctx.createOscillator();
const gain = ctx.createGain();
const merger = ctx.createChannelMerger(4);

console.log('Oscillator:', osc.numberOfInputs);
console.log('Gain:', gain.numberOfInputs);
console.log('Merger:', merger.numberOfInputs);
console.log('Destination:', ctx.destination.numberOfInputs);

Oscillator: 0 Gain: 1 Merger: 4 Destination: 1

Eingangsindex vor connect() prüfen

const ctx = new OfflineAudioContext(2, 44100, 44100);
const links = ctx.createOscillator();
const rechts = ctx.createOscillator();
const merger = ctx.createChannelMerger(2);

const sichereVerbindung = (quelle, ziel, eingang = 0) => {
  if (ziel.numberOfInputs === 0) {
    throw new Error(`${ziel.constructor.name} hat keine Eingänge`);
  }
  if (eingang >= ziel.numberOfInputs) {
    throw new RangeError(`Eingang ${eingang} existiert nicht (max. ${ziel.numberOfInputs - 1})`);
  }
  quelle.connect(ziel, 0, eingang);
};

sichereVerbindung(links, merger, 0);
sichereVerbindung(rechts, merger, 1);

try {
  sichereVerbindung(links, merger, 2);
} catch (e) {
  console.log(e.message);
}

Eingang 2 existiert nicht (max. 1)

Knoten im Audiographen beschreiben

const ctx = new AudioContext();

const beschreibe = (node) => ({
  typ: node.constructor.name,
  eingaenge: node.numberOfInputs,
  ausgaenge: node.numberOfOutputs,
  rolle: node.numberOfInputs === 0 ? 'Quelle'
       : node.numberOfOutputs === 0 ? 'Ziel'
       : 'Verarbeitung'
});

const knoten = [
  ctx.createBufferSource(),
  ctx.createBiquadFilter(),
  ctx.createChannelSplitter(2),
  ctx.destination
];

console.table(knoten.map(beschreibe));

AudioBufferSourceNode | 0 | 1 | Quelle BiquadFilterNode | 1 | 1 | Verarbeitung ChannelSplitterNode | 1 | 2 | Verarbeitung AudioDestinationNode | 1 | 0 | Ziel

// Wichtig · Fallstricke

Eingänge sind keine Kanäle: Ein einzelner Eingang kann mehrere Kanäle führen (z. B. Stereo). Wie viele Kanäle es sind, bestimmen channelCount und channelCountMode. numberOfInputs zählt nur die Anschlusspunkte.
Nur lesbar: Eine Zuweisung wie node.numberOfInputs = 2 wird still ignoriert, im Strict Mode wirft sie einen TypeError. Die Anzahl muss beim Erzeugen festgelegt werden, etwa mit createChannelMerger(n) oder new AudioWorkletNode(ctx, name, { numberOfInputs: n }).
Ist beim Aufruf von connect(ziel, ausgang, eingang) der Eingangsindex nicht kleiner als ziel.numberOfInputs, wirft der Browser einen IndexSizeError (DOMException).
An einen Eingang lassen sich mehrere Quellen anschließen. Ihre Signale werden dann automatisch addiert. Für einfaches Mischen braucht man also keine zusätzlichen Eingänge.
Die Eigenschaft funktioniert in allen modernen Browsern. Sehr alte WebKit-Versionen kannten nur webkitAudioContext mit Präfix.

Siehe auch

AudioNode.numberOfOutputs AudioNode.connect() AudioNode.channelCount AudioNode ChannelMergerNode AudioWorkletNode AudioNode.context