# HANDOFF — 2026-09-14 (AUDIO−VIDEO SYNC FIX SHIPPED: StartLive now clears the pre-live ring backlog)

## Branch / Commit State

`main` HEAD = `5ba4d70`. Ahead of origin by **27 commits**. Working tree **dirty**:
the sync fix is implemented + tests green below, HANDOFF/MyMistakes updated — NOT yet
committed. **NOT pushing** — the prior no-push ruling (transparency + audio-silence) is
clear on the first gate; the second was the sync issue, whose fix is now in the tree
but the user has not greenlit a push. On-board next: verify a take, then decide.

Heads-up for any reader: the previous HANDOFF (a62a283 era) described webcam/audio/
truncation fixes as **uncommitted** — that file was stale on arrival. They were
actually already committed:

- `724af14` fix: audio silence (idempotent `AudioSyncDelay.Configure`), webcam gray
  block (cbW/cbH default), truncated videos (SceneGraph split/static bake docs + FramePump probe)
- `5ba4d70` docs: audio-sync offset measured ~367ms w/ 300 offset → "set SyncOffsetMs=0"

Build was green (0 warnings) and 295 tests passing at the prior session end; no code
changed this session (analysis only).

## ✅ SHIPPED — pre-live capture ring backlog fix (2026-09-14)

**Root cause:** `AudioMixer.Start()` begins mic and loopback capture at **app startup**
for the level meters. The 2-second ring buffers (`_micBuffer` = 96k floats = 2.0s mono;
`_loopbackBuffer` = 192k floats = 2.0s stereo) fill continuously with pre-live audio.
`StartLive` → `LiveLoopAsync` drained from the ring's tail — the **oldest** sample —
so every recorded event landed ~2.0s late in the audio track (fixed lag, scaled with
time-since-app-launch, capped at ring depth).

**Fix:** `AudioMixer.StartLive()` now runs `_micBuffer.Clear(); _loopbackBuffer.Clear();`
immediately after the pipe starts, before the drain task runs — the in-flight ≤10ms
chunk loss is imperceptible and correct ("recording begins at go-live").

**Regression test (the ONE integration test for this change):**
`StartLive_DiscardsPreLiveBacklog_SoFirstAudioIsCurrent` in
`ytLive.Tests/AudioPipelineTests.cs` — saturates the loopback ring with stale 0.8
(simulated pre-live meters), StartLive, then emits fresh 0.2; asserts the wire carries
~0.2 (max < 0.3), failing loudly if the stale 0.8 backlog survived the clear.

**Test collateral:** the 3 existing pipe-emit tests pre-filled the rings BEFORE
StartLive (relying on the bug as a reservoir). Their emits now land right after
StartLive (post-clear, pre-connect — the pipe drops pre-connect writes, so this keeps
the ring primed for the client) with the 2026-09-14 comments updated. All passed.

Verified: `AudioPipelineTests` 26/26 green. Room-native build 0 warnings. Full gate
pending (verify.sh clean build + full suite + scope check).

### Read/Write semantics confirmed (AudioRingBuffer.cs)

Thread-safe via `_sync`: Write evicts oldest when full; Read returns from
`tail = (_head - _count + C) % C` — when full `tail == _head`, so every drained sample
is one lap behind the last write. `Clear()` is locked; it is the right seam.

**Root cause (confirmed two independent takes):** `AudioMixer.Start()` begins mic and
loopback capture at **app startup** for the level meters. The 2-second ring buffers
(`_micBuffer` = 96k floats = 2.0s mono; `_loopbackBuffer` = 192k floats = 2.0s stereo)
fill continuously with pre-live audio. `StartLive` → `LiveLoopAsync` drains from the
ring's tail — the **oldest** sample, which is the moment-of-go-live sample minus the
full ring depth — so every recorded event appears ~2.0s late in the audio track. The
lag is **fixed** for the entire recording and scales linearly with "how long the app was
open before you hit record", capped at the 2.0s ring depth (plus the configured sync
offset plus ~0.1s encoder pipeline).

**Read/Write semantics confirmed** in `AudioRingBuffer.cs` (thread-safe via `_sync`):
Write evicts oldest samples when full (`_count == _buffer.Length`); Read returns from
`tail = (_head - _count + C) % C` — when full, `tail == _head`, meaning every drained
sample is exactly one lap behind what was last written. `Clear()` exists and is locked;
it is the right seam.

**Only one Clear call exists** in the capture path: `RestartMic()` (AudioMixer.cs:132)
clears `_micBuffer` on device swap. **Neither buffer is cleared at `StartLive`** — this
is the bug.

**Taking:** the lag also explains the earlier 13:58 take that measured only ~367ms
with 300ms offset active: the app had just been restarted for that take, so the rings
were only partially pre-filled (lag = min(2.0s, time-since-app-launch)). Two takes
hours later (rings fully saturated) reproduce the full ~2.0s backlog consistently.

---

**Take 1** (ty-20260912-1923-0000-2.mp4, talking + 3 claps):
- Audio 17.25s, video 17.05s (1023 frames), no frame drops — NOT truncated.
- Per-clap offsets: +2.16 / +2.18 / +2.15s (audio later). Cross-correlation peak:
  **+133 frames (+2.217s)**, sharp and unique. Fixed offset, no drift.
- DB: `Audio.SyncOffsetMs = 300` (not 0 as the 5ba4d70 commit message claimed —
  the write never actually landed).

**Take 2** (ty-20260914-1104-0000-2.mp4, clean clap test):
- Audio 22.31s, video 22.10s (1326 frames), no frame drops.
- Audio clap peak at **14.04s**; video motion peak at **11.93s** (yavg 2.75 vs
  background ~0.1–0.5). Offset: **+2.11s** — confirms the same mechanism.
- Tiny pre-clap blips at 0.2/1.5/4.5/13.5s are faint artifacts (< 100 RMS);
  the 11617-RMS clap is unambiguous.

**Theory of the "cut off at the end":** audio events land ~2s late; when the video
ends the audio track is still playing the final 2s of real-time content, giving the
impression of a cut. The audio track's slightly longer duration (17.25 vs 17.05;
22.31 vs 22.10) is the tail of that delayed signal — real audio outlives the
pump-stopped video.

**Theories RULED OUT by data:**
- ❌ Frame truncation / slow full-render — video is real-time; frame counts match
  wall-clock (FramePump log: 301/300 per 5s, dropped 0, avg render 14ms).
- ❌ Named-pipe-connect drop — would *shorten* audio (events earlier), opposite sign.
  Pipe connected near-instantly in both takes.
- ❌ AudioSyncDelay alone — capped at 0..500ms; 300ms is a subset, not the whole.
- ❌ Audio drift/resampler rate — offset is constant, not growing.

## Open threads

- **Audio-silence verification** — FIXED code (idempotent `Configure`, committed
  `724af14`); the 19:23 take had real peakMix. Final user confirmation still pending.
- **Audio sync offset DB value** — `Audio.SyncOffsetMs = 300` (the "set to 0" write
  in 5ba4d70 never actually landed). Fix for the ~2s ring backlog is now SHIPPED (local,
  uncommitted). Next: re-record the clap pattern, run the cross-correlation recipe → expect
  residual ≈ 400ms (300ms configured sync + ~100ms pipeline); then optionally zero the
  slider to hit ~100ms.
- **Truncation with DYNAMIC scenes** — proven mechanism + probe in place; static
  scenes full-length. 19:23 take confirms dynamic scenes hold ~60fps (no truncation)
  but with 30ms stall cadence.
- **Webcam MJPG missing**, **web capture ~10–14Hz**, **layer SortOrder not persisting**
  — queued, unchanged.

## Landmines

- testhost shares startup.log — filter by time.
- `cmd.exe /c "taskkill /F /IM ytLive.exe"` (WSL form double-slashes mangle) before rebuilds.
- Build/tests: Windows dotnet host (`/mnt/c/Program Files/dotnet/dotnet.exe`). 0 warnings.
- ffmpeg/ffprobe: `/mnt/c/Program Files/Krita (x64)/bin/ffmpeg.exe` with Windows paths.
- **`Audio.SyncOffsetMs` currently = 300 in the DB** (contradicts the "set to 0"
  line in 5ba4d70; the write likely never happened). Non-zero offsets still depend on
  the idempotent `Configure` guard to avoid the silence bug.
- `MyMistakes.md` → Recipes registry now has the **audio/video sync measurement
  recipe** (claps + cross-correlation) — grep before re-deriving.

## Next step

**Verify the shipped fix:** re-record with the same clap pattern and run the
cross-correlation recipe from `MyMistakes.md` → expect offset ≈ 400ms (300ms configured
sync + ~100ms pipeline) with a `SyncOffsetMs=300` DB value, or ~100ms with the slider
zeroed. Then commit this session's work (StartLive clear + regression test + docs) and
decide with the user whether the no-push ruling is lifted.