[LeeO86]

Stacked on #70. Rule: all generators get the same features. Android had no generator and no calibrator take; now it has both, behind the same JS API as iOS.

What this does

1. Android generator (Signal → Start test signal), same as the iPhone: fullscreen test picture (AVS3 fields, sync square and scale, AVS4 QR with test ID, Title and sender calibration), sound packets on the same plan, 1 or 2 events/s, Title, Subtitle, image, stable sender ID (phone- + core generator_test_id, install ID in the app preferences, version <versionName> (<versionCode>)), large "Stopped" after Stop, same stop reasons (background, audio focus lost, output changed, clock jump, missed deadline, 23 h), clock reference from the NTP check, screen brightness and wake.
2. Calibration mode (generateStyled(..., {mode: 'calibration'})): halves swap every 500 ms on the 60 Hz grid (core calibration_left_white / calibration_swap_frame), 4 ms 1.5 kHz beep 100 ms after each swap, red board outline in real millimetres, microphone records meanwhile, core display_calibration once a second, result or error back when the screen closes.
3. Calibrator take in the Android camera view: beginCalibrator('camera' | 'display') → PhoneAnalyzer::begin_calibrator, progress/result from poll_calibrator. The camera take re-runs the auto step and locks at the lowest ISO.
4. App: no platform branch any more for the wizard (supportsCalibrator no longer checks iOS); the Title placeholder says "Android" on Android.

Design choices

• Frame timing: Choreographer. Android 13+: postVsyncCallback → preferredFrameTimeline.expectedPresentationTimeNanos (like iOS targetTimestamp). Older: frame start + 2 display periods (estimate). The screen asks for a 60 Hz display mode. All on System.nanoTime.
• Audio: one streaming AudioTrack (48 kHz mono float, ~80 ms buffer), a thread writes 5 ms blocks, silence between packets. AudioTrack.getTimestamp maps an output frame to System.nanoTime (the Choreographer clock), so a packet for host time T starts at frame pos + (T − time) × 48000: placed to the sample, output latency already inside (iOS subtracts outputPresentationLatency instead). The start frame is recomputed with the newest timestamp each block until two blocks before it starts, so audio-vs-system clock drift does not add up and timestamp jitter cannot push it into the past. Underrun → stop (everything queued would play late). Why not AAudio/Oboe: the timestamp gives the same exact mapping from API 24 without native audio code or a new dependency; low latency is not needed because packets are planned 2.5 s ahead.
• Shared core: PhoneGeneratorPlan, AVS4 QR, render_picture / render_sync_foreground, calibration functions compile into libavsync-jni like the iOS Core_*.cpp (generator_jni.cpp mirrors AVSyncGenerator.mm). Text: JNI to Android's own text drawing with the bundled DejaVu Sans (GeneratorText.kt), as iOS uses CoreText; the font and icon come from the iOS resource folder (gradle assets.srcDirs).
• Screen: a fullscreen Dialog over the app (no new Activity / manifest entry); one view draws plate, fields, sync square and foreground, rotated in portrait like iOS.
• Image: Android photo picker (13+) or document picker, copy ≤ 512 px PNG in the app's files (GeneratorImageStore.kt), removed when replaced.

Tests

• Core ctest (core + clock): pass (after merging the latest Calibrator wizard: camera and screen calibration with the calibrator board #70).
• node --test mobile-app/src/*.test.mjs tests/web/*.test.cjs: 58 pass.
• Android JVM unit tests (:avsync:testDebugUnitTest, local docker): 14/14 pass, incl. new GeneratorTest (sample placement from a timestamp, block mixing, raster fit, calibration layout in mm).
• Host check of the JNI bridge (the same generator_jni.cpp + text_android.cpp built for x86_64, a JVM stand-in for GeneratorText): test-ID vector phone-985274814721, picture renders with all labels, title/subtitle, QR and fields; frame/position/named sequence right; synthetic click+beep train gives −37.93 ms for a planted −38 ms (24 pairs); silence gives the "No clicks heard" error.
• src/androidTest/PhoneGeneratorTest (needs a device/emulator, not run here; no KVM in the lab): stable ID test vector, picture 1280×720 with AVS4 QR read by ML Kit, host times, audio packet, frame/position, foreground, calibration pattern and silent analysis.
• Release APK (arm64-v8a) and the androidTest APK built locally in docker (steps of android-apk.yaml); APK contains libavsync-jni.so, assets/DejaVuSans.ttf, assets/icon.png. CI apk job on this PR: green.

Device test list (Android phone)

1. Signal → Start test signal: picture fills the screen, rotates in portrait, sync square animates, fields burst at each event; status shows frame skips ≈ 0 and an audio lead (typ. 20–100 ms).
2. Measure it with a second phone (iPhone or Android) or the container: QR read, testId phone-…, Title shown, AV offset stable over 2 min, no "deadline missed"/"dropout".
3. Stop → black picture with "Stopped"; Start again → same sender ID. Change rate → new ID.
4. Home button / screen off while running → stops with "Paused"; plug headphones → "Audio output changed".
5. Options: Title, Subtitle, Add image (photo picker), Change, Remove; image appears in the picture.
6. Settings → With calibrator shows on Android. Camera step with a board: exposure dark (lowest ISO), ring fills, result plausible; Save.
7. Screen step: halves at the bottom, outline about 22 × 66 mm (measure with a ruler), beep audible, mic hears click + beep, result closes the screen; Save; then a normal test signal shows "sender calibration ±x ms" in the status and the analyser shows it.
8. 90/120 Hz phone: does it switch to 60 Hz (skips stay ≈ 0)?
9. Android 12 or older phone (no expected-presentation API): compare AV offset with an Android 13+ phone or iPhone to check the two-period estimate.

Open risks

• Frame time before Android 13 is an estimate (+2 vsync); the real pipeline depth can differ per phone.
• AudioTrack.getTimestamp accuracy depends on the HAL (some report coarse or late positions); measured AV offset will show it.
• Some phones refuse 60 Hz and stay at 90/120 Hz: the 60 Hz plan still shows the right frame per vsync, but at 90 Hz frames alternate 1/2 vsyncs.
• Recording while playing: AudioRecord with UNPROCESSED/VOICE_RECOGNITION should not cancel the beep; to check on devices with aggressive processing.
• Calibrator camera take on phones without manual exposure: only exposure compensation, flash may saturate.

🤖 Generated with Claude Code

https://claude.ai/code/session_017ybuzgBaGxuB5UiaE8dRa4