# Take Stamp

Marcus sings to his beat in Logic. Each sample of his vocal is stamped with the song position he
sang it at and sent losslessly to Lou's Logic, where it lands at exactly that position.
**Nothing slides.** Placement comes from Marcus's playhead, not from arrival time, so network delay
doesn't matter. Lou can sit in a silent room minutes behind, and the session fills in as he plays.

- Page / downloads: https://marcusx.fun/takestamp/ (password `[redacted]`)
- Relay: RAM only. It stores nothing on disk, keeps a ~5 min in-memory ring for reconnects, and is
  empty after a restart.
- Wire format: LSTN v2 frames, the shared Listen spec (`PROTOCOL.md`), 32-bit float, CRC-checked.

```
Marcus's Logic                 supernode (RAM)                Lou's Logic
vocal track                                                   TakeStamp Receive
 [TakeStamp Send] --f32 + song pos--> /takestamp relay --pull-->  song timeline (RAM)
   audio passes through                                        out[pos] = take[pos]
                                                                 |  (Print mode)
                                                                 v
                                                interface out -> Lou's preamps/outboard -> interface in
                                                                 |
                                                filed at pos - measured loop  ->  BWF / Logic track
```

## Session mode: Lou presses Record, Marcus never presses anything (2026-11-18)

```
Lou presses Record ─▶ record_start ─▶ relay ─▶ Marcus's TakeStamp Send starts its own transport
                                                at that song position: click/beat in his ears,
                                                mic + beat-as-heard stamped with song position
Lou's Stereo Out [TakeStamp Receive, Session producer]
   local mix MUTED ─▶ monitor = Marcus's feed (vocal + beat, small fixed buffer)  = shared monitor
   capture = vocal placed by stamp on Lou's timeline (sample-accurate)
Lou presses Stop ─▶ Marcus stops, tail lands, take exported as BWF at its song position ─▶ TALK
```

- **Marcus (performer):** TakeStamp Send on his vocal track, "Follow producer" on (default). Optional
  "Load beat..." (same sample rate, sample 0 = bar 1); otherwise it plays a click. Set "I/O comp" to his
  interface's output+input latency in samples.
- **Lou (producer):** TakeStamp Receive as the **last insert on Stereo Out**, tick "Session producer".
  Record = start both sides. Stop = end; it drains the tail and returns to talk mode by itself.
- **Headless (no Mac needed):** `headless/performer.py` (waits, auto-starts) and `headless/producer.py`
  (presses Record/Stop, mutes, monitors, captures). Proof: `tests/e2e_session.py`, results in `PROOF.md`.
- Protocol: `PROTOCOL.md` -> "Session channel".

## Build (each Mac, once)

Requires Apple Command Line Tools (`xcode-select --install`). Xcode and Homebrew aren't needed.
`build.sh` uses JUCE from `~/dev/JUCE*` if it's there, otherwise it downloads JUCE 7.0.12, and it
downloads a portable cmake if you don't have one.

```bash
unzip TakeStamp-src.zip && cd takestamp
ONLY=Sender   ./build.sh     # Marcus's Mac
ONLY=Receiver ./build.sh     # Lou's iMac (Catalina OK)
```

That installs `TakeStamp Send.component` / `TakeStamp Receive.component` (plus VST3) into
`~/Library/Audio/Plug-Ins`, ad-hoc signs them, and runs `auval`. In Logic they're under
**Audio Units > MarcusX**. If they don't show up, go to Logic > Settings > Plug-in Manager > Reset & Rescan.

## Both sessions

Use the same beat, tempo, project start (bar 1) and, ideally, sample rate (48 kHz). If the rates
differ, the receiver converts positions through seconds, so it still lines up, with linear interpolation.

## Marcus (sender), no setup beyond the insert

1. On the vocal track, add **Audio FX > Audio Units > MarcusX > TakeStamp Send**. Record-arm it /
   turn on input monitoring so the plugin hears the mic.
2. Record as usual. While the transport rolls, the vocal ships with its song position. The status
   line reads `SENDING`. Check *Only while recording* if you don't want playback passes sent.
3. A punch-in over the same bars replaces the earlier pass on Lou's side, because the newest pass
   wins regardless of arrival order.

Headless fallback with no plugin (rough, MTC-accurate to about 10 ms): `headless/mtc_send.py`
captures BlackHole and reads Logic's MTC (see the file header).

## Lou (receiver)

**Simple:** insert **TakeStamp Receive** on an audio or aux track. Play from anywhere at or behind
where Marcus is and his vocal comes out at the exact spot. Then either bus it to an audio track and
record, or click **Export stream BWF**.

**Through Lou's preamps (the main mode):**
1. Make an audio track "TS Loop" with:
   - *input* set to the interface input the preamp/outboard returns on;
   - *output* set to the interface output that feeds the preamp (not the monitor mix);
   - input monitoring on;
   - **TakeStamp Receive** inserted.
   The plugin doesn't pass its input through, so there's no feedback.
2. With the transport stopped, click **Ping loop**. It plays a 50 ms sweep out through the chain,
   finds it coming back, and shows `loop (ping) N smp`. That N is the full round trip
   (DA -> preamp -> AD -> buffers). Re-ping if you change the buffer size or the chain.
3. Turn on **Print** and play from a few bars before Marcus's take. Marcus's vocal goes out through
   the preamps and the return is filed at `position - loop`, sample-aligned to his stamps.
4. Click **Export print BWF**. The file goes to `~/Music/TakeStamp/` and carries a BWF time
   reference. Drag it in, then use *Edit > Move > To Recorded Position*. **BWF project start (s)**
   (in the plugin's Controls view, default 3600 = 01:00:00:00) has to match the project's SMPTE
   start at bar 1.
   - Alternatively, record the return on a separate Logic track. Logic's own latency compensation
     applies there, and the **lead** control nudges the output earlier if Logic's measurement is off.

The **Clear RAM** button drops everything held, and so does closing the plugin. Nothing persists
unless you export.

## Tests (box/supernode, Linux)

```
g++ -O2 -std=c++17 -Icore tests/test_core.cpp -o test_core
python3 tests/e2e_relay.py https://marcusx.fun/takestamp /tmp/dump.bin 12   # prints song_start/len
./test_core /tmp/dump.bin <song_start> <len>
```

The tests cover:
- 50-500 ms jitter, out-of-order delivery, duplicates and a punch-in take;
- an old pass arriving late;
- ns stamp round trip;
- loopback ping through a simulated preamp (gain, HF roll-off, noise);
- a full print loop;
- a dump pulled from the real relay.

See `TEST_RESULTS.md`.

## Files

| path | what |
|---|---|
| `core/TakeStampCore.h` | wire codec, song timeline (take-recency overwrite), loop ping. No JUCE |
| `plugins/Sender/Plugin.cpp` | TakeStamp Send AU/VST3 |
| `plugins/Receiver/Plugin.cpp` | TakeStamp Receive AU/VST3 (place, ping, print, BWF export) |
| `relay/server.py` | supernode relay (systemd user unit `takestamp`, :19360, Caddy `/takestamp/*`) |
| `headless/mtc_send.py` | plugin-less fallback sender |
| `build.sh` | macOS build + install + auval |
