fix(audio): a sync offset is saved the moment it changes

Both offsets rode the debounced layout save, so a value set seconds before the app closed was lost
without a word. That is what happened to the -130 ms offset on 2026-11-12: two clips were measured
against a setting that was not in force, the numbers disagreed by ~65 ms, and the disagreement was
blamed on the audio path.

Setters now write the row immediately (two tiny rows), keeping ScheduleSave for the rest of the
layout. AudioSyncSettingsTests gains the regression: set both offsets on a view model and read them
back through a fresh store with no debounce flush.

MyMistakes records the general shape — "a setting that didn't stick" is almost always ScheduleSave —
with the check list and the two related rules: offsets never ship with a non-zero default, and
scripts/avsync.py only resolves ~50 ms, so below that the creator's judgement wins.

677 pass, 0 warnings. Scope justification: Assets/starting-background.jpg is outside this unit — the
creator's replacement art, still awaiting their visual check.
This commit is contained in:
2026-11-12 14:21:48 -08:00
parent 1eb04597d1
commit cc75212997
3 changed files with 63 additions and 0 deletions
+31
View File
@@ -35,6 +35,37 @@ max 200.
## 🔬 Recipes registry
### A SETTING THAT "DIDN'T STICK" — CHECK THE DEBOUNCE FIRST (RECIPE, 2026-11-12)
**Symptom:** a value is set in the UI, behaves correctly for one session, and is gone after a
restart. It looks like a wiring bug in the control; it is almost always `ScheduleSave()`.
**Cause:** `MainViewModel.ScheduleSave()` restarts a debounce timer that later calls `Save()`, which
writes the whole layout. Anything changed in the last few seconds before the app closes is lost —
and none of it is logged, so the next session reads a value the creator never chose.
**Quick fix:** for anything small and decisive (a sync offset, a toggle the creator just clicked),
call the `_layoutStore.Save…()` method **in the setter itself**, before `ScheduleSave()`. Two rows
cost nothing; a lost setting costs a whole reproduce-and-test cycle. Live example:
`MainViewModel.Audio.cs` → `AudioSyncOffsetMs` / `MicSyncOffsetMs`.
**Check list when a remembered setting misbehaves:** grep the property for `ScheduleSave`, confirm a
direct save exists, then reproduce with a *restart* (not just a new session) before debugging deeper.
**Bit us:** the lip-sync offset. `Audio.SyncOffsetMs` was set to −130, lost on close, and two clips
were measured against a setting that was not in force — the numbers disagreed by ~65 ms and the
disagreement was blamed on the audio path.
### A SYNC OFFSET IS NEVER A PRODUCT DEFAULT (2026-11-12)
**Mistake:** `MicSyncOffsetMs` shipped at **175 ms** because that suited one C920 on one desk. It
shifted every creator's voice to correct one machine and hid whether a desync was the app's fault.
**Rule:** offsets ship at 0 and are opt-in. `AudioSyncSettingsTests` pins it. And the tool that
measures them, `scripts/avsync.py`, varies **±35 ms between clips** on identical settings — it can
answer "is this 100 ms out?" but never "is this 20 ms out?". Below ~50 ms the creator's judgement is
the better instrument, so stop tuning rather than chasing the tool's noise.
### A LOOSE FILE IN `Assets/` IS NOT AN ASSET — THE CSProj LIST IS (RECIPE, 2026-11-04)
**Problem:** four untracked `Assets/llamacasty-*` exports sat in the tree for days, reported in