Skip to content

Nodes

Multichannel nodes

When passing a value to audio-rate input of a Node, the signal is by default monophonic (single-channel). For example, SquareOscillator(440) generates a 1-channel output.

It is possible to generate multi-channel output by passing an array of values in the place of a constant. For example, SquareOscillator([440, 880]) generates stereo output with a different frequency in the L and R channels.

There is no limit to the number of channels that can be generated by a node. For example, SquareOscillator(list(100 + 50 * n for n in range(100))) will create a node with 100-channel output, each with its own frequency. 

>>> sq = SquareOscillator([100 + 50 * n for n in range(100)])
>>> print(sq.num_output_channels)
100

Automatic upmixing

There are generally multiple inputs connected to a node, which may themselves have differing number of channels. For example, SquareOscillator(frequency=[100, 200, 300, 400, 500], width=0.7) has a 5-channel input and a 1-channel input. In cases like this, the output of the nodes with fewer channels is upmixed to match the higher-channel inputs.

Upmixing here means simply duplicating the output until it reaches the desired number of channels. In the above case, the width input will be upmixed to generate 5 channels, all containing 0.7.

If width were a stereo input with L and R channels, the output would be tiled, alternating between the channels. Each frame of stereo input would then be upmixed to contain [L, R, L, R, L], where L and R are the samples corresponding to the L and R channels.

The key rule is that, for nodes that support upmixing, the output signal has as many channels as the input signal with the highest channel count.

This process percolates through the signal chain. For example:

SquareOscillator(frequency=SineLFO([1, 3, 5], min=440, max=880),
                 width=SawLFO([0.5, 0.6], min=0.25, max=0.75))
  • The min and max inputs of the frequency LFO would be upmixed to 3 channels each
  • The min and max inputs of the width LFO would be upmixed to 2 channels each
  • Then, the output of the width node would be upmixed from 2 to 3 channels

Nodes with fixed input/output channels

Some nodes have immutable numbers of input/output channels. For example:

  • StereoPanner has 1 input channel and 2 output channels
  • StereoBalance has 2 input channels and 2 output channels
  • ChannelMixer has an arbitrary number of input channels, but a fixed, user-specified number of output channels

Even Nodes that do not have an obvious input (e.g. BufferPlayer) have input channels, for modulation inputs (for example, modulating the rate of the buffer).

When two nodes are connected together with incompatible channel counts (for example, connecting a StereoBalance into a StereoMixer), an InvalidChannelCountException will be raised.

The Channel* node classes

There are a number of Node subclasses dedicated to channel handling.

  • ChannelArray: Concatenates the channels of multiple nodes, so that calling ChannelMix with nodes of N and M channels will produce an output of N + M channels.
  • ChannelMixer: Reduces or expands the number of channels by evenly spreading the audio across the output channels.
  • ChannelSelect: Selects sub-channels of the input, either individually or by group.

Querying channel subsets with the index operator

Single channels of a multi-channel node can be accessed using the index [] operator. For example:

square = SquareOscillator([440, 441, 442, 443])
output = square[0]
# output now contains a mono output, with a frequency of 440Hz.

Slice syntax can be used to query multiple subchannels:

square = SquareOscillator([440, 441, 442, 880])
output = square[0:2]
# now contains a two-channel square wave

→ Next: Status and properties

Last update: 2023-01-03
Created: 2022-04-01