CLAUDE.md#

Tips for future agents working in this repo — a Node CLI that joins a commonroom call as a muted, visible participant and records every other participant's audio (one WAV per participant) plus the room chat. Read commonroom's CLAUDE.md first: this tool speaks its protocol verbatim, and the protocol is documented there.

Architecture#

src/
  identity.ts   ported from commonroom; EPHEMERAL keypair (no localStorage)
  nostr.ts      ported near-verbatim (Node >= 22 global WebSocket); close() added
  peer.ts       ported, adapted to @roamhq/wrtc; receive-only media (see below)
  wav.ts        incremental WAV writer (buffers ~1 s, re-patches header sizes)
  recorder.ts   the heart: presence, mesh, control channel, audio sinks, files
  transcribe.ts `transcribe` subcommand: per-WAV ASR + merged transcript.md
  cli.ts        arg parsing, subcommand dispatch, signal handling, log lines
  test/
    speaker.ts         synthetic participant: sine tone + one chat message
    loopback.ts        test: recorder + speaker in a random room -> tone + chat
    transcribe-test.ts test: fabricated 2-speaker recording dir (JFK sample)
                       -> transcript ordering + words; uses --model tiny

Key design decisions#

• Protocol-identical participant. Same announcements, per-peer signaling topics, deterministic initiator (smaller peer ID), control-channel messages (hello/mute/chat/bye), stalled-connection retry, room-full handling, and the soft cap of 8 — the recorder counts toward it. Don't invent protocol; if the browser client changes, port the change.
• Receive-only media, but symmetric-looking. Outgoing tracks are wrtc RTCAudioSource/RTCVideoSource placeholders that never produce data (= a fully muted participant). The VIDEO m-line is negotiated sendonly from our side (as initiator via addTransceiver(track, {direction:'sendonly'}); as answerer by flipping the transceiver direction after setRemoteDescription) so browsers never send us video — saves bandwidth and decode CPU. Audio stays sendrecv.
• Recording gates on first non-zero frame. Before the first RTP packet, RTCAudioSink delivers all-zero frames at a PROVISIONAL sample rate (16 kHz observed), then switches to the real one (48 kHz) — opening the file eagerly yields junk stub segments. A never-unmuting participant produces no file. A mid-stream format change (rare) closes the segment and starts a new one.
• Wall-clock silence padding. If the sink stalls > 1 s (network gap, DTX), silence is inserted so sample position keeps tracking elapsed time — the manifest's segment startedAt plus the file offset IS the meeting timeline.
• connectionState flaps. wrtc can pass through 'connected' several times while ICE settles; the connect handler must be idempotent or hello/notice get re-sent per flap.
• Bye cooldown (3 s). An announcement published just before a peer's bye can arrive just after it and would trigger an instant reconnect (and a stub recording); after a bye we ignore that peer's announcements briefly.
• Every exit path MUST end in process.exit(). @roamhq/wrtc segfaults in its static destructors on a natural process exit whenever nonstandard media sources exist. The CLI, the speaker, and any future script that touches wrtc must exit explicitly.
• Crash-safe outputs. events.jsonl and chat.txt are appended per event; WAVs flush (with header re-patch) about once a second; manifest.json is written atomically (tmp + rename) at segment boundaries and every 30 s.
• Transcription needs no alignment step. The silence padding means an ASR timestamp within a segment plus the manifest startedAt is the wall-clock time; transcribe.ts just merges utterances with chat/join/left events and groups adjacent same-speaker utterances (< 3 s gap) into turns. ASR engines are probed (faster-whisper via an embedded python3 stdin script — VAD on, which also skips the padded silence — then whisper-cli, then whisper); raw ASR is cached per WAV in <dir>/asr/. cli.ts imports recorder.js LAZILY so transcribe works where the wrtc native module doesn't load.

Testing#

npm run build && npm run test:loopback — full end-to-end over the real public relays (needs network): asserts the recorded WAV contains the 440 Hz tone (RMS + zero-crossing rate) and the chat message landed exactly once. npm run test:transcribe — real-speech transcription test (downloads the whisper.cpp JFK sample + the tiny model on first run). Segfault-at-exit in a child process = some path bypassed process.exit(). For manual testing against real browsers, record a room and join it at https://concept-collection.github.io/commonroom/ — let the user do multi-person tests; don't try to automate browser media.