new ChannelMergerNode() — Methode · JavaScript-Referenz

Signatur

new ChannelMergerNode(context, options)

Beschreibung

Der Konstruktor new ChannelMergerNode() erzeugt einen Knoten der Web Audio API, der mehrere Eingänge zu einem einzigen Ausgang mit mehreren Kanälen zusammenfasst. Jeder Eingang wird dabei auf einen Kanal des Ausgangs abgebildet: Eingang 0 → Kanal 0 (links), Eingang 1 → Kanal 1 (rechts) usw. Hat ein Eingang selbst mehrere Kanäle, wird er vorher auf Mono heruntergemischt.

Man benutzt den Knoten typischerweise zusammen mit einem ChannelSplitterNode: Zuerst trennt man ein Stereosignal in einzelne Kanäle auf, bearbeitet diese getrennt (z. B. eigene Lautstärke, Verzögerung oder Filter pro Kanal) und führt sie anschließend mit dem Merger wieder zusammen. Ebenso lassen sich zwei unabhängige Mono-Quellen gezielt auf den linken und rechten Kanal legen.

Der Konstruktor ist die moderne Alternative zur Fabrikmethode BaseAudioContext.createChannelMerger(). Vorteil: Optionen können direkt als Objekt übergeben werden. Die Eigenschaften channelCount (immer 1) und channelCountMode (immer "explicit") sind bei diesem Knoten fest vorgegeben und dürfen nicht geändert werden.

Parameter

Name	Typ	Default	Beschreibung
$context Pflicht	BaseAudioContext		Der `AudioContext` oder `OfflineAudioContext`, dem der Knoten zugeordnet wird.
$options	Object	{}	Optionales Konfigurationsobjekt mit folgenden Eigenschaften: `numberOfInputs` (`number`, Standard `6`): Anzahl der Eingänge und damit Kanäle des Ausgangs, zulässig 1–32. `channelCount`: muss `1` sein, sonst `InvalidStateError`. `channelCountMode`: muss `"explicit"` sein, sonst `InvalidStateError`. `channelInterpretation` (`"speakers"` \| `"discrete"`, Standard `"speakers"`).

Rückgabewert

Typ

ChannelMergerNode

Beschreibung

Ein neues ChannelMergerNode-Objekt mit numberOfInputs Eingängen und einem Ausgang mit entsprechend vielen Kanälen.

Beispiele

Einfache Instanziierung eines Stereo-Mergers

const ctx = new AudioContext();
const merger = new ChannelMergerNode(ctx, { numberOfInputs: 2 });

console.log(merger.numberOfInputs);   // Anzahl Eingänge
console.log(merger.numberOfOutputs);  // immer 1
console.log(merger.channelCountMode); // fest vorgegeben

2 1 explicit

Zwei Oszillatoren auf linken und rechten Kanal legen

const ctx = new AudioContext();
const merger = new ChannelMergerNode(ctx, { numberOfInputs: 2 });

const links = new OscillatorNode(ctx, { frequency: 440 });
const rechts = new OscillatorNode(ctx, { frequency: 660 });

// connect(ziel, ausgangIndex, eingangIndex)
links.connect(merger, 0, 0);  // → linker Kanal
rechts.connect(merger, 0, 1); // → rechter Kanal
merger.connect(ctx.destination);

document.querySelector('#start').addEventListener('click', async () => {
  await ctx.resume();
  links.start();
  rechts.start();
  links.stop(ctx.currentTime + 2);
  rechts.stop(ctx.currentTime + 2);
});

Kanäle tauschen mit Splitter und Merger

const ctx = new AudioContext();
const audio = document.querySelector('audio');
const source = new MediaElementAudioSourceNode(ctx, { mediaElement: audio });

const splitter = new ChannelSplitterNode(ctx, { numberOfOutputs: 2 });
const merger = new ChannelMergerNode(ctx, { numberOfInputs: 2 });

source.connect(splitter);
// Links und rechts vertauschen
splitter.connect(merger, 0, 1);
splitter.connect(merger, 1, 0);
merger.connect(ctx.destination);

audio.addEventListener('play', () => ctx.resume());

Fehler bei ungültigen Optionen abfangen

const ctx = new OfflineAudioContext(2, 44100, 44100);

try {
  new ChannelMergerNode(ctx, { numberOfInputs: 2, channelCount: 2 });
} catch (err) {
  console.log(err.name);
}

try {
  new ChannelMergerNode(ctx, { numberOfInputs: 40 });
} catch (err) {
  console.log(err.name);
}

InvalidStateError IndexSizeError

// Wichtig · Fallstricke

Kanal-Zuordnung: Beim connect() unbedingt den dritten Parameter (Eingangsindex) angeben – ohne ihn landet alles auf Eingang 0 und damit nur im linken Kanal.
Downmix: Jeder Eingang wird auf Mono heruntergemischt. Wer ein Stereosignal einspeist, verliert dessen Stereo-Information; vorher mit ChannelSplitterNode auftrennen.
Feste Werte: channelCount ≠ 1 oder channelCountMode ≠ "explicit" führen zu einem InvalidStateError; numberOfInputs außerhalb 1–32 zu einem IndexSizeError.
Nicht verbundene Eingänge erzeugen Stille im jeweiligen Kanal – der Ausgang hat trotzdem numberOfInputs Kanäle.
Kompatibilität: Der Konstruktor wird von allen aktuellen Browsern unterstützt; sehr alte Safari-Versionen (vor 14.1) kennen nur createChannelMerger() bzw. webkitAudioContext.
Autoplay-Richtlinie: Ein AudioContext startet oft im Zustand "suspended" und muss nach einer Nutzerinteraktion per resume() aktiviert werden.

Siehe auch

ChannelMergerNode ChannelSplitterNode BaseAudioContext.createChannelMerger() AudioNode.connect() AudioContext StereoPannerNode new ChannelSplitterNode()