# PROOF: producer-controlled record is in time

Run 2026-11-18 22:59:36 CST (box clock, America/Chicago) through the **real public relay** `https://marcusx.fun/takestamp`
(supernode, Caddy, TLS). Performer and producer were separate processes on the box; the performer
was started idle and never touched again. Each take: producer presses Record at bar 5
(song pos 7.338896 s = sample 352,267), 22 s of record, Stop, drain, auto-return to talk.
Tempo **130.81 BPM** (beat = 22,016.66 samples @ 48 kHz). The "singer" claps on every beat after a
1-bar count-in, plus a syncopated 4-and every 2nd bar (50 claps per take), over the performer's click.

Network impairment is injected on everything the performer sends (every 100 ms POST gets its own
delay, so with jitter they reach the relay **out of order**) and on the control messages it receives
(record_start / record_stop). On top of that is the real internet path box -> marcusx.fun.

## Results

| injected delay | per-POST delay (ms) | landed latency median / max (ms) | frames reordered | claps found | max clap placement error: vs rendered sample / vs exact beat | mean abs error vs exact | monitor vocal-to-beat offset | auto-start latency (Record press -> performer start) | monitor runs behind producer playhead (median) | monitor stalls | CRC bad | back to TALK after performer stop |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 ms (real internet only) | 0-0 | 221 / 405 | 25 | 50/50 | **0** / 0.415 smp (0.0086 ms) | 0.239 smp | **0** smp (n=44) | 162 ms | 710 ms | 0 (0 ms) | 0 | 230 ms |
| 300 ms | 300-300 | 522 / 707 | 15 | 49/49 | **0** / 0.411 smp (0.0086 ms) | 0.235 smp | **0** smp (n=43) | 507 ms | 1340 ms | 0 (0 ms) | 0 | 101 ms |
| 1859 ms +/-150 jitter (reordered) | 1709-2007 | 2078 / 3093 | 255 | 50/50 | **0** / 0.415 smp (0.0086 ms) | 0.239 smp | **0** smp (n=44) | 1978 ms | 4370 ms | 73 (730 ms) | 0 | 842 ms |
| 1859 ms +/-150 + 250 ms jump mid-take | 1710-2257 | 2213 / 2602 | 280 | 50/50 | **0** / 0.415 smp (0.0086 ms) | 0.239 smp | **0** smp (n=44) | 2017 ms | 4470 ms | 23 (230 ms) | 0 | 258 ms |
| 1859 ms +/-150 + 250 ms net jump + 250 ms performer clock jump | 1710-2257 | 2088 / 2983 | 305 | 50/50 | **0** / 0.415 smp (0.0086 ms) | 0.239 smp | **0** smp (n=44) | 1972 ms | 4510 ms | 81 (810 ms) | 0 | 802 ms |

How to read it:
- **Placement**: every clap was found on the producer's captured timeline and lands on **exactly the
  sample it was sung on** (matched-filter onset vs. the rendered sample: |error| < 0.00002 samples, i.e.
  detector precision; reported as 0). Against the *exact* fractional beat (130.81 BPM does not fall on
  whole samples) the error is at most 0.415 samples = **0.0086 ms**; that is only the beat grid rounded to
  whole samples, and it is identical in all five runs (the five curves overlap in the plot). Network
  delay, jitter, reordering, the 250 ms mid-take delay jump and a 250 ms step of the performer's wall clock
  changed **nothing**.
- **Shared monitor**: in the producer's monitor stream, Marcus's vocal and the beat he heard stay
  locked: offset **0 samples** on every on-beat clap in every run (|offset| < 0.00002 smp). They ride in the
  same frames, and the playout only ever holds whole blocks, so a stall can't pull them apart.
- **Auto-start**: in every run the performer started on its own (`auto: true, button_pressed: false`)
  from the relay's `record_start`. The latency from the producer's Record press to the performer's
  transport start was ~160 ms on the bare internet path (includes TLS setup for the POST), ~0.5 s at 300 ms,
  ~2.0 s at 1,859 ms. It doesn't affect placement because the performer starts **at the producer's song
  position** and stamps from there.
- **Monitor lag**: the producer hears the shared monitor about `auto-start + uplink + 250 ms buffer` behind
  their own playhead (0.7 s / 1.3 s / ~4.4-4.5 s). That's the lag Marcus described: it's constant within the
  take and is **not** sync error, because song time stays relative to itself.
- **Stalls** happen only in the monitor, never in the capture: the 250 ms delay jump forces a ~230-250 ms
  re-buffer, and real internet hiccups (single POSTs landing up to ~1 s late) add a few more. With the
  1,859 ms link a 500 ms monitor buffer would be the better default.
- Back to TALK: automatic after the performer's tail had landed and been monitored (0.1-0.85 s after
  `performer_stopped`), every run `RECORD -> DRAIN -> TALK`, capture complete.

## Files

- `proof/clap_error.png`: per-clap placement error (all runs), monitor vocal-to-beat offset, and a zoom
  of one clap vs. the producer's reference click from the hardest run.
- `proof/proof_d1859jjc_mix.wav`: hardest run (1,859 ms ±150 ms jitter + 250 ms delay jump + 250 ms clock
  jump), producer's captured track **mixed with the producer's own reference click**, from Record point.
  Same for every run: `proof_<tag>_mix.wav`, plus `proof_<tag>_stereo_L-capture_R-refclick.wav`.
- `proof/monitor_<tag>_L-vocal_R-beat.wav`: what the producer heard during RECORD/DRAIN (the shared monitor).
- `proof/results.json`, `proof/runs/<tag>/` (producer.json/npz, performer.json, logs).
- Reproduce: `python3 tests/e2e_session.py https://marcusx.fun/takestamp 22 && python3 tests/plot_proof.py`.
- Cross-language frame check: `tests/test_session_hdr.cpp` (C++ core <-> Python: take_id, song pos, CRC
  round-trip OK). `tests/test_core.cpp`: ALL PASS after the header change.

## What this does NOT prove (honest caveats)

- **No Mac, no Logic.** Both clients are the headless Python reference implementations. The JUCE
  Send/Receive changes are source only; they pass a `-fsyntax-only` compile against JUCE on Linux but were
  **not built or run as AUs**. Things only a real Logic session can confirm:
  - An AU can't press Logic's transport. The Send plugin runs **its own** transport (click, optional beat
    file) from the producer's song position. Marcus hears that through his vocal track, not Logic's
    arrangement. Driving Logic itself would need MMC over IAC (not built).
  - The Receive plugin on **Stereo Out** mutes Lou's local mix by replacing the bus output during the take.
    Whether Logic keeps calling Stereo Out's processBlock after Stop (needed for DRAIN) is untested;
    there's a 20 s safety timeout back to TALK.
  - **I/O comp** (interface output+input latency) is a manual number on the performer. The test singer
    is "perfect" (claps exactly on the rendered beat), so human timing and interface latency aren't in
    these numbers.
  - Session takes assume both sides run at the same sample rate (the headless run used 48 k on both).
- Both clients ran on the same box clock, so the auto-start latency is exact here. Across two machines
  it would need the relay clock (`relay_us` on every event) or the Listen clock-offset logic.
- Impairment is on the performer's link only. The producer's pull used the real path.
- The monitor buffer is fixed (250 ms); it doesn't adapt.

## Suggested fix for `/home/box/listen-feed/receiver.py` (not applied)

Symptom: ~20 s after audio arrives the main thread blocks forever in `pipe_write` to `pacat`, and pulse logs
`null-sink q overrun`. Cause: the loop paces `play.write()` by `time.time()`, but pacat drains at the
null sink's clock. Any drift or hiccup fills the 64 KB pipe, and then the blocking `stdin.write()`
freezes reception, the status file and everything else.
1. Never write to pacat from the network loop. Move it to a writer thread fed by a bounded
   `collections.deque(maxlen=~200 ms of blocks)` that **drops the oldest** block when full (count drops in status).
2. Or keep a single thread, but `os.set_blocking(proc.stdin.fileno(), False)`, write with `os.write`, and on
   `BlockingIOError` / short write drop the block (or the remainder) and count an overrun instead of waiting.
3. Let pacat's consumption be the clock instead of `time.time()` (in the writer thread, a blocking write *is*
   the pacing), and keep `--latency-msec=50`.
4. Watchdog: if no successful write for >1 s, kill and restart only pacat, without blocking the receive path.
