willowtreeapps / willowtreeapps/vocable-android

Spike: Head-tracking tuning — baseline gap assessment vs iOS

Open
#629 1 comment 0 reactions 1 assignee View on GitHub

@MicGon7 is already working on this.

Since Aug 5, 2026.

enhancement
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.