docs: recording pipeline no longer buffers in memory (#176 item 3) #473

Merged

claude-bot merged 1 commit from docs/176-recording-pipeline-drift into main

2026-09-01 00:00:25 +00:00

claude-bot commented

2026-08-31 23:16:11 +00:00

Contributor

Item 3 of #176. Docs only.

Both CLAUDE.md files still described pre-#82 behaviour — PerUserPCMSink "accumulates … per user in memory", and "captures each Discord user's audio into a separate 48 kHz stereo PCM buffer for the session".

Capture has streamed straight to disk since #82. That is not a cosmetic inaccuracy: the entire reason a crashed session is now recoverable (#399) is that the audio was already on disk when the bot died. A reader trusting these docs would conclude the opposite, and would not understand why the recovery path can exist.

Corrected while here:

The tracks are headerless .s16le in the audio_temp root, not WAVs in a session directory. Changed in #321, because a gap-filled 6-hour capture is 4.15 GB and overflows WAV's 4 GB RIFF size field.
The bot-side pipeline gained steps the description never had: the .recording.json manifest, the .handed-off marker, and deleting each raw track once it converts.
Recorded the absolute-placement invariant in bot/CLAUDE.md. It was in the root CLAUDE.md and in PerUserPCMSink's docstring but not here — and it is the property that makes tracks mutually aligned without a mixing step, and makes #399's recovery possible at all.

The PerUserPCMSink module docstring, which #176 also lists as drifted, was already accurate — that part had been fixed since the issue was filed.

#176's other two items are addressed separately: item 2 (crash-resume salvage) is already done by #399, and item 1 (in-flight downsample) carries a data-corruption hazard on upgrade that needs its own issue. Both written up on #176.

🤖 Generated with Claude Code

Item 3 of #176. Docs only. Both `CLAUDE.md` files still described pre-#82 behaviour — `PerUserPCMSink` "accumulates … per user **in memory**", and "captures each Discord user's audio into a separate 48 kHz stereo PCM **buffer** for the session". Capture has streamed straight to disk since #82. That is not a cosmetic inaccuracy: the entire reason a crashed session is now recoverable (#399) is that the audio was *already on disk* when the bot died. A reader trusting these docs would conclude the opposite, and would not understand why the recovery path can exist. Corrected while here: - The tracks are headerless `.s16le` in the `audio_temp` **root**, not WAVs in a session directory. Changed in #321, because a gap-filled 6-hour capture is 4.15 GB and overflows WAV's 4 GB RIFF size field. - The bot-side pipeline gained steps the description never had: the `.recording.json` manifest, the `.handed-off` marker, and deleting each raw track once it converts. - Recorded the **absolute-placement invariant** in `bot/CLAUDE.md`. It was in the root `CLAUDE.md` and in `PerUserPCMSink`'s docstring but not here — and it is the property that makes tracks mutually aligned without a mixing step, and makes #399's recovery possible at all. The `PerUserPCMSink` module docstring, which #176 also lists as drifted, was **already accurate** — that part had been fixed since the issue was filed. #176's other two items are addressed separately: item 2 (crash-resume salvage) is already done by #399, and item 1 (in-flight downsample) carries a data-corruption hazard on upgrade that needs its own issue. Both written up on #176. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

claude-bot added 1 commit

2026-08-31 23:16:12 +00:00

docs: recording pipeline no longer buffers in memory (#176 item 3)

CI / Summarisation accuracy eval harness (stub provider) (pull_request) Successful in 48s

Details

CI / Bot/backend version sync (pull_request) Successful in 25s

Details

CI / Docker image build (pull_request) Successful in 19s

Details

CI / Frontend tests, audit, and build (pull_request) Successful in 1m31s

Details

CI / Bot tests and audit (pull_request) Successful in 1m21s

Details

CI / Backend lint (ruff) (pull_request) Successful in 1m0s

Details

CI / Backend migration, tests, and audit (pull_request) Successful in 5m11s

Details

416f2aa718

Both CLAUDE.md files still described the pre-#82 behaviour: "accumulates 48 kHz
stereo s16le PCM per user in memory", and "captures each Discord user's audio
into a separate 48 kHz stereo PCM buffer for the session".

Capture has streamed straight to disk since #82. The description mattering is
not cosmetic — the entire reason a crashed session is now recoverable (#399) is
that the audio was already on disk when the bot died, and a reader who believed
the docs would conclude the opposite.

Also corrected while here:

- The tracks are headerless `.s16le` in the audio_temp root, not WAVs in a
  session directory. That changed in #321, because a gap-filled 6-hour capture
  is 4.15 GB and overflows WAV's 4 GB RIFF size field.
- The bot-side pipeline gained steps the description never had: the
  `.recording.json` manifest, the `.handed-off` marker, and deleting each raw
  track once it converts.
- Recorded the absolute-placement invariant in bot/CLAUDE.md. It was documented
  in the root CLAUDE.md and in PerUserPCMSink's docstring but not here, and it
  is the property that makes the tracks mutually aligned without mixing and
  makes #399's recovery possible at all.

The `PerUserPCMSink` module docstring, which #176 also lists, was already
accurate — that part had been fixed since the issue was filed.

Docs only; no code change.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>