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: object

An 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_count objects, so mixer.voice[0].level = 0.5 sets 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.LFO starts 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 – voice is 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 – voice is out of range.

deinit()[source]

Free the mixer. Later calls other than deinit raise ValueError.

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: object

One 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.LFO or synthio.Math that moves it. A new voice starts at 1.0.

With Mixer.level_ramp at 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.LFO or synthio.Math. A mono mixer ignores it. A change follows the rules of level.

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.

stop(voice=0)[source]

Stop the voice at once. voice is accepted and ignored, as in CircuitPython.

end()[source]

Let the source play to its end and then stop, by turning looping off.

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: object

Fans 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 – taps is out of range, or the source has more than two channels.

tap(index, /)[source]

Return one of the taps.

Raises:

ValueError – index is 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: object

One 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: object

A 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 play a 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 – source is not an audio sample.

  • ValueError – source is 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 source is still the old one, and another play replaces the switch that was waiting. A port nothing has pulled since it was pointed at what it plays switches at once, and so does after=0.

Raises:
  • TypeError – sample is not an audio sample.

  • ValueError – sample is None, after is 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.