3Tips for future agents working in this repo — a Node CLI that joins a
4[commonroom](https://github.com/concept-collection/commonroom) call as a
5muted, visible participant and records every other participant's audio (one
6WAV per participant) plus the room chat. Read commonroom's CLAUDE.md first:
7this tool speaks its protocol verbatim, and the protocol is documented there.
9## Architecture
11```
12src/
13 identity.ts ported from commonroom; EPHEMERAL keypair (no localStorage)
14 nostr.ts ported near-verbatim (Node >= 22 global WebSocket); close() added
15 peer.ts ported, adapted to @roamhq/wrtc; receive-only media (see below)
16 wav.ts incremental WAV writer (buffers ~1 s, re-patches header sizes)
17 recorder.ts the heart: presence, mesh, control channel, audio sinks, files
18 cli.ts arg parsing, signal handling, log lines
19 test/
20 speaker.ts synthetic participant: sine tone + one chat message
21 loopback.js test: recorder + speaker in a random room, verify tone + chat
22```
24## Key design decisions
26- **Protocol-identical participant.** Same announcements, per-peer signaling
27 topics, deterministic initiator (smaller peer ID), control-channel messages
28 (hello/mute/chat/bye), stalled-connection retry, room-full handling, and the
29 soft cap of 8 — the recorder counts toward it. Don't invent protocol; if the
30 browser client changes, port the change.
31- **Receive-only media, but symmetric-looking.** Outgoing tracks are wrtc
32 `RTCAudioSource`/`RTCVideoSource` placeholders that never produce data (=
33 a fully muted participant). The VIDEO m-line is negotiated `sendonly` from
34 our side (as initiator via `addTransceiver(track, {direction:'sendonly'})`;
35 as answerer by flipping the transceiver direction after
36 setRemoteDescription) so browsers never send us video — saves bandwidth and
37 decode CPU. Audio stays sendrecv.
38- **Recording gates on first non-zero frame.** Before the first RTP packet,
39 `RTCAudioSink` delivers all-zero frames at a PROVISIONAL sample rate (16 kHz
40 observed), then switches to the real one (48 kHz) — opening the file eagerly
41 yields junk stub segments. A never-unmuting participant produces no file. A
42 mid-stream format change (rare) closes the segment and starts a new one.
43- **Wall-clock silence padding.** If the sink stalls > 1 s (network gap, DTX),
44 silence is inserted so sample position keeps tracking elapsed time — the
45 manifest's segment `startedAt` plus the file offset IS the meeting timeline.
46- **connectionState flaps.** wrtc can pass through 'connected' several times
47 while ICE settles; the connect handler must be idempotent or hello/notice
48 get re-sent per flap.
49- **Bye cooldown (3 s).** An announcement published just before a peer's bye
50 can arrive just after it and would trigger an instant reconnect (and a stub
51 recording); after a bye we ignore that peer's announcements briefly.
52- **Every exit path MUST end in `process.exit()`.** @roamhq/wrtc segfaults in
53 its static destructors on a natural process exit whenever nonstandard
54 media sources exist. The CLI, the speaker, and any future script that
55 touches wrtc must exit explicitly.
56- **Crash-safe outputs.** events.jsonl and chat.txt are appended per event;
57 WAVs flush (with header re-patch) about once a second; manifest.json is
58 written atomically (tmp + rename) at segment boundaries and every 30 s.
60## Testing
62`npm run build && npm run test:loopback` — full end-to-end over the real
63public relays (needs network): asserts the recorded WAV contains the 440 Hz
64tone (RMS + zero-crossing rate) and the chat message landed exactly once.
65Segfault-at-exit in a child process = some path bypassed `process.exit()`.
66For manual testing against real browsers, record a room and join it at
67https://concept-collection.github.io/commonroom/ — let the user do
68multi-person tests; don't try to automate browser media.