Audio stream pipelines and processing.
Streams are represented as sequences of buffers, each of which contains zero or more samples.
Data is produced from
Sources on demand and fed into a chain of zero or more
Sinks until it
reaches the end of the pipeline. The pipeline always operates in a "pull" mode, where
yield buffers only as fast as requested by a
Valid sample formats are bounded by the
Sample trait. In general a sample will be a primitive
numeric value, though this need not be true. Sample values must always be copyable and sendable
between threads, and most non-trivial stream transformations require that a number of
arithmatic operations be available.
In all formats, the nominal range is between -1 and 1, inclusive. In integer formats, the
logical interpretation is as a fixed-point value with the radix point left-aligned. For
Sample is best considered as a number in range -128/128 through 127/128 by
steps of 1/128.
A format is considered soft-clipped if it is capable of representing values outside the nominal range. Notably, this applies to floating-point formats where numbers outside the nominal range can be represented (but perhaps with some loss of precision). The converse of a hard-clipped format is soft-clipped.
From least general to most, there are three classes of sources, each of which yield different
"flavors" of output.
MonoSources simply provide a stream of samples of a statically-known format. This stream
is strictly linear and can only mark end-of-stream.
Source is the general static element, providing blocks of a statically-known sample
format. It may pass an arbitrary number of channels at a time and specifies the stream's
DynamicSource has no properties known at compile-time. Sample format and rate are
specified on a per-buffer basis, requiring reinterpretation of the data before use.
A less-general source can always be adapted into a more-general source. A
Ogg vorbis decoder.
Adjust the amplitude of the input stream by a constant factor.
Make a copy of a specified channel.
Adapts a normal
The result of pulling from a
A source of uncontrolled samples.
Type bound for sample formats.
A source of samples with defined sample rate.