[LeeO86]

Stacked on #71 (feat/android-generator).

Problem

The phone test signal took the NTP clock check once at Start and stopped itself ("Clock reference expired") once that check was 5 minutes old, or sooner once the holdover passed the limit. So it always died about 5 minutes after the last check.

Fix (option 1: refresh while running)

• App (App.js): while the signal runs, every new clock check is passed to it with the new native call updateGeneratorClock(options). It is the same JS call on iOS and Android, and it takes the same options as generatorClockOptions. The check cadence is now one shared rule, clockCheckDue (src/time-reference.mjs), for measuring and for the signal: a check a minute before the 5-minute age limit, or (at most every 30 s) when the holdover would pass the limit within a minute. Before, the app checked only after the limit was passed, which was too late for a running signal.
• Core (PhoneGeneratorPlan::retime, clock_offset_ns, clock_reference_expired): this code is shared, so iOS and Android behave the same.
  • The timestamps move, not the timing. Only the TAI stamps (in the QR and in the audio packet) of events not queued yet change. Host times never move: frames stay on the display's 60 Hz grid, and the sound and picture of one event always carry the same stamp. Events already queued (up to 2.5 s ahead) keep their stamps. I chose this over moving the host times: a sub-frame shift of the picture would be rounded to the vsync grid and could put picture and sound up to one frame apart.
  • Slew rate 100 ppm: each event's stamp moves by at most 0.05 ms (2/s) or 0.1 ms (1/s) from the one before. A typical 1–5 ms difference between checks is taken up in 10–50 s. The largest accepted difference (the limit, 20 ms by default) takes 200 s, which is less than the time to the next check. To an analyser this looks like a source clock 100 ppm off, the same order as the 50 ppm holdover allowance. When QRs are missed and the analyser counts on from an older event, the error stays under 2 ms (20 s gap).
  • Too big a difference (new check further from the current stamps than the uncertainty limit): the signal stops with "New clock check is … ms off (more than the … ms limit). Tap Start for a fresh clock mapping." The next Start uses the new check. I chose stopping over slewing with a cap: a slew that long would leave the output outside the limit for minutes without saying so.
  • The signal only stops with "Clock reference expired" when no check got through in time (no network). The rule is the same as before and now lives in core.
• Native (iOS AvsyncGeneratorController.swift, Android AvsyncGenerator.kt): updateClock checks the new reference, slews from nextAudio (the first event not queued yet), and keeps it as the current reference. The status line still says "NTP UTC", now as "NTP UTC (check 42 s ago, adjusting +0.8 ms)" (the part of the slew still to go; nothing while there is none).
• Started before the first check (follow-up from the Mac session): pressing Start right after coming to the front, before the first NTP check finishes, used to keep the signal on device UTC for the whole run. Now the first accepted check switches it to NTP UTC, with the same 100 ppm slew from the device-UTC timestamps to the NTP ones (same core retime, iOS and Android identical). If the device clock is further from the check than the limit, it does not stop: it stays on device UTC and the status says "device UTC (clock check +35.0 ms off, more than the 20 ms limit)". A later check within the limit can still switch it. Once switched, the normal rules apply (refresh, expiry, stop on a big jump).
• What an analyser sees: the QR and the audio packet carry no device-vs-NTP mark (phone timestamps are always flagged estimated; the server reports source_reference: phone-utc-scheduled-output either way). So an analyser only sees the timestamps slew. The close result has clockApplied: true and the check in clockReference from the moment of the switch, not from the end of the slew.
• Unchanged: test ID / source ID; the "Phone clock changed" check (it compares the phone's wall clock with the host clock and does not use the NTP check). The calibration pattern uses no clock reference, so it is not affected. The container generator uses the host/PTP clock and does not use PhoneGeneratorPlan (checked by reading the code; no change).

Tests

• Core ctest (test_timecode.cpp), 2 new cases:
  • slew rate, refused big change, queued events unchanged, host times unchanged, same stamp for audio and video;
  • a 15-minute run with checks every ~3 min: no stop. Without checks: stops at 240.5 s, which is the rule for 8 ms + 240 s × 50 ppm.
  • start on device UTC: a check 35 ms off is refused (stays on device UTC, nothing changes); a later 12 ms check switches it, slewed at ≤ 50 µs per event, host times unchanged.
• node --test mobile-app/src/*.test.mjs tests/web/*.test.cjs: 60 pass, including clockCheckDue, a 15-minute JS run with and without network, and the first check reaching a signal started before it.
• Android (docker): :avsync:testDebugUnitTest (new clockCheckMapsToTheHostClock), :avsync:assembleDebugAndroidTest (new instrumented clockRefreshSlewsStampsNotHostTimes, compiled but not run), :app:assembleRelease: build successful.
• iOS: not compiled here. Swift parse check passed; the new Swift functions also type-check against stubs of the bridge. tests/native/generator-runner.mm has new retime/expiry checks.

Needs the Mac: build, then npm run test:ios-generator and npm run test:ios-native. Changed iOS files: AVSyncGenerator.h, AVSyncGenerator.mm, AvsyncGeneratorController.swift, AvsyncModule.swift, tests/native/generator-runner.mm.

Device test

1. Start the test signal on NTP UTC and leave it running for more than 10 min. It must not stop, and the "check … s ago" age must go back to a small number every few minutes.
2. Point an analyser at it during that time. Latency and AV offset should show no jumps; the "±… ms" value may move a little.
3. Turn on flight mode while it runs. It should stop with "Clock reference expired" within about 5 min (sooner with a poor check).

🤖 Generated with Claude Code

https://claude.ai/code/session_017ybuzgBaGxuB5UiaE8dRa4