rbrooks/Quest-Board

Watch

Fork 0

[Recording] Log a per-speaker captured/expected ratio so a timeline regression is one grep away #327

New issue

Closed

opened 2026-08-25 20:38:46 +00:00 by claude-bot · 1 comment

claude-bot commented

2026-08-25 20:38:46 +00:00

Collaborator

Severity: MEDIUM. Found in the August 2026 session lifecycle review (#319).

Why

The dev stack cannot exercise the Discord bot at all (no token), so the capture fix is prod-only to verify end to end. It needs a tripwire that proves itself on the first real session without anyone inspecting audio.

The data has always been there and was never compared. close() already logs file_bytes per user (recording.py:236-240) and the upload already logs the wall-clock duration (recording.py:733-736) — into the same log stream, never diffed. Meanwhile the live dashboard has been publishing seconds_captured next to elapsed_seconds every two seconds since the feature shipped (services/recording_status.py:7,26,54). The smoking gun was on screen the whole time.

Proposed fix

In close(), log per user: expected_bytes = duration_s * 192000, written_bytes, and ratio. One grep after the first post-deploy session proves the fix (ratio ~1.0) or disproves it (ratio ~0.2). This requires passing duration_s or started_at into the sink — currently absent, which is itself telling.
Emit a WARNING when any ratio falls below 0.9.
Surface the existing seconds_captured vs elapsed_seconds divergence on the recording dashboard as a visible warning rather than two numbers a human has to compare.
Log the untapped per-SSRC library counters (jitter_synthetic_packets, opus_decode_ok/err, rtp_unknown_ssrc_dropped) available via vc.get_recv_diagnostics(), which the bot never surfaces.

Acceptance criteria

close() logs expected/written/ratio per speaker
A ratio below 0.9 logs a WARNING naming the speaker
The recording dashboard shows a visible warning when captured time falls behind elapsed time
get_recv_diagnostics() counters are logged at stop
Documented in docs/OPERATIONS.md as the post-deploy verification step for the capture fix

**Severity: MEDIUM.** Found in the August 2026 session lifecycle review (#319). ## Why The dev stack cannot exercise the Discord bot at all (no token), so the capture fix is **prod-only to verify end to end**. It needs a tripwire that proves itself on the first real session without anyone inspecting audio. The data has always been there and was never compared. `close()` already logs `file_bytes` per user (`recording.py:236-240`) and the upload already logs the wall-clock `duration` (`recording.py:733-736`) — into the same log stream, never diffed. Meanwhile the live dashboard has been publishing `seconds_captured` next to `elapsed_seconds` every two seconds since the feature shipped (`services/recording_status.py:7,26,54`). The smoking gun was on screen the whole time. ## Proposed fix 1. In `close()`, log per user: `expected_bytes = duration_s * 192000`, `written_bytes`, and `ratio`. One grep after the first post-deploy session proves the fix (ratio ~1.0) or disproves it (ratio ~0.2). This requires passing `duration_s` or `started_at` into the sink — currently absent, which is itself telling. 2. Emit a WARNING when any ratio falls below 0.9. 3. Surface the existing `seconds_captured` vs `elapsed_seconds` divergence on the recording dashboard as a visible warning rather than two numbers a human has to compare. 4. Log the untapped per-SSRC library counters (`jitter_synthetic_packets`, `opus_decode_ok/err`, `rtp_unknown_ssrc_dropped`) available via `vc.get_recv_diagnostics()`, which the bot never surfaces. ## Acceptance criteria - [ ] `close()` logs expected/written/ratio per speaker - [ ] A ratio below 0.9 logs a WARNING naming the speaker - [ ] The recording dashboard shows a visible warning when captured time falls behind elapsed time - [ ] `get_recv_diagnostics()` counters are logged at stop - [ ] Documented in `docs/OPERATIONS.md` as the post-deploy verification step for the capture fix

claude-bot added this to the v3.11.5 - Recording Clock Hotfix milestone

2026-08-25 20:38:46 +00:00

claude-bot added the

enhancement

bot

recording

labels

2026-08-25 20:38:46 +00:00

rbrooks referenced this issue from a commit

2026-08-25 22:24:18 +00:00

fix(bot): anchor per-speaker capture to a session wall clock (#320, #321, #322)

rbrooks referenced this issue from a commit

2026-08-25 22:24:18 +00:00

feat(frontend): warn on the recording dashboard when a track falls behind (#327)

claude-bot referenced this issue

2026-08-25 22:29:56 +00:00

v3.11.5 — per-speaker recordings never shared a session clock (#320) #418

claude-bot referenced this issue from a commit

2026-08-25 23:11:52 +00:00

Merge PR #418: v3.11.5 — per-speaker recordings never shared a session clock (#320)

claude-bot commented

2026-08-29 07:57:33 +00:00

Author

Collaborator

Shipped — closing as part of a v3.11.5 bookkeeping sweep.

bot/questboard_bot/cogs/recording.py:356, in close():

ratio is the capture tripwire (#327): with a correct session clock it must be ~1.0. Anything near 0.2 means tracks are speech-only again and the timeline has regressed. One grep after the first real session settles it.

It logs written_bytes / expected_bytes per speaker and raises an AUDIO_DIAG short_track warning below 0.9. services/recording_status.py:30 carries the live counterpart, distinguishing track position (silence included) from decoded speech.

The design intent held: the ratio is exactly the signal that made #320 diagnosable after the fact, and it is why a regression would now be one grep rather than another lost session.

Shipped — closing as part of a v3.11.5 bookkeeping sweep. `bot/questboard_bot/cogs/recording.py:356`, in `close()`: > ratio is the capture tripwire (#327): with a correct session clock it must be ~1.0. Anything near 0.2 means tracks are speech-only again and the timeline has regressed. One grep after the first real session settles it. It logs `written_bytes / expected_bytes` per speaker and raises an `AUDIO_DIAG short_track` warning below 0.9. `services/recording_status.py:30` carries the live counterpart, distinguishing track position (silence included) from decoded speech. The design intent held: the ratio is exactly the signal that made #320 diagnosable after the fact, and it is why a regression would now be one grep rather than another lost session.

claude-bot closed this issue

2026-08-29 07:57:56 +00:00

rbrooks referenced this issue from a commit

2026-09-06 09:13:55 +00:00

feat(webapp): a live recording panel on the session page (#386)

claude-bot referenced this issue

2026-09-06 09:13:57 +00:00

[Frontend] Fold the Recording Dashboard and SessionDetail's recording panel into one live-session screen #386

claude-bot referenced this issue

2026-09-06 09:14:11 +00:00

feat(webapp): one screen for a live session (#386, phase 8 of v4.3.0) #532

claude-bot referenced this issue