AudioResample

std.AudioResample(anode clip[, int samplerate, int sampletype, int bits, int[] channels, string dither_type="triangular", bint normalize, bint overflow_error=False])

Converts audio between sample rates, channel layouts and sample formats. Every argument defaults to the corresponding property of the input clip, so only the parts that are explicitly specified are changed.

Integer samples fill the whole width of the container they are stored in, with the significant bits left aligned and any spare low bits left as zero padding. A 24 bit sample therefore occupies the top 24 bits of a 32 bit value, which is the same layout the wave writers and the source filters use. Float samples use the nominal -1.0 to 1.0 range, so a full scale negative sample corresponds to float -1.0 at every bit depth. Converting to a wider integer format or to float is exact and reversible.

Note that only pure format conversions are exact to the last bit. Sample rate conversion and channel mixing work on 32 bit floating point values internally, so anything that changes the rate or the layout carries about 24 significant bits through the conversion. That resolves more than any real signal chain, and 16 and 24 bit material passes through it exactly, but 32 bit integer input doesn’t survive those operations bit exactly even when the output format could represent it.

clip:

Input clip.

samplerate:

Output sample rate.

The conversion uses a Kaiser windowed sinc filter with the passband reaching 91% of the lower of the two Nyquist frequencies, which for 44.1 kHz output means everything up to about 20 kHz is preserved flat. Measured stopband attenuation is better than 110 dB and total harmonic distortion plus noise is below -115 dB.

The output length is the input length scaled by the rate ratio and rounded up. Samples before the start and after the end of the clip are treated as silence, so the very first and last output samples fade in and out over the length of the filter rather than wrapping around.

The ratio between the two rates is reduced to an exact fraction and one filter phase is generated per step of that fraction, so all the common rates convert cheaply. Rates whose ratio doesn’t reduce, such as 48000 to 96001, need an impractically large filter and are rejected with an error.

sampletype:

Output sample type, 0 for integer and 1 for float. When set to float and bits isn’t specified the output is 32 bit float.

bits:

Output bits per sample. Integer output accepts 16 to 32 bits and float output only accepts 32 bits.

channels:

Output channel layout, specified as a list of channel constants the same way as in BlankAudio. The order the channels are listed in doesn’t matter, a layout is a set.

The mix matrix is derived from the two layouts rather than looked up per layout pair, so any combination is handled. Channels that exist in both layouts pass straight through untouched, and each input channel that has nowhere to go is folded into the channels that do exist:

  • A front centre with no destination is folded into front left and right at -3 dB each, and a front left/right pair with no destination is folded onto the centre the same way, which is how stereo collapses to mono.

  • Surrounds are folded into the fronts at -3 dB. Side and back channels name the same position when a layout carries only one of the two, so a layout using side surrounds converts to one using back surrounds without any loss.

  • A back centre folds into the back pair if there is one, the side pair otherwise, and the fronts as a last resort.

  • Elevated and auxiliary positions collapse onto the channel below or beside them and then follow that channel’s own rule.

  • The LFE is discarded unless the output layout has an LFE of its own.

The -3 dB fold levels are the ones ITU-R BS.775 specifies and that ATSC A/52 carries by default, so the standard 5.1 to stereo downmix comes out as L' = L + 0.707*C + 0.707*Ls.

Output channels that no input channel feeds contain digital silence and are never dithered. Upmixing spreads what is there but doesn’t invent surround content, so converting stereo to 5.1 gives you the original two channels and four silent ones.

Matrix encoded output such as Dolby Surround Lt/Rt isn’t supported, since folding the surrounds in with a phase shift needs a filter rather than a matrix.

dither_type:

Dither applied when the destination has less precision than the source, which means when converting from float to integer or to a narrower integer format. Widening a format or converting to float is exact and never dithered regardless of this setting. Sample rate conversion and channel mixing always work in floating point internally, so any integer output is dithered when either of them is active. The following methods are available:

none

Plain rounding. Produces quantization distortion that is correlated with the signal.

rectangular

Uniformly distributed noise spanning one quantization step. Decorrelates the error from the signal but not the error power.

triangular

Triangularly distributed noise spanning two quantization steps, the default. Slightly noisier than rectangular but decorrelates both the error and its power from the signal, which is normally what you want.

The dither noise is derived from the position of each sample rather than from a running random number generator, and the resampler likewise computes the filter phase for each output sample directly from its position instead of carrying state between samples. The output of a given frame is therefore always identical no matter in which order frames are requested, which keeps output reproducible when seeking. Note that dithering a signal that is already at full scale can push samples past the last representable value and cause clipping.

normalize:

Whether to scale the mix matrix down so that no output channel can clip. The worst case gain of an output channel is the sum of the weights feeding it, which for the standard 5.1 to stereo downmix is about 2.41, so normalizing costs roughly 7.6 dB of level in exchange for never clipping. The whole matrix is scaled by the same factor rather than each row on its own, which keeps the balance between the output channels intact.

Defaults to on for integer output, where clipping is unrecoverable, and off for float output, which has the headroom to carry the plain BS.775 coefficients. Only has an effect when the channel layout changes.

overflow_error:

Will stop processing with an error if clipping is detected if overflow_error is set. If it’s false a warning will be printed for the first audio block with clipping.

To convert to 44.1 kHz 16 bit integer, the usual cd delivery format:

AudioResample(clip=clip, samplerate=44100, sampletype=0, bits=16)

To downmix 5.1 to stereo:

AudioResample(clip=clip, channels=[vs.FRONT_LEFT, vs.FRONT_RIGHT])

To convert a float clip to 16 bit integer with the default dither:

AudioResample(clip=clip, sampletype=0, bits=16)

To convert to 32 bit float:

AudioResample(clip=clip, sampletype=1)

To reduce an integer clip to 16 bits without adding any dither noise:

AudioResample(clip=clip, bits=16, dither_type="none")