gramps/LlamaCasty
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat: signed A/V sync offset (−500..+500), negative advances by eating live stream head (OBS eat-head semantics)

Browse Source 
Positive offsets still delay the whole mix via the delay line (lip-sync fix);
negative offsets now ARM once at StartLive and drop |N| ms off the pipe's write
head so audio events land earlier when audio runs BEHIND video. Slider relabeled
AUDIO SYNC, Min −500, locked while live/recording (IsEditMode). LayoutStore and
VM clamp to −500..500.

OBS reference for eat-the-head negative sync: https://obsproject.com/kb/obs-studio/buffering-time (negative sync values pull audio earlier by discarding buffered player audio).

Test: StartLive_NegativeOffset_AdvancesAudio_ByDroppingTheStreamHead (6x0.9 head
must be eaten before 0.2 bed reaches the wire).
This commit is contained in:
Llama Chile Shop
2026-09-14 12:30:44 -07:00
parent 11a7af2dc0
commit b22d08eca6
12 changed files with 219 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files
TASKS/task-22-audio-sync-offset.md
+20
View File
@@ -17,7 +17,27 @@
### Design decisions
- **Global offset first** — one setting for all audio sources. Per-source is v1.1+.
- **Signed offset (2026-09-14)** — WIDENED from positive-only 0..500 to **−500..+500**.
> The "positive-only / advance needs video-side delay / out of scope" line below is
> RETIRED. Negative offsets now ADVANCE the audio by eating the head of the live stream
> (OBS's negative-sync behavior): `AudioMixer.StartLive` arms `_advanceSamplesRemaining`
> = |N| ms → samples, and `LiveLoopAsync` drops that many samples off the write head.
> Positive keeps using the `AudioSyncDelay` line live-reactive. Slider relabelled
> "AUDIO SYNC", `Min="-500"`, and **locked (`IsEnabled = IsEditMode`) while live or
> recording** — a negative advance can only be armed at go-live, so it must not move
> mid-session. Clamps: `Pre-viewModel` + `LayoutStore` ±500; `AudioSyncDelay` still
> clamps negative→0 internally (pure delay line, unchanged).
> **Provenance (2026-09-14): creator-directive** — asked for both directions after the
> ring-backlog fix surfaced the residual (audio can run late too: capture cards, BT,
> webcams). Regression test: `StartLive_NegativeOffset_AdvancesAudio_ByDroppingTheStreamHead`.
- **Positive-only (delay audio)** — the physically-correct direction (audio runs ahead of the video). True "advance" needs a video-side delay and is PERMANENTLY OUT with per-source sync (TASKS.md → "Out of product" — v1.x phrasing retired 2026-09-01).
- **Simple slider** — 0 to +500 ms, default 0. No numeric input needed.
- **Visual feedback** — "sync OK" status dot shows when an offset is dialled in.
### ❗ REQUIRED before 1.0 (creator directive 2026-09-14)
A **detailed user-doc tutorial** on the audio-sync feature (what -500..+500 means, the
clap-calibration recipe both directions, and that it locks while live). `docs/` currently
holds only the README image — the tutorial is unstarted. Add it to the 1.0/gold-pass checklist.