[LeeO86]

What this does

Adds the calibrator wizard (Settings → With calibrator) for the calibrator board (contract docs/calibrator.md, hardware in #69). The clap calibration stays as it is.

1. Plug in – small animation: cable from phone to board.
2. Camera and microphone – lay the board LED-down on the rear camera. The camera and mic record the flash + click train, a ring of 20 dots fills up, the result is shown as "Camera vs mic: +12.3 ms ± 0.4". Save stores it as this phone's analyser calibration (same record and validity as the clap, method calibrator-pulse).
3. Screen and speaker – the phone's own generator opens in calibration mode: two halves at the bottom of the screen swap black/white every 500 ms, the speaker beeps 100 ms after each swap. The board clicks on each swap; the mic hears click then beep, so the mic delay cancels. "Screen vs speaker: −38.0 ms ± 0.3". Save stores it as the phone's sender calibration; the test signal then sends it in the AVS4 QR (method transponder).
   • "Measure a TV or monitor instead": the container shows the same pattern, the phone only listens; result shown, not saved.

How it is built

• Core C++ (core/include/avsync/calibrator.hpp): sound onsets (click vs beep by order and by 2.7 kHz vs 1.5 kHz energy), flash onsets from 32 row bands on the analyser's rolling-shutter row time, pairing, outlier rejection, uncertainty (standard error of the median), the pattern on the frame grid, the beep. iOS gives no readout time and exposes for the whole frame: the readout is fitted over the pulses (the board's clock drifts against the camera, so the flash lands on different rows).
• PhoneAnalyzer::begin_calibrator runs the camera take (and an audio-only take for an external screen); progress once a second, then the result.
• Same path as real sending: the calibration pattern is a mode of the generators, not a React view. iPhone: generateStyled(..., {mode: 'calibration'}) uses the same display link, layers, audio engine and player node. Container: AVSYNC_PATTERN=calibration (live key, Signal API pattern, web form "Picture"). Android has no generator: skipped (shared logic is in core; the Android CMake builds it).
• App: components/CalibratorWizard.js, pure logic in src/calibrator.mjs.
• Analysers subtract the sender calibration (decided): once in core, Pairer::set_sender_calibration, used by the phone session (iOS + Android), the container analyzer and the file analyzer. Result = measured − sender calibration; the raw value and the calibration stay visible: phone reading rawOffsetMs / senderCalibrationMs (Measure and Results show "raw … · sender calibration …", saved results keep both), events raw_av_offset_ms / sender_calibration_ms, /api/v1/measurement raw_offset_ms / sender_calibration_ms, web UI Input card "AV sync raw", file result summary.sender_calibration_ms / median_raw_av_offset_ms. Not calibrated: no change. No double count: the phone's own analyser calibration is still subtracted only in the app (liveView); the native session never gets it.
• Clear calibration clears both (decided): Debug → Clear calibration now asks first ("Clears both: the analyser calibration … and the sender calibration …"). There was no confirm before; this adds one.
• Results: Title as default nickname: a sender's default name is the newest AVS4 Title from its saved results (live Δ: the Title heard now), then the short ID. A nickname you set wins. "check" also marks a different sender calibration.

Contract changes (docs/calibrator.md, on this branch; no firmware change)

• Generator sound fixed: 4 ms beep at 1.5 kHz.
• Camera mode uses every paired pulse (start pulses too); the start pattern is not needed.
• Display mode does not need the swap times: the beep must come 0–450 ms after the click, so sound − picture between −100 and +350 ms (also covers a TV chain).
• Buzzer delay and display path difference: still 0 until measured.

Tests

• Core ctest: all pass (new test_calibrator.cpp: noise, missing pulses, stray sound, rolling shutter with known / estimated / fitted readout, 60 fps long exposure, slow screen, sensor mismatch per direction, external TV, failures, PhoneAnalyzer end to end). Synthetic accuracy about 0.03 ms.
• node --test mobile-app/src/*.test.mjs tests/web/*.test.cjs: 58 pass (sender calibration in the reading and saved result, Title nickname, check on sender calibration).
• Core: new test "the sender calibration from the QR is subtracted once, raw value kept"; the phone analyser end-to-end test now expects offset +32.5 (raw +20, sender −12.5).
• phone_generator.py: the fixture sends a sender calibration (−12.5 ms) at 2 Hz; events, /api/v1/measurement and /api/v1/status checked (corrected ~40 ms, raw ~27.5 ms); 1 Hz stays not calibrated.
• Linux MXL: new tests/integration/calibration_pattern.py (1080p50, 1080i25, 1080p59.94: swaps every 500 ms, beep 100 ms after each swap within 0.07 ms, simulated board gives 0.03 ms; live switch back to the test signal). phone_generator.py, settings.sh, api.sh, live.sh pass.
• iOS could not be compiled here (no Xcode). mobile-app/tests/native/generator-runner.mm got a sender-calibration QR check for the Mac.

Needs the Mac / a device

• Build iOS (Swift/ObjC++ changes in the camera view, generator controller, module, bridges; new Core_calibrator.cpp), npm run test:ios-generator, npm run test:ios-native.
• Device: the wizard screens and animations; generator calibration mode (pattern position, outline size, beep audible, mic take works in play-and-record); a normal test signal with a saved sender calibration shows it in the analyser.
• With a real board: camera take (exposure at lowest ISO, saturation), display take on iPhone and on a TV with the container pattern; compare the play-and-record vs playback output delay once.

Open questions

• Should the analysers subtract the sender calibration? Decided: yes, see above.
• Clear calibration: analyser only or both? Decided: both, with a confirm.
• Should the normal generator also run in play-and-record, so the audio session is bit-identical to the calibration?
• Android: add beginCalibrator to the camera view (the core is ready)?

🤖 Generated with Claude Code

https://claude.ai/code/session_017ybuzgBaGxuB5UiaE8dRa4