AudioNode.channelCountMode — Eigenschaft · JavaScript-Referenz

Signatur

AudioNode.channelCountMode

Beschreibung

Die Eigenschaft channelCountMode ist lesbar und schreibbar. Sie legt fest, wie ein Audioknoten die berechnete Kanalzahl (computedNumberOfChannels) für seine Eingänge ermittelt. Diese Zahl bestimmt, ob ankommende Signale vor der Verarbeitung hochgemischt (Up-Mixing) oder heruntergemischt (Down-Mixing) werden. Zusammen mit channelCount und channelInterpretation bildet sie das Kanal-Mixing-Modell der Web Audio API.

"max": Die Kanalzahl entspricht der höchsten Kanalzahl aller Verbindungen am Eingang. channelCount wird ignoriert. Das ist die Voreinstellung der meisten Knoten, z. B. GainNode, BiquadFilterNode und AnalyserNode.
"clamped-max": Wie "max", nach oben aber durch channelCount begrenzt. Voreinstellung u. a. bei PannerNode, StereoPannerNode, ConvolverNode und DynamicsCompressorNode.
"explicit": Die Kanalzahl entspricht genau channelCount, egal wie viele Kanäle ankommen. Voreinstellung u. a. bei ChannelSplitterNode, ChannelMergerNode und AudioDestinationNode.

Meist ändern Sie den Wert, wenn ein Signal in einer festen Kanalkonfiguration verarbeitet werden soll. Beispiele: ein Mehrkanal-Signal gezielt auf Mono heruntermischen, bevor es analysiert wird, oder die Ausgabe eines Effekts auf Stereo begrenzen.

Parameter

Name	Typ	Default	Beschreibung
$value	"max" \| "clamped-max" \| "explicit"	je nach Knotentyp, meist "max"	Neuer Modus beim Schreiben der Eigenschaft. Ungültige Zeichenketten werden laut WebIDL stillschweigend ignoriert; der alte Wert bleibt erhalten.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Modus als Zeichenkette: "max", "clamped-max" oder "explicit".

Beispiele

Standardwerte verschiedener Knoten auslesen

// OfflineAudioContext braucht keine Nutzerinteraktion
const ctx = new OfflineAudioContext(2, 44100, 44100);

const nodes = {
  gain: ctx.createGain(),
  panner: ctx.createPanner(),
  splitter: ctx.createChannelSplitter(2),
  destination: ctx.destination
};

for (const [name, node] of Object.entries(nodes)) {
  console.log(`${name}: ${node.channelCountMode} (channelCount=${node.channelCount})`);
}

gain: max (channelCount=2) panner: clamped-max (channelCount=2) splitter: explicit (channelCount=1) destination: explicit (channelCount=2)

Stereo-Signal vor der Analyse auf Mono heruntermischen

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

const osc = ctx.createOscillator();
const monoMix = ctx.createGain();

// Genau 1 Kanal erzwingen, egal was ankommt
monoMix.channelCount = 1;
monoMix.channelCountMode = 'explicit';
monoMix.channelInterpretation = 'speakers'; // L+R werden gemittelt

const analyser = ctx.createAnalyser();
osc.connect(monoMix).connect(analyser);
analyser.connect(ctx.destination);

console.log(monoMix.channelCountMode, monoMix.channelCount);

explicit 1

Unzulässige Werte und Fehlerbehandlung

const ctx = new OfflineAudioContext(2, 44100, 44100);
const panner = ctx.createStereoPanner();

// Ungültiger String: wird still ignoriert
panner.channelCountMode = 'stereo';
console.log(panner.channelCountMode);

// "max" ist bei StereoPannerNode nicht erlaubt
try {
  panner.channelCountMode = 'max';
} catch (err) {
  console.log(err.name);
}

// Beim ChannelMergerNode ist der Modus fest
const merger = ctx.createChannelMerger(2);
try {
  merger.channelCountMode = 'max';
} catch (err) {
  console.log(err.name);
}

clamped-max NotSupportedError InvalidStateError

// Wichtig · Fallstricke

Einschränkungen je Knotentyp: PannerNode, StereoPannerNode, ConvolverNode und DynamicsCompressorNode erlauben kein "max" und werfen dann einen NotSupportedError. ChannelSplitterNode, ChannelMergerNode und ScriptProcessorNode haben einen festen Modus "explicit"; jede Änderung wirft einen InvalidStateError.
Ungültige Werte: Ein Tippfehler wie "clamped_max" erzeugt keinen Fehler, sondern wird einfach ignoriert. Prüfen Sie den Wert deshalb nach dem Setzen, wenn es darauf ankommt.
Zusammenspiel: channelCount wirkt bei "max" gar nicht. Wer eine feste Kanalzahl will, muss "explicit" setzen. Wie gemischt wird (Lautsprecher-Regeln oder diskrete Zuordnung), bestimmt channelInterpretation.
Die Eigenschaft wirkt nur auf die Eingänge eines Knotens. Knoten ohne Eingang (z. B. OscillatorNode, AudioBufferSourceNode) werden davon nicht beeinflusst.
Werte lassen sich auch direkt im Konstruktor übergeben, z. B. new GainNode(ctx, { channelCountMode: 'explicit', channelCount: 1 }).
Kompatibilität: Die Eigenschaft wird von allen aktuellen Browsern unterstützt (Chrome, Firefox, Safari, Edge). In Node.js gibt es sie nur über Zusatzbibliotheken wie node-web-audio-api.

Siehe auch

AudioNode AudioNode.channelCount AudioNode.channelInterpretation AudioNode.prototype.connect() ChannelMergerNode ChannelSplitterNode GainNode