audiodev.pump

The audio pump, used without being asked.

audiopump is a C module that pulls a CircuitPython audiosample graph on a thread the interpreter is not on – a pthread on unix, a pinned FreeRTOS task on esp32 – and writes every block straight into I2S. When the firmware carries it, everything in audiodev that plays a sample graph goes through it; when it does not, nothing here does anything and the old path is untouched. No app asks for a backend.

There is exactly one pump: one C task, one I2S channel. So there is one Pump here too, reached through owner, and it is what arbitrates between an AudioOut graph and a PCMOutput stream that both want to sound. Two clients get a root audiomixer.Mixer built for them and the pump is retargeted onto it; one client is pulled with nothing in the way, which is why a single player’s PCM is byte-identical to the old path’s.

Three drivers, because the ports differ in where the bytes land and in whether there is a thread to land them from:

RingDriver

The desktop (unix, and anything else whose driver has no i2s_start). The pump fills a RAM ring; Pump.next_block drains it on the interpreter thread and hands the bytes to the existing push transport. The DSP leaves the interpreter thread; the byte-shovelling stays. Nothing on a desktop paces the pump, so this driver parks it between ticks – see RingDriver.produce.

ServiceDriver

WebAssembly and CPython, where the pump has no thread of its own. audiopump.service() runs the same loop on the interpreter thread, filling the same ring, and the audio is byte-identical to the unix build’s. What changes is that the ring is look-ahead rather than slack: a tick of T milliseconds needs a ring longer than T.

BusioDriver

esp32. The graph goes to audiobusio.I2SOut – CircuitPython’s own class, with this same pump under it – built from the board’s I2SWire. There is one way this firmware plays a sample, and that is it: the output owns the channel, converts anything that is not signed 16-bit on the pump’s thread, retunes the bus to the sample’s rate and sizes the DMA descriptor in time. audiodev writes no PCM, opens no peripheral, and is left holding the policy – the codec, two clients, a file, the fault sentence.

Windows uses it too, when the interpreter can play to the computer’s speaker itself (speaker). The output is then built on a SpeakerWire, and the pump writes every block straight into WASAPI on its own thread, with no Python between the graph and the device.

A fault in the pump is a sentence, not a traceback and not a dead speaker: Pump.died turns the status block’s error and fault words into one, and the caller that notices is AudioOut, which falls back to the old pull-on-the-interpreter path for the rest of the process.

exception audiodev.pump.StartFailed[source]

Bases: RuntimeError

The pump did not take a graph THIS TIME.

Separate from every other refusal on purpose. “This build cannot pump a file-backed source” is a property of the graph and will be true again in a millisecond; “the thread lost a race with a busy CPU” is a property of the afternoon, and making the second one sticky turns a transient loss into a process that never uses the pump again (omnipython#52).

audiodev.pump.module()[source]

The audiopump C module, or None. Imported once, checked properly.

audiodev.pump.driver()[source]

The _audioif C module – the pump’s platform driver – or None.

The pump is two halves. audiopump is the portable engine and ships with audiodsp on every port; _audioif is the hardware, and it exists only where there is hardware to drive. The I2S channel, the microphone Input and the round-trip probe are ITS names, not the engine’s.

Private by convention, as the underscore says: audiodev is the public face, and nothing outside this module should import it.

audiodev.pump.busio()[source]

The audiobusio C module – I2SOut – or None.

The public face of the audio hardware layer, and CircuitPython’s own spelling: audiobusio.I2SOut(bit_clock, word_select, data).play(sample) runs CircuitPython’s own docstring example on this firmware unchanged. Everything audiodev does on a board goes through it, so there is one way the firmware plays a sample and audiodev is the policy layer over it – format negotiation, volume, the codec session, two clients, files.

It is checked for I2SOut, not merely imported, for the same reason module is checked for spawn.

audiodev.pump.dac()[source]

The audioio C module – AudioOut – or None.

CircuitPython’s name for a DAC output, on a board whose audio is a DAC rather than I2S (an STM32H7’s, on the Arduino GIGA R1). It has I2SOut’s methods, so BusioDriver drives either one the same way.

audiodev.pump.driver_name()[source]

Which platform driver the engine bound: esp32, pthread, win32, none.

“none” on a build with no driver linked – WebAssembly, and anything that shipped the engine without the hardware half. That build still pumps; threaded() is False and audiopump.service() drives the loop.

audiodev.pump.available()[source]

True when this firmware carries a usable pump.

audiodev.pump.on_board()[source]

True when the pump owns a peripheral, rather than a ring.

That is an I2S channel on esp32 and a DAC on an STM32H7. Asked of the DRIVER, not the engine: the engine is the same code on every port and has no idea whether there is a peripheral behind it.

audiodev.pump.speaker()[source]

True when the pump can play to the computer’s speaker itself.

Windows: audiobusio.I2SOut(..., sink="wasapi") opens the default speaker in WASAPI shared mode and the pump writes each block to it from its own thread. Asked of the driver, which has sink_stats only where a sink can be a speaker.

audiodev.pump.c_sink()[source]

True when the pump can write to a C sink from its own thread.

A USB speaker on the host port publishes one (c_sink() on its output). The engine says whether its spawn takes it, and it needs a thread to write from.

class audiodev.pump.SpeakerWire(sink='wasapi')[source]

Bases: object

The wire BusioDriver builds a desktop speaker output on.

A board’s I2SWire names pins; a speaker has none, so the pin numbers are placeholders the desktop I2SOut ignores and sink is what picks the device: "wasapi" is the default speaker, and the firmware’s README gives the full path syntax.

audiodev.pump.duplex()[source]

True when this firmware can record while it plays, on one I2S port.

The driver opens the board’s port as a TX/RX channel pair whose RX half Python can read (_audioif.rx_open), so a speaker and a microphone that share a port’s clocks – the ESP32-P4 boards’ ES8311 and ES7210, or the ES8311’s own ADC – are two halves of one channel rather than two owners fighting over it. A board asks this to decide which PCMInput to build: PumpPCMInput when True, machine.I2S when not.

audiodev.pump.clock_running()[source]

True while the pump’s driver has an I2S channel open on this board.

A board whose codecs need MCLK before I2S exists bootstraps it with PWM on the same pin. Starting that PWM while the channel is running takes the pin away from it, so both codecs lose their clock mid-stream; a board asks this first. False on any firmware that cannot answer.

audiodev.pump.threaded()[source]

True where spawn() puts the pull loop on a thread of its own.

False on WebAssembly, where there is no thread to put it on and audiopump.service() runs the same loop on this one. A build too old to answer has a thread, because every build that had the pump before this question existed did.

audiodev.pump.backpressure()[source]

True where a full output ring makes the pump wait instead of dropping.

The one question a desktop driver has to ask before it decides whether to park the pump between ticks. With back-pressure the ring is the pace – exactly as an I2S write is the pace on a board – so parking is pure cost and the pump is left to run. Without it a free-running pump fills the ring in milliseconds and loses whole blocks, which is not a glitch you can hear past on a recording; it is a hole in the bytes.

A build too old to answer does not have it: every build that had the pump before this question existed dropped.

audiodev.pump.now()[source]

Frames the pump has pulled since it started, or 0 without one.

The number an event’s frame is compared against, so it is the one to schedule from. It is not what a listener has heard: subtract whatever the sink is holding for that. It wraps every 2^32 frames – 24.9 hours at 48 kHz – and the comparisons inside the queue are wrap-aware, so nothing out here has to be.

audiodev.pump.events(capacity=96)[source]

The pump’s event queue, or None on a build with no pump.

audiodev.pump.events() is how an app reaches the clock; see Pump.events for why the queue belongs to the pump and not to the app that asked for it.

audiodev.pump.ring_bytes(frame_size, chunk_bytes=0, max_block=0)[source]

How deep the desktop output ring is, for frame_size-byte frames.

One rule in one place, because three things have to agree on it: the ring RingDriver allocates, how far ahead of the interpreter a free-running pump therefore gets, and how deep anything feeding that pump has to be – a Prefetch, above all, which the pump would otherwise empty between two ticks.

This number is the latency of a live event, and that is why it is two drain windows and not eight. A pump the ring paces keeps the ring full, so a note pressed now is heard after everything already in it has been handed out. Eight chunks is 160 ms at a 20 ms tick, which is a delay you can play against a metronome and hear. Two chunks plus a block is 26 ms at a 10 ms tick, which is what the parked pump used to give – the same latency, with the pump off the interpreter’s timeline instead of on it.

The floor is two blocks of the graph, because a graph’s block is whatever its tail offers – an audiocore.RawSample offers its entire buffer, so a half-second tone is a 96 kB block – and a ring that cannot hold one is the one case back-pressure cannot rescue: it drops, and counts it.

audiodev.pump.block_size(sample)[source]

Bytes in one pull of sample, or 0 if it cannot be asked.

The audiosample protocol publishes sample_rate, channel_count and bits_per_sample to Python and not max_buffer_length, so the one number a ring has to be sized against is the one Python cannot see. The pump’s info() reads it off the C base struct. Without it a ring is sized by guesswork, and an audiocore.RawSample hands back its whole buffer in a single pull – a half-second tone is a 96 kB block, which a 64 kB ring silently drops in its entirety.

audiodev.pump.rearranging()[source]

True while something is rearranging the pump. A tick must not pull.

A service tick arrives between bytecodes. On a board it rides the app’s shared timer and is delivered by micropython.schedule, so it lands wherever it lands – including halfway through the method that is taking one client off the pump and putting another on. The P4 found the first instance of this the hard way: a tick inside stop saw a player that read exactly like a healthy old-path player, pulled a block, wrote it, and opened machine.I2S on the port the pump had just let go of. Both halves of that race were seen on silicon.

AudioOut._pumping closed it for one player’s own methods. It cannot close the rest, because the thing being rearranged is global: one pump, one graph, one peripheral. A tick that services player B while player A is inside Pump._retarget reaches the same C module through a different Python object, and spawn() answers the second one with “a pump is already spawned”.

So this is the flag, and it is the pump’s rather than any player’s. It nests, because AudioOut.play -> Pump.play -> Pump._retarget is three of these deep on one call.

audiodev.pump.reentered()[source]

Ticks turned away because something was rearranging the pump.

Never a hole: the tick’s whole job is to top a buffer up, the buffer is hundreds of milliseconds deep, and the next tick does what this one did not. A number that climbs says the app’s timer is faster than its own rearrangement, which is worth knowing and is not worth an exception.

audiodev.pump.health()[source]

The process pump’s Pump.health, without building one.

Returns None when this firmware has no pump, so a status screen can ask unconditionally.

audiodev.pump.retarget(mod, sample, loop=False)[source]

Swap a live pump’s tail, carrying the OUTPUT’s loop flag with it.

The flag belongs to the tail, not to the pump’s whole lifetime. A root audiomixer.Mixer replaced by the one client still sounding is a tail whose loop is that client’s, and for as long as retarget() took one argument it kept whatever spawn() was called with – so a looping client left alone on a live pump stopped at the end of its first lap, silently, exactly as a mixed one did before _tail() learned loop=.

An engine too old for the keyword still swaps the graph; it just cannot carry the flag, which is the bug, so say nothing and let the caller’s own gate report it rather than losing the audio.

audiodev.pump.pumpable(sample)[source]

True when the pump can pull sample itself.

A file-backed source cannot: its get_buffer re-enters the interpreter to read the VFS, and the pump thread has no interpreter on it. Those go through a Prefetch into a ring instead.

This catches the source at the tail only. A WaveFile buried deep in a graph is caught by the pump at the first block instead, as a fault – the audiosample protocol gives no way to walk backwards. That is a known hole, not an oversight.

class audiodev.pump.Prefetch(sample, *, frames=256, capacity=6, loop=False, min_bytes=0)[source]

Bases: object

A file-backed sample, pulled on the interpreter thread into a ring.

WaveFile, MP3Decoder, VorbisDecoder and anything else that reads through the VFS re-enter the interpreter inside get_buffer, so the pump refuses them. They become producers: this pulls with audiocore exactly as the old path did, on the thread that is allowed to, and writes what it yields into an audiopump.Ring the pump treats as an ordinary source node.

It lives here, next to the thing that owns the pump, because the alternative is every caller inventing it again. Call service from the same tick that services the player.

service(limit=None)[source]

Top the ring up. Returns bytes written this call.

Not re-entrant, and a tick can land inside it. The block pulled from the file lives in self._held until the ring has taken all of it; a second call arriving in the middle pulls the NEXT block over the top of it and the frames in between are gone – a gap in the file that nothing counts, because wrote is only told about what reached the ring. A tick that finds this busy does nothing and the next one tops the ring up instead; the ring is deeper than a tick by construction.

It always comes back: when the ring is full, when the source has nothing ready (a stream waiting on the network), or after one ring’s worth of bytes if limit is not given, so a source slower than real time can’t hold the caller here.

fed()[source]

True when every byte of the file is in the ring.

Not the same as done, which only says the file has been read to the end: a block the ring had no room for is still held here, and wrote has not counted it yet. Treating the two as one ended the WAV 22 kB early, which is a clean fade-out and looks like nothing.

finished()[source]

True when the file has been read out and the ring has drained.

class audiodev.pump.RingDriver(frame_size, *, chunk_bytes=0, max_block=0)[source]

Bases: _Driver

Desktop: the pump fills a RAM ring, the interpreter drains it.

The ring is the pace. There is no DMA on a desktop to block the pump, so the ring does it: when it has no room for another block the pump thread sleeps, and this driver’s next drain wakes it. Nothing is dropped, STATUS_RING_OVF is 0 by construction, and the pump runs freely between ticks – which is where the DSP finally leaves the app’s timeline.

It did not always. Until back-pressure landed the C ring dropped whole blocks rather than overwriting what had not been taken, so this driver had to unpark the pump only inside produce() and park it again before returning. That kept the bytes exact and cost the whole point of a thread: a parked pump is a pump the interpreter waits for, and 96 % of the pump path’s time was inside produce(), waiting. Letting it free-run instead was tried, with a policy that stopped the moment the ring reported a drop – an app doing 3.5 ms of its own work per tick went from 1811 ms to 1028 ms, 1.8x – and the audio lost 71 to 5657 blocks every time. That policy cannot work: by the time the counter says a block was dropped, the block is gone. Making the ring wait is the same win with no byte at risk.

The park path is still here, and it is not dead code: it is what a build whose driver has no wait hook gets, and backpressure is the question that chooses between them. Latency is the ring: with back-pressure the pump keeps it full, so what is between a live event and the speaker is the ring’s own depth plus whatever the host transport holds. ahead_ms says what this one’s is.

ahead_ms(rate=48000)[source]

How much audio the ring holds when full, in milliseconds.

The bound on a live event’s latency through this driver, and the one number to state rather than discover: with back-pressure the pump keeps the ring full, so a note pressed now is heard after what is already in it has been handed out.

dropped()[source]

Blocks the ring had no room for. Must be 0; it is the byte stream.

waited()[source]

(times, microseconds) the pump waited for this driver to drain.

Zero on a build with no back-pressure, and zero on one whose consumer is always slower than the ring is deep. It is the number that says the ring really is the pace: a pump that never waits is a pump nothing is holding back, and on a desktop that means it was dropping.

produce(into)[source]

Fill into with what the pump has made. Returns bytes.

rest()[source]

Stop the pump running ahead until the next produce().

A no-op where the ring is the pace: running ahead is exactly what the pump is supposed to do there, and it stops on its own when the ring is full. Parking it here would put the DSP back on the app’s timeline, which is the cost this whole change exists to remove.

class audiodev.pump.ServiceDriver(frame_size, *, chunk_bytes=0, max_block=0, ahead_ms=0)[source]

Bases: RingDriver

WebAssembly and CPython: there is no thread, so this tick is the pump.

Same ring, same drain, same bytes. What changes is where the loop runs: audiopump.service() enters the C pull loop on the interpreter thread and returns when the ring is full, so the park/unpark dance above has nothing to park – the pump is at a block boundary whenever Python holds the thread, which is always.

The ring stops being a buffer against a racing thread and becomes the look-ahead: everything produced in this tick has to last until the next one. A tick of T milliseconds therefore needs a ring longer than T, and measurably so – 10 ms wants 4 blocks, 50 ms wants 16 and 200 ms wants 64. That is the whole of the difference a missing thread makes; the audio is byte-identical either way.

produce(into)[source]

Fill into with what the pump has made. Returns bytes.

rest()[source]

Nothing to rest. The pump only runs inside produce().

class audiodev.pump.BusioDriver(wire, fmt, *, power=None, volume=None, transport=None)[source]

Bases: _Driver

esp32: the graph goes to audiobusio.I2SOut, and it owns the bus.

On a board whose wire is a DACWire it goes to audioio.AudioOut instead, the same object built on a DAC, and everything below holds for it too.

There is one way this firmware plays a sample, and this is where audiodev joins it. I2SOut opens the channel, spawns the pump, converts anything that is not already signed 16-bit on the pump’s thread, reads a file through a ring of its own, retunes the bus to the sample’s rate on every play(), sizes the DMA descriptor in time and refuses a second output with CircuitPython’s own “Peripheral in use”. None of that is audiodev’s to reimplement, and all of it used to be: this class opened the channel with _audioif.i2s_start and a dma_frame=128 fixed at every rate, which is the descriptor bug audiobusio already measured and fixed (67 starved blocks in 2 s at 8 kHz; zero at rate/200).

What stays here is the policy nothing below the line knows about: the codec. I2SOut does not know a codec exists – CircuitPython’s does not either – so the board’s audio_power role is raised here, with the volume the transport is holding, and the transport is told its hardware is live so set_volume() and mute() reach the codec while the pump plays. That was measured on the P4 as a volume knob that stored a number and reached nothing.

Two keywords of I2SOut’s are ours rather than CircuitPython’s and both are used here: port= (a board can have the codec on one port and a microphone on another) and main_clock_fs= (the board’s I2SWire has carried it since before this module existed). sink= is the third, and on a desktop it is what makes this class testable at all – see open.

retarget(sample, loop=False)[source]

Point a running pump at sample. No gap, no re-open.

halt()[source]

Stop the pump. The peripheral, if any, stays open.

starved()[source]

Blocks the DMA could not be given in time. I2SOut’s own word.

status()[source]

The status block the loop writes, or None to use the caller’s.

class audiodev.pump.SinkDriver(transport, ahead_ms=None)[source]

Bases: _Driver

The graph goes to an output’s C sink, written by the pump’s thread.

For an output that isn’t the board’s own I2S but can take PCM from native code: a USB speaker on the host port. The pump renders the graph and writes each block into the speaker’s stream itself, so no audio waits for the interpreter.

The output’s buffer may be large, for the times the interpreter fills it instead. The pump keeps only ahead_ms of sound queued in it, which is the delay this path adds.

The transport’s volume and mute are software here, and the pump’s bytes don’t pass through the transport, so the pump applies them: level hands it the transport’s current setting.

Parameters:
  • transport – A PCMOutput with c_sink() and capacity(). It is kept, so its stream lasts as long as this driver.

  • ahead_ms – Sound kept queued in the output. The default is the transport’s c_sink_ahead_ms, or 10.

A transport may also name the priority the pump’s thread should run at while it writes there, as c_sink_prio. A USB speaker does: the task that sends its packets must be able to interrupt the pump, or packets go missing while a block renders.

retarget(sample, loop=False)[source]

Point a running pump at sample. No gap, no re-open.

level()[source]

Take the transport’s volume and mute to the playing pump.

status()[source]

The status block the loop writes, or None to use the caller’s.

class audiodev.pump.PumpPCMInput(format, *, wire, ring_bytes=20000, take='mix', timeout_ms=1000, before_open=None, **kwargs)[source]

Bases: PCMInput

Capture from the RX half of the pump’s own I2S channel.

On a board whose speaker and microphone share one I2S port, machine.I2S can have only one of them: it opens one direction per port, and opening the second silently takes the port from the first. The pump’s driver opens the port as a TX/RX pair instead, and this reads the RX half – so an audio_out can play while this records, in either order, and closing one leaves the other running.

It is a PCMInput like any other: readinto() fills the buffer and blocks until it has, areadinto() waits without blocking the loop, and gain and mute are the board’s codec. What is different is underneath: the driver’s interrupt copies every finished DMA block into a ring of ring_bytes, so a reader that falls behind by less than that loses nothing. stats()["dropped"] counts the frames a slower reader lost.

The channel is opened (or joined) BEFORE the codec is brought up, so the codec’s setup runs with the channel’s MCLK already on its pin; a board must not start a PWM clock on that pin while clock_running says the channel is up.

take picks what a one-channel recording hears from a two-slot wire: "left", "right", or "mix", their average, which is the right answer for a codec with a microphone in each slot.

A board with no I2S microphone hands it another wire. On a PDMWire the firmware decimates a PDM microphone in hardware, and on an AnalogWire it samples an ADC pin on a timer; both record mono, into the same kind of ring, and neither shares a clock with the output, so they record at any rate the board declares while anything plays. The Arduino GIGA R1 records this way.

stats()[source]

captured and dropped frames, and waiting bytes.

audiodev.pump.pcm_input(format, **kwargs)[source]

Build a PumpPCMInput (see its docstring for the keywords).

class audiodev.pump.PumpOutput(fmt, *, frames=256, capacity=6)[source]

Bases: object

A push stream on the pump: PCMOutput’s _write, over a Ring.

On esp32 this is what a PCMOutput has to become, because the pump owns the I2S channel and machine.I2S cannot be opened beside it. The contract lines up exactly: audiopump.Ring.write() takes whole frames and returns bytes accepted, which is try_write()’s, and space() is bytes, which is what the fill-to-space rule counts in.

On a desktop host it is not used, and that is the answer rather than an omission: the transport there is already a push queue with its own thread behind it, so putting the pump in the middle would copy every byte into a ring and out again to reach the same queue, for nothing. The pump earns its place where it owns the peripheral or pulls a graph.

Mix it into audiodev with:

class MyOut(PCMOutput):
    def _write(self, buf):  return self._ring.write(buf)
    def space(self):        return self._ring.space()

which is what attach_stream builds.

drain()[source]

Nothing to do: the pump is the consumer and it never blocks.

audiodev.pump.attach_stream(fmt, *, driver=None, frames=256, capacity=6)[source]

Put a push stream on the pump beside whatever else is sounding.

Returns a PumpOutput the caller writes PCM into, already registered as a pump client – so an AudioOut graph and this stream are summed by a root Mixer and come out of one peripheral.

This caller DID ask for the pump, so it plays with raises=True and a refusal arrives as the driver’s own exception – the ValueError that says whether it was the rate or the sample width – rather than as a RuntimeError carrying a copy of its wording.

class audiodev.pump.PumpPCMOutput(format, *, wire, audio_power=None, frames=256, capacity=6, buffer_ms=None)[source]

Bases: PCMOutput

A PCMOutput that writes into the pump, for a board whose pump owns the only output there is.

A DAC board has no machine.I2S to open beside the pump, so its pcm_out is this: opening it puts a ring on the pump with attach_stream, and write() fills the ring. A sample graph playing at the same time is summed with it. The ring takes what it has room for and returns 0 when full, so wrap it in pace_output the way an I2S board wraps machine.I2S.

wire is published for AudioOut, which finds it on its transport and plays a graph straight through BusioDriver without opening this stream at all.

buffer_ms

The audio the DAC’s own ring should hold, in milliseconds, or None for the firmware’s default. BusioDriver hands it to audioio.AudioOut(buffer_ms=).

queued_size()[source]

Bytes still waiting to play or capture. Default 0.

is_active()[source]

True while PCM remains queued. Default False.

class audiodev.pump.Pump[source]

Bases: object

The one pump, and who is sounding through it.

Clients come and go with play and stop. One client is the pump’s tail directly. A second client makes a root audiomixer.Mixer with a voice each, at level 1.0 – the Mixer sums, so two loud clients clip, which is the same arithmetic two CircuitPython AudioOuts into one DAC would do and is stated rather than quietly halved. The old root is retired one generation late, never deinited straight after the retarget: doing that immediately is a race the P4 caught, with fault=deinited.

events(capacity=96)[source]

The pump’s event queue, or None on a build without a pump.

One queue, for the same reason there is one pump: it is the pump that applies it, at the top of each block, on its own thread. An app puts notes on it with a frame number – see Instrument.scheduled() in audioinstruments – and the groove then stops caring what the interpreter thread is doing.

It is re-attached here rather than by the app, because audiopump.shutdown() drops the queue along with the thread, and a player calling play() a second time goes through a shutdown. An app that attached its own queue once would find it quietly stopped being applied on the next kit change, with no error anywhere. It is also emptied at that point: every frame in it was stamped against a clock that has just gone back to zero.

play(owner, sample, driver=None, loop=False, raises=False)[source]

Put owner’s sample on the pump. Returns True when it sounds.

A refusal is False and a sentence on fault, because the usual caller is a player that never asked for the pump and cannot be made to handle its problems.

raises=True is for the caller that DID ask. The driver’s own exception comes out instead of being flattened into that sentence – audiobusio.I2SOut.retarget raises a ValueError naming which refusal it is, a rate change or a sample that is not signed 16-bit, and until this keyword existed there was no way to catch it (audioif#2). refusal is the same object for the callers that take the False.

status()[source]

The block the loop writes. The DRIVER’s, where it owns one.

audiobusio.I2SOut spawns with a status bytearray of its own, so on a board the one this object allocated is never written to. Reading it anyway is the shape of bug that reports a healthy pump as error 0, fault 0 for ever – silence with a reassuring sentence.

health()[source]

One dict an app can put on a screen. Nothing here raises.

The counters underneath this were each readable on their own and none of them had a reader, which is how reentered() came to be a number nobody could see (omnipython#38; audiocomponents#97 is the same shape one layer up and chose this surface first).

The entries, and which of them is bad news:

dropped

Blocks the output ring had no room for. This is the one that means audio was not heard. It is 0 by construction on a build whose ring can hold one block of the graph; a number here says the ring is shorter than the graph’s own block.

reentered

Ticks that arrived while something was rearranging who is sounding, and were turned away. Not a hole. The buffer under it is hundreds of milliseconds deep and the next tick does what this one did not. A number that climbs says the app’s timer is faster than its own rearrangement, which is worth knowing and is not worth an exception.

waited / waited_us

Times the pump slept because the ring was full, and how long in total. On a desktop this is the number that says the ring really is the pace: a pump that never waits is a pump nothing is holding back, which on a desktop meant it was dropping.

blocks / bytes

What it has pulled since it was spawned.

clients

Players and streams sharing the pump. Two means a root Mixer.

running

Whether the loop is live. False with fault None just means nothing is playing.

ahead_ms

How much audio the ring holds when full: the floor under note-to-sound latency on this driver.

fault / blocked

The last refusal as a sentence, and whether it is still refusing. blocked True is the state where every play() goes to the interpreter thread.

died()[source]

The reason the pump stopped by itself, as a sentence, or None.

fault()[source]

The last reason the pump stopped or refused a graph, or None.

It is a record, not a verdict: it survives the teardown that repairs the pump, so an app can still say what happened after the speaker has come back. blocked is the one to ask before deciding whether to reach for the pump at all.

refusal()[source]

The exception behind fault, or None.

audiobusio.I2SOut.retarget raises a ValueError naming which refusal it is; flattening it to str() was the whole of what a caller could see (audioif#2). A caller that took the False can re-raise this or test its type.

blocked()[source]

True while the pump will refuse every play.

Set when a fault lands on a pump that is still holding something – a thread, a channel, a half-swapped tail. Cleared by the teardown, which is the repair, or by clear_fault.

clear_fault()[source]

Forget the last fault and let the next play try again.

note_fault(why, blocking=True)[source]

Record a refusal somebody else caught.

blocking=False records it WITHOUT closing the door: the sentence is on fault() for whoever reports it, and the next play() tries again. That is what a transient loss wants – a pump that lost one race with a busy CPU is not a pump that cannot pump this graph, and nothing else ever clears _blocked on this path (omnipython#52).

audiodev.pump.owner()[source]

The process’s one Pump.

audiodev.pump.forget()[source]

Drop the pump and everything on it. For tests and soft-reset paths.