willowtreeapps / willowtreeapps/vocable-android
Spike: Head-tracking tuning — baseline gap assessment vs iOS
@MicGon7 is already working on this.
Since Aug 5, 2026.
- Dominant language
- Kotlin
- Stars
- 127
- Forks
- 21
- Avg merge
- 16m
- Merged PRs (30d)
- 4
Description
Why
This was initially framed as a straightforward parity checklist item (iOS has a tuning UI, Android doesn't), but that's contested: Chris Stroud flagged it would need a spike just to assess the baseline, since if Android's tracking is genuinely lacking versus iOS, the real fix might be reworking the smoothing engine into an actual PID controller — not just exposing today's hardcoded constants as sliders. Separately, iOS's own tuning UI turned out not to be reachable in any shipped build (verified independently) — this isn't the production gap it first appeared to be.
Baseline: there is no PID/tuning logic on Android at all today — gaze smoothing is a single hardcoded Vector3.lerp plus two hardcoded scaling constants in FaceTrackingViewModel.kt. See Documentation/head-tracking-tuner-comparable-apps.md for how two real, shipped Android apps in this same category (Eva Facial Mouse, Google Project Gameface) solve this problem — both as ordinary user-facing settings, not a hidden debug tool.
Scope
Research-only spike. No shipped code expected — output is a documented recommendation. Everything past this spike is contingent on its outcome and is not yet scoped as issues (see Out of Scope).
Acceptance Criteria
- Side-by-side qualitative comparison of Android vs. iOS gaze responsiveness (jitter, overshoot, lag, corner reachability) documented on comparable devices
- iOS's actual PID-based smoothing implementation documented well enough to state what genuine technical parity would require
- Comparable Android apps (see reference doc) reviewed as an alternative model, not just iOS
- Written recommendation delivered to Product, one of: (a) build a debug-gated engineering tuning tool, (b) the real gap is the smoothing algorithm itself — scope as its own initiative, (c) no meaningful product-level gap, no further action, (d) build a real user-facing settings screen (Eva/Gameface pattern), not a debug tool
- Product sign-off received on a specific path before any further engineering issues are opened
Out of Scope
- Any implementation work — deliberately not yet broken into issues, since it depends entirely on which of the 4 outcomes above Product picks. Once decided, that becomes a fresh, short breakdown rather than pre-built speculative issues.
Links
- Reference:
Documentation/head-tracking-tuner-comparable-apps.md - Related (differently scoped): #109 ("Calibration" — end-user recalibration, not this QA/engineering tuning surface)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.