AudioSupport - pierreguillot/Camomile GitHub Wiki

Audio

The use of audio in your plugin is simple, the only thing required is to define the supported configuration of audio channels. However, many options and properties can be implemented and used to adapt the audio processing to the audio context and to offer more flexibility.

Important: The plugin should not be MIDI only. Ensure that the entry midionly is not defined or false (midionly false).

Main Audio Bus

An audio bus is a channels configuration and corresponds to a number of input audio channels associated to a number of output audio channels. To support an audio bus, add the entry bus followed by the number of input audio channels and the number of output audio channels in the properties file of the plugin.

For example, adding the entry bus 2 2 enables the support for an audio channels configuration with two inputs associated to two outputs. In the patch, use the objects [adc~] and [dac~]with the standard syntax of arguments to receive and to send the audio signals.

When no input channel is necessary, for a synthesizer for example, using the entry bus 0 2 enables the support for an audio channels configuration with only two outputs. Or when only an input channel is necessary, for a volume unit meter for example, using the entry bus 1 0 enables the support for an audio channels configuration with only one output.

In theory, a plugin accepts any number of input audio channels and any number of output audio channels, but in practice, most of the digital audio workstations highly restrict the possible configurations. Refer to the documentation of your digital audio workstation to see what are the available configurations.

Sample Rate

The digital audio workstation controls the sample rate of the audio chain. When the sample rate changes, the plugin stops the audio processing, changes the internal sample rate of Pd and restarts the audio processing. If the processing requires adaptation to the sample rate, for example when using FFT, in the patch, use the audio start notification to retrieve the running sample rate in order to adapt the audio processing.

Block Size

The digital audio workstation controls the size of the audio block, the number of samples per audio block, of the audio chain. Although the size of the audio block can be set in the preferences of the digital audio workstation, the number of samples per audio block is not guaranteed and may vary with each block. In addition, Pd internally requires that the block size be 64 samples but the plugin manages the proper operation of both systems - using a default latency of 64 samples but which is compensated by the digital audio workstation. In the main patch, the size of the audio block will always be 64 samples but it is still possible to use a larger or smaller block size in the abstractions and sub-patches using the object [block ~].

Latency

Audio processing may involve latency, for example when using FFT, but digital audio workstations offer a system to compensate for this artifact. As this latency can change for many reason, for example when the sample rate has changed, since version 1.0.4, the plugin offers a dynamic system for notifying the digital audio workstation. Thus to warn the digital audio workstation that the latency involved in the audio processing has changed, send the message [audio latency $1( with $1 replaced by the latency in samples to the plugin via the object [send camomile].

Tail Length

Audio processing may also involve an audio tail which should be taken into account by the digital audio workstations, for example when using delay lines. To define the audio tail length the plugin, use the entry taillength followed by the length in seconds in the properties file of the plugin. For example, if the tail length is 12.5 seconds, then add taillength 12.5.

Important: Digital audio workstations do not support dynamic change of tail length. So always prefer a very long tail length that will suit all your needs.

Side-Chain

This feature is still experimental and the operation differs between plugin formats. Maybe the approach will change in the future to ensure more consistency.

Some digital audio workstations also support an extra audio bus for side-chain processing. A side-chain corresponds to one or more extra channels that can be fed by an external input like another track. For example, a compressor with a side-chain input controls gain from main input to output based on the level of the signal at the side-chain input. To support an extra audio bus for side-chain processing, add a second entry bus followed by the number of input audio channels and the number of output audio channels required by the side-chain in the properties file of the plugin.

For example, the support for the main bus defined by two input channels with two output channels and a side-chain defined by one input channel with zero output channel required to add:

bus 2 2;
bus 1 0;

In the patch, use the objects [adc~] and [dac~]with the standard syntax of arguments to receive and to send the audio signals. The channels' numbers of the side-chain follow the channels' numbers of the main.

In theory, a side-chain can correspond to any bus, but in practice, as for the main audio bus, the available configurations are restricted by the digital audio workstations. And keep in mind that even if side-chain processing is a common approach, all the digital audio workstations does not support this feature.

Multichannel