The Convolution command performs a one-dimensional convolution over audio data using a convolution kernel (also known as a convolution mask), and returns a new audio object giving the result of this operation.

The audArray parameter specifies the audio data on which to perform the convolution, and must be a dense rectangular Array, Vector, or Matrix with datatype=float[8], and one or two dimensions.

The kernel parameter specifies the convolution kernel in the form of an N-element column Vector or Array, or an Nx1 Matrix or Array of numeric values.

The Convolution operation consists of "sliding" the kernel over each channel of the input data, moving it by one sample each time, computing a new sample value for the output channel.

When the audio data has more than one channel, the kernel can be specified as an NxM Matrix or Array, where M is equal to the number of channels. Each channel of the mask is then used for the corresponding channel of the audio data.

The samples covered by the kernel are multiplied by the corresponding entries (weights) in the kernel, and summed up. Then, the sum is divided by the sum of the weights (or 1 if the weights sum to zero), and the sample corresponding to the center of the kernel is given that value in the output audio. The input audio is not modified.

Options

For an N-element kernel, there will be $\frac{N}{2}-\frac{1}{2}$ samples at the beginning and end of the audio data that do not have the required $N-1$ neighbors.

The shape=shapeMode option controls which samples of the convolution are to be part of the output:

If shape=valid is specified, those samples with too few neighbors are omitted from the convolution, and thus the output data will be smaller than the input data (by one less than the length of the kernel).

If shape=same is specified, the output data will be the same size as the input data. The treatment of the edge samples is then controlled by the edges=edgeMode option described below.

If shape=full is specified (the default), a full mathematical convolution is performed, in which any position of the kernel that overlaps the data will produce an output sample. Thus, the output data will be larger than the input (by one less than the length of the kernel). When part of the kernel protrudes past the edge of the input data, the values used for samples outside the data are controlled by the exterior=exteriorMode option described below.

The edges=edgeMode option controls what is to be done with the edge samples when shape=same.

If edges=leave is specified, the edge samples are left unmodified (copied from the input into the output data verbatim). Depending on the convolution kernel, there will be an audible difference between these and the processed samples. For example, if the kernel implements a low pass filter, the edge samples will still retain the higher frequency components.

The setting edges=compute (the default) causes the edge samples to be computed, in a manner controlled by the exterior=exteriorMode option described below.

A specific sample value can be specified for the edge samples by giving a numeric value for edgeMode (for example, edgeMode=0.5). In that case, the edge samples get that value (for multi-channel audio data, each channel receives the value).

The exterior=exteriorMode option controls how samples exterior to the data are interpreted when shape=same and edges=compute, or when shape=full.

Specifying exterior=ignore tells Convolution to ignore the exterior samples when part of the kernel falls outside the data. Only the samples within the data are multiplied by the corresponding kernel entries. The result is then reweighted by the ratio of total kernel weight to the sum of the kernel entries falling within the data. This avoids fade-in and fade-out at the extremes of the result.

A specific sample value can be specified for the exterior samples by giving a numeric value for exteriorMode (for example, exterior=0.5). This results in a fade-from/to-DC effect at the edges of the result (preceded/followed by a click if the value is non-zero).

The default if the exterior option is not specified is exterior=0.

The weight=n option overrides the weight by which the weighted sum of samples is multiplied. By default, it is multiplied by the inverse of the sum of the weights of the kernel entries, or by 1 if the kernel entries sum to zero. Specifying weight=n causes the sum to be multiplied by n instead.

Specifying weight=none causes the weighted sum to be used as-is. This corresponds to the mathematical definition of convolution.

A convolution corresponding to the mathematical definition can be obtained by specifying the options shape=full, exterior=0, and weight=none. These are the defaults.

$\mathrm{audiofile}≔\mathrm{cat}\left(\mathrm{kernelopts}\left(\mathrm{datadir}\right)\,''/audio/stereo.wav''\right)\:$

$\mathrm{with}\left(\mathrm{AudioTools}\right)\:$

$\mathrm{aud}≔\mathrm{Read}\left(\mathrm{audiofile}\right)$

$\mathrm{aud}≔\left[\begin{array}{cc}''Sample\; Rate''& 22050\\ ''File\; Format''& \mathrm{PCM}\\ ''File\; Bit\; Depth''& 8\\ ''Channels''& 2\\ ''Samples/Channel''& 19962\\ ''Duration''& 0.90531s\end{array}\right]$

$\mathrm{tinny}≔\mathrm{Convolution}\left(\mathrm{aud}\,⟨-1\,-1\,-1\,6\,-1\,-1\,1⟩\right)$

$\mathrm{tinny}≔\left[\begin{array}{cc}''Sample\; Rate''& 22050\\ ''File\; Format''& \mathrm{PCM}\\ ''File\; Bit\; Depth''& 8\\ ''Channels''& 2\\ ''Samples/Channel''& 19968\\ ''Duration''& 0.90558s\end{array}\right]$

The AudioTools[Convolution] command was updated in Maple 2020.