Mixing and routing
What the modules that combine, split and steer streams take and return.
audiomixer.Mixer plays several sources at once; audioroute fans a stream
out, re-points a wire and scales stereo width. To change what plays without
rewiring, see
Change what plays without a click.
audiomixer
Generated from audiomixer.pyi; the file reads on its own.
Mix several audio sources into one stream.
Mixer is an audio source with a fixed number of voices. Each voice plays
one source at that source’s own rate, with its own level and panning, and the
mixer adds the voices up into one stream of the format you gave it. Hand the
mixer to an output, then Mixer.play sources into its voices. It follows
CircuitPython’s audiomixer, so code written for a board runs unchanged,
and adds Mixer.level_ramp.
Nothing in the module makes a voice on its own: you reach one through
Mixer.voice.
- class audiomixer.Mixer(*, voice_count=2, buffer_size=1024, channel_count=2, bits_per_sample=16, samples_signed=True, sample_rate=8000)[source]
Bases:
objectAn audio source that mixes several others.
Every argument is a keyword. The format you give is the format of the stream the mixer produces, and every source played into it must have the same channel count, bit depth and signedness; it may have any sample rate, and plays at its own.
- Parameters:
voice_count – How many voices, 1 to 255. The default is 2.
buffer_size – Bytes in each of the mixer’s two block buffers. The default is 1024.
channel_count – 1 or 2.
bits_per_sample – 8 or 16.
samples_signed – Whether samples are signed. The default is True.
sample_rate – The mixer’s rate in Hz, 1 or more. The default is 8000.
- Raises:
ValueError – An argument is out of range.
- property playing
Whether any voice is playing.
- property voice
The voices, as a tuple of
voice_countobjects, somixer.voice[0].level = 0.5sets the first one’s level.
- level_ramp
Frames a voice’s level or pan move takes, 0 to 16777216 (2 ** 24). At 0, the default, a move behaves as it does in CircuitPython. Above 0, a move walks from the old value to the new one in a straight line over that many frames, so turning a level in one call does not click. Set it to the number of frames in 20 ms (960 at 48 kHz) for the usual crossfade.
A voice’s first level lands at once; the walk starts with the next move. A move made during a walk starts a new walk from where the level stands. A level driven by a
synthio.LFOstarts a walk each time it is read, so it follows the LFO a walk behind.
- sample_rate
The mixer’s rate in Hz. Writable, to 1 or more.
- property bits_per_sample
Size of one sample in bits: 8 or 16.
- property channel_count
Number of channels: 1 or 2.
- play(sample, *, voice=0, loop=False)[source]
Play a source on one voice, from its start.
- Parameters:
sample – An audio source in the mixer’s format.
voice – The voice, 0 up to
voice_count - 1.loop – Start the source again whenever it ends.
- Returns:
The mixer.
- Raises:
ValueError –
voiceis out of range, or the source’s format does not match the mixer’s.
- stop_voice(voice=0)[source]
Stop one voice at once.
- Raises:
ValueError –
voiceis out of range.
- deinit()[source]
Free the mixer. Later calls other than
deinitraiseValueError.
Mixer voices
Mixer.voice returns these. The module has no public name for the type, so it is listed here under the private name the stub gives it.
- class audiomixer._MixerVoice[source]
Bases:
objectOne voice of a
Mixer.Get voices from
Mixer.voice; the module has no name for the type and you cannot make one on its own.- property playing
Whether the voice is playing a source. A source that has ended, or a voice that was stopped, is not playing.
- level
0.0 is silent, 1.0 is as recorded. A number, or a
synthio.LFOorsynthio.Maththat moves it. A new voice starts at 1.0.With
Mixer.level_rampat 0 a change lands at the voice’s next zero crossing, so it cannot step a waveform mid-cycle. With a ramp set it walks to the new level over that many frames.- Type:
How loud the voice is
- panning
-1.0 is all left, 1.0 is all right, 0.0 is the centre and the default. A number, or a
synthio.LFOorsynthio.Math. A mono mixer ignores it. A change follows the rules oflevel.- Type:
Where the voice sits between the channels of a stereo mixer
- loop
Whether the voice starts its source again when it ends.
- play(sample, *, loop=False)[source]
Play a source on this voice, from its start, replacing what the voice was playing.
- Parameters:
sample – An audio source. Its channel count, bit depth and signedness must match the mixer’s.
loop – Start the source again whenever it ends.
- Raises:
ValueError – The source’s format does not match the mixer’s.
audioroute
Generated from audioroute.pyi; the file reads on its own.
Route audio: fan one stream out, scale stereo width, re-point a wire.
Splitter reads one source and hands out up to four SplitterTap streams
that each play the same audio, so a stream can feed parallel branches.
MidSide scales the difference between the left and right channels. Port
is a wire whose source can be changed while it plays.
All of them are audio samples (a Splitter itself is not; its taps are), so
they play wherever an audiocore.RawSample does.
- class audioroute.Splitter(source, taps=2)[source]
Bases:
objectFans one source out to parallel branches.
The splitter reads the source once and keeps the audio in a ring of 8192 frames, so the taps may be read at different paces, but a tap that falls further behind than the ring holds loses audio. Every tap exists from the start, because audio nobody has read yet is dropped.
- Parameters:
source – The stream to read, mono or stereo.
taps – How many taps to make, 1 to 4.
- Raises:
ValueError –
tapsis out of range, or the source has more than two channels.
- tap(index, /)[source]
Return one of the taps.
- Raises:
ValueError –
indexis not below the number of taps, or the splitter was deinitialised.
- clear()[source]
Drop the audio that is buffered and unread, so every tap starts on the source’s next frames. Use it after the source was read some other way, so the taps do not come back on stale audio.
- deinit()[source]
Release the splitter and its taps, and let go of the source. Every later use raises
ValueError.
- class audioroute.SplitterTap[source]
Bases:
objectOne branch of a
Splitter: the same audio, as an audio sample.Make taps with
Splitter.tap; they take no arguments of their own. The format is the source’s, as signed 16-bit audio.- sample_rate
Frames per second, from the source.
- property bits_per_sample
Size of one sample in bits: always 16.
- property channel_count
Number of channels: 1 or 2.
- deinit()[source]
Release this tap. Every later use raises
ValueError.
- class audioroute.Port(source)[source]
Bases:
objectA wire whose source can be changed while it plays.
A port hands back its source’s audio untouched and without copying it, and takes its format from the source it is made with. Hand a port to a player once, then
playa different source into it to change what is heard, without touching the player.- Parameters:
source – The stream to pass through. It cannot be None.
- Raises:
TypeError –
sourceis not an audio sample.ValueError –
sourceis None or was deinitialised.
- sample_rate
Frames per second. Writable, to 1 or more.
- property bits_per_sample
Size of one sample in bits, from the source.
- property channel_count
Number of channels, from the source.
- property source
The stream the port is passing through now.
- play(sample, *, loop=False, after=0)[source]
Point the port at a different source. It takes effect between blocks, and the player does not need to stop.
- Parameters:
sample – The stream to pass through from now on.
loop – Ignored. It is accepted so a call written for another audio object works here.
after – Frames to keep playing the current source first. The port switches at the start of the first pull after that many frames have played, which gives a level the old source is walking time to land. Until then
sourceis still the old one, and anotherplayreplaces the switch that was waiting. A port nothing has pulled since it was pointed at what it plays switches at once, and so doesafter=0.
- Raises:
TypeError –
sampleis not an audio sample.ValueError –
sampleis None,afteris negative, or the source’s sample rate, channel count, bit depth or signedness differs from the port’s.
- deinit()[source]
Let go of the source and release the port; the source itself is not released. Every later use raises
ValueError.