`listen.py`'s shape has not been built

[bdbarnett]

One object that owns the codec, the graph and the pump, with a safe surface
over it, is the live-instrument API and the example that would teach it.
audiolive.LiveAudio is most of the way there and is not it.

From #123.

[bdbarnett]

A proposal. Nothing is written and the tree is unchanged.

There is no listen.py in this repo. The name is docs/spikes/probes/listen.py
in the anchor — the P4 probe that first made a board sound. You import it and
it plays; you turn its knobs from a REPL while it does.

What LiveAudio already is

It does own all three. Codec: _open_codec()
(lib/examples/audiolive/__init__.py:398), reading AUDIO_OUT.wire at :386
and calling _audioif.i2s_start at :415. Graph: _rebuild() at :635,
which builds the Rack outside the swap and points the pump at it with
retarget (:668). Pump: spawn(…, sink=True) at :679, shutdown() at
:827. The safe surface is real too — LOCKED at :232 and _safely at
:240 are one runtime test in one place, so a knob is a plain setter.

What it lacks

It has no notes. The live-instrument half is one property, synth at
:555, handing you a raw synthio object you press from the interpreter thread,
at whatever block boundary the press lands on. The pump has a timestamped event
queue — audiopump.Events, now(), PRESS/RELEASE/RELEASE_ALL
(audiodsp/src/audiopump/audiopump.c:1870-1881) — and audioinstruments
already plays into it (_support.py:1078, sequencer.py). audiolive touches
none of it: grep the package for audiopump.events or now and you get
nothing, and rack_midi.py:142 still carries a comment saying the queue does
not exist yet. The one example here that keeps time on the audio clock,
drum_machine, reaches the queue the other way, through audiodev.pump
(drum_machine.py:259).

So it owns the pump and not the pump's clock. "Live instrument" today means
press it and hope.

Two behind that. It never calls service(), so on a threadless port spawn()
adopts the tail, returns −2 and pulls nothing (audiopump.c:1284-1297) — its
docstring's desktop and browser halves are a ring you drain by hand. And it
dropped listen.py's fit check: i2s_start returns the ring depth,
LiveAudio stores it as self.cushion (:415) and never reads it, where
listen.py timed each new chain's block and warned when it would not fit
(probes/listen.py:262-266).

The shape

Live — codec, graph and pump — in pydevices beside audiodev, not under
lib/examples/. The example stays here and shrinks to what teaches it.

• chain(spec=None) — read or set the pedalboard. Refuses a chain whose block
  outruns the ring it opened with, before you hear it.
• source(what=None) — "riff", "input", an instrument name, or a tuple
  summed through one Mixer. Refuses "input" where capture is not on the
  playback port.
• press(pitch, velocity=127, at=None) — at=None is now; an
  audiopump.now() frame is scheduled. Refuses a frame already past, and an
  instrument that is not schedulable.
• release(pitch=None, at=None) — None releases everything held.
• status() — load, worst block, starved ms, and why the pump stopped if it
  did. Refuses to report a pump it does not own.
• stop() — its own client off the pump, codec down. Idempotent, and it does
  not take another client's audio with it.

Two cuts from today's fifteen. knob/patch/labels become
live.effects[i].set_macro(…): on a locked build _safely is
return fn(*args) (:240), so they are index sugar over the effects' own API.
died/recover/drain fold into status() and the driver — a faulted pump
and a desktop ring are mechanism an instrument should not have to know.

The decision that forecloses

Whether Live owns audiopump or is a client of audiodev.pump.Pump. Today
it owns it: __init__ refuses if audiopump.running() (:316) and stop()
shuts the whole pump down (:827). Pump is where the event queue survives a
shutdown (pydevices/lib/audiodev/pump.py:1061 — re-attached there because
audiopump.shutdown() drops the queue with the thread), where a second client
gets a mixer voice, and where BusioDriver/RingDriver/ServiceDriver already
answer board, desktop and browser. Own the pump directly and you rewrite all
three, and can never sound beside drum_machine or piano.py. Moving it later
means moving every caller.

My recommendation is that Live be a client of Pump, reaching the codec only
through board_peripherals.audio_out(). Say yes to that seam and the six
methods above, or name the one you want different, and I will build it.

[bdbarnett]

Parked (Arthur, 2026-09-22): the proposal above — a Live object in pydevices beside audiodev, scheduling on the pump's clock — is the seed of the live-instrument surface, and building it belongs to an audio program with a vision and a gate, not to a housekeeping sweep. Reopens with that program, or the moment a user needs it.

[bdbarnett]

Trigger stated (Brad, 2026-09-23): it reopens with the pump trio (audiodsp#108, audiodsp#109, pydevices-examples#126), when live use shows the hole or a tear, for example a stompbox build or playing out. It's the same design territory, so one sitting covers all four.