Tekan Buddy 🏃

An AI running trainer for your iPhone, built as a mobile web app. Pick a persona — Angry Ah Beng and Ah Lian (scold you in Singlish), Coach Christine (relentless encouragement), and two more — press Start, and get coached over your own music.

Features

• Personas — five, each with its own voice, 227-phrase library and attitude. Ah Lian is Ah Beng's equal in vulgarity, with a running joke about her useless ex — never named, just "my ex" — that she brings up whenever you slack off.
• Per-persona voice settings — speed (applies at render time) and playback level (applies at play time, no re-render), both in admin. Every voice ships at 100%; the level control only pulls one down, for a voice that ever renders hot. It covers every path a phrase can take: pre-rendered clips, live-generated ones, the device fallback, the admin preview and the post-run summary line.
• GPS run tracking — time, distance, live pace, per-km splits.
• Start-line intros — a ~10-second opening monologue when you press Start: freshly generated by Claude when keys are configured (with a 2.5s fallback race so there's never dead air), otherwise rotating through six pre-written intros per persona, with the rotation remembered between runs.
• Coach engine — encouragement (positive or abusive, per persona), pace reactions when you slow down or speed up, km milestone callouts, and random anecdotes / facts / nuggets on a schedule. Pace reactions fire often, so each persona carries 16 "too slow" and 12 "flying" lines and roughly a third of them are generated live instead.
• Chatter dial, mid-run — the same control as on the setup screen sits under the coach bubble during a run. Moving it rescales whatever interjection is already pending, so turning your buddy up is audible straight away rather than after the next one finally comes round. Hidden while the screen is locked.
• Km markers in the persona's voice — every kilometre from 1 to 21 has its own pre-rendered line, and the pace hand-off ("and that last kilometre took you…") is pre-rendered too, so the only thing the device voice ever reads is the figure itself. The pace quoted is the split for the kilometre just finished — not the whole-run average — taken from the recorded split, which already excludes paused time.
• Pre-rendered voice library — phrases rendered with ElevenLabs. On first launch after deploy, the app renders any missing phrases itself through the server's ElevenLabs key into Vercel Blob, with an on-screen progress bar — no manual step needed. Falls back to on-device speech synthesis for phrases not yet rendered, so the app works with zero API keys.
• Stale-audio detection — every render drops a marker blob whose pathname carries a fingerprint of the exact words it voiced, sweeping that phrase's superseded markers so the store stays at one marker per phrase. Reword a phrase without changing its id and the gap-filling pass would skip it forever, since a file already sits at that path; instead admin marks the row "old" and offers to re-cut just the affected phrases. Phrases voiced before this existed carry no marker and are left alone rather than guessed at, so the warning only ever appears on a mismatch that can be proven.
• Live phrase generation — mid-run, the coach asks the server for brand-new material (Claude Sonnet 5 writes the line in-persona, ElevenLabs voices it), fed with live context: current weather, the neighbourhood you're running through, your pace and speed, distance, km markers, elapsed time, and time of day. Half of km-marker callouts and anecdotes, and a quarter of encouragements, are generated live when keys are configured.
• Music over-dub — deep-links into Spotify or Apple Podcasts; the trainer speaks over your music using Safari's Audio Session API, which ducks the music under each line and lets it come straight back.
• Keep-alive audio session — a near-silent loop keeps Safari running the app (timers + GPS) when the phone is locked.
• Always-on display mode — dim, AMOLED-friendly orange readout with wake lock, for armband runners.
• Sleeve lock — 🔒 in the run screen's top bar blocks every control so an arm sleeve can't pause or end your run; unlock with a deliberate 1.5s hold.
• Put it away and go — after a manual pause, one tap locks the screen and hands the resume to whatever evidence the mode has. Outdoors the clock restarts itself the moment you move off, back-dated to that fix (~1s with Doppler). On a treadmill there is no GPS to watch, so it counts down ten seconds instead.
• Pause / resume cues — every transition, manual or automatic, buzzes the phone and plays a short two-tone cue (falling for a stop, rising for a go) ahead of whatever the trainer says about it. iOS Safari has no Vibration API, so on an iPhone the cue is the part that actually lands.
• Auto-pause — the clock freezes about two seconds after you stop moving and picks up about two seconds after you start again, both back-dated to the moment movement actually turned. Your buddy announces each transition out loud, since the phone is in a sleeve, and starts commenting if you stand around too long — escalating each time.
• Delayed start — a 20-second countdown so you can press Start, get the phone into the sleeve and set yourself. The screen locks immediately and your buddy calls out ten and five seconds. GPS warms up during the count, so the run begins on a settled fix.
• Target checkpoints in the persona's voice — the preset targets (3/5/10/12/14 km and 15/20/30/45/60 min) have a known remaining figure at every checkpoint, so all 10 callouts per target are pre-rendered with the distance or time baked in. A target outside the presets falls back to a generic line plus the figures read by the device.
• Openers that know the conditions — a pre-rendered line chosen live from the clock and the weather: a pre-dawn start, the afternoon heat, the rain you came out in anyway.
• Push-to-talk — tap the mic, say something, and the trainer answers in character.

Accounts & run history

Optional, like everything else: set GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and AUTH_SECRET (see .env.example) and the app opens with a choice — Continue with Google or Run as guest. Guests get exactly the pre-accounts app, remembered so the question is asked once. Signed in, the app opens on a home screen: Get Ready to Run on top, and below it a card for every saved run — tap through for distance, average pace, moving time, total elapsed time, fastest split, the route drawn on real OpenStreetMap tiles (toned to match the paper stock), and a kilometre-split bar chart (longer bar = faster split, fastest in the accent). Runs save automatically at the finish line; anything under a minute or 50 m is dropped as a pocket-start, and a run can be deleted from its detail page behind an explicit confirmation.

Signing in also gives the trainer a memory: the run list is digested into last-run figures, personal bests and recency (lib/history.ts — one blob listing, no body fetches), and rides into every improvised line. Expect the intro to notice a four-day gap, or a mid-run remark when the pace closes in on a best. The shareable end-of-run card carries the same depth — route, headline numbers, a kilometre-splits strip with the fastest split called out, where the run happened, and the coach's closing line.

The account page also holds the runner's own stats — age, gender (female, male, or the "—" of not saying), height and weight, editable in either kg·cm or lb·in (stored metric; the toggle is just a display preference that follows the account). BMI is derived live from the two fields and shown read-only, together with its band under the Singapore Heart Foundation's Asian-population classification (underweight < 18.5, normal to 22.9, overweight to 27.4, obese from 27.5) — the bands are baked into the app, no lookup involved. When they're filled in, the trainer gets them alongside the live run stats and may weave a personal touch into its improvised lines — your name, mostly, with age or build as occasional seasoning. Guests have no account page fields; everything stays anonymous.

The admin screen (gated to ADMIN_EMAIL) also carries a user directory: every account that has signed in, with run counts and last-seen, and a click-through to each user's saved runs showing the trainer they picked and the run's configured target (distance, treadmill time, or free run). Profiles are written at sign-in, so accounts predating the registry appear on their next login.

Storage is the same Vercel Blob store as the voice library — one JSON per run under an HMAC-derived per-user prefix, with the card's summary encoded in the pathname so listing a history fetches no file bodies. Auth is the classic Google authorization-code flow with a signed HttpOnly cookie — no auth library, no database.

Running locally

npm install
npm run dev

The app is fully functional with no API keys (library phrases + on-device TTS).

npm test runs the simulation suites — the GPS tracker against jittered fake fixes, the voice engine against iOS-style interruptions, the stale-audio bookkeeping against a lagging CDN. npm run test:ui drives a production build in a real browser. Every scenario in there earned its place by catching a real bug; see tests/README.md.

Environment variables (optional, unlock the good stuff)

Variable	Purpose
ANTHROPIC_API_KEY	Live phrase generation + push-to-talk replies (Claude Sonnet 5)
ELEVENLABS_API_KEY	Voicing generated phrases, and batch-rendering the library
ELEVENLABS_VOICE_AHBENG	ElevenLabs voice ID for Angry Ah Beng (falls back to a stock voice)
ELEVENLABS_VOICE_AHLIAN	ElevenLabs voice ID for Ah Lian (falls back to a stock voice)
ELEVENLABS_VOICE_COACH	ElevenLabs voice ID for Coach Christine (falls back to a stock voice)
ELEVENLABS_VOICE_FLIRTY	ElevenLabs voice ID for Coach Cassie (falls back to a stock voice)
ELEVENLABS_VOICE_LOANSHARK	ElevenLabs voice ID for Ah Long (falls back to a stock voice)
BLOB_READ_WRITE_TOKEN	Auto-injected when you add a Vercel Blob store — enables first-launch in-app library rendering
ADMIN_PIN	Protects the admin page and credit-spending endpoints (unset = open, for local dev)
ADMIN_EMAIL	Hides the ⚙ Admin link from everyone but these Google accounts (comma-separated; needs sign-in configured)
DEFAULT_PLAN	The plan for accounts with none pinned: full (default, pre-launch) or free (once the subscription is on sale)
REVENUECAT_SECRET_KEY	RevenueCat secret API key — lets the server read who is subscribed (the sync route and the webhook)
REVENUECAT_WEBHOOK_SECRET	The Authorization value you set on the RevenueCat webhook pointing at /api/plan/webhook
NEXT_PUBLIC_SUPPORT_EMAIL	Shown as the contact on /privacy (without it the page points at the App Store listing's support link)
NEXT_PUBLIC_REVENUECAT_IOS_KEY	RevenueCat public iOS SDK key — the shell configures the purchases plugin with it (public by design)

Weather (Open-Meteo) and reverse geocoding (BigDataCloud) are keyless — the location/weather-aware phrases need no configuration.

Rendering the voice library

Set the two persona voice IDs in lib/personas.ts to voices in your ElevenLabs account (for Ah Beng, a cloned Singlish voice is chef's kiss), then:

ELEVENLABS_API_KEY=... npm run generate-library

This renders every un-rendered phrase into public/audio/<persona>/ and writes a manifest.json per persona. It's idempotent — add phrases to lib/phrases.ts and re-run to top up the library. Commit the MP3s (or put them on Vercel Blob and adjust the URL in lib/coach.ts).

Deploying to Vercel

Push this repo, import it in Vercel, add the two env vars. That's it — the API routes run as serverless functions.

iPhone setup tips

• Open in Safari and Add to Home Screen for the full-screen app feel.
• Flip the ringer switch on — ambient web audio respects the mute switch.
• Start your music/podcast first, then hit Start Run.
• Keep the phone unlocked-ish: the always-on mode (moon button) dims the screen while keeping GPS and the coach alive.
• Locking the screen or switching apps (to take a photo, say) silences the trainer while you're away — iOS suspends mixable web audio in the background, and there's no way around that without taking your music over completely. The run picks straight back up when you return; GPS fixes and coach lines during those seconds are simply lost.

Architecture notes

• lib/coach.ts — decides what to say and when (milestones > pace events > anecdotes > encouragement, with cooldowns and no-repeat shuffling).
• lib/audio.ts — audio session management (ambient ↔ transient for music ducking), keep-alive loop, MP3 playback with TTS fallback, wake lock.
• lib/geo.ts — watchPosition with a Kalman position filter, Doppler-speed distance integration, accuracy-scaled jitter/teleport gates and rolling 60s pace. See "GPS accuracy" below.
• lib/enviro.ts — keyless weather (Open-Meteo) + reverse geocoding (BigDataCloud), fetched from the first GPS fix, refreshed every 30 min.
• lib/phraseCategories.ts — which phrase categories the generator can top up, what each one is for, and why the rest are fixed. Shared by the admin screen and the expand endpoint so they can't disagree.
• app/api/phrase — Claude (claude-sonnet-5) writes one line in-persona from the live run stats; ElevenLabs voices it; both degrade gracefully.

Design system

Shared with marktan.ai: warm newsprint ground, rust accent, near-square corners, Fraunces for figures and headlines, Newsreader for prose, JetBrains Mono for the wide-tracked uppercase labels that carry the structure. Fonts are self-hosted via next/font rather than linked from Google, because this is an installed PWA that runs outdoors on unreliable mobile data.

Two grounds, one system. :root is paper — setup, summary, admin. .theme-ink inverts only the ground and ink tokens for the live run screen; the accent, the type and the radii carry across untouched, so it reads as a mode rather than a second theme. The run screen is dark on purpose: a full-brightness cream screen glares on a night run and costs real OLED battery over an hour. The always-on sleeve display stays true black for the same reason, only more so.

Two things to know before editing:

• color is declared on .app, not only on body. Inheritance passes down the computed colour, and body sits outside .theme-ink — declare it only on body and the entire run screen inherits paper-dark ink onto an ink-dark ground.
• --accent is the brand rust and owns all chrome and actions. A trainer's own colour is --persona, injected per-run, and is used only where it marks which trainer this is — the avatar tint, the selected card's edge, the route line on the run card.

GPS accuracy

A phone standing still still reports a position that wanders, and because that wander is a displacement it's always positive — sum it up naively and a stationary phone quietly clocks up a kilometre. Four things guard against it:

1. Doppler speed is the authority on movement. coords.speed comes off the carrier phase, not from differencing positions, so it reads ~0 while you stand still. Below STATIONARY_MPS (0.6 m/s) nothing accumulates at all.
2. Positions are Kalman-smoothed before they're used for anything — uncertainty grows by KALMAN_Q m/s between fixes, so a tight fix pulls the estimate hard and a loose one barely moves it.
3. The jitter gate scales with the accuracy circle. A step must beat both 6 m and half the reported accuracy; anything smaller leaves the anchor where it is instead of dragging it along with the noise.
4. Distance is the sum of gated chords between those smoothed, accepted fixes — the same polyline the route stores. Steps are blocked entirely while Doppler says stationary, which is what stops the unsigned-noise creep the gates alone can't fully close.

Plus: a 4 s warm-up discard (cold-start fixes are the worst a receiver ever produces), maximumAge: 0 so a cached fix is never replayed as new, and a 30 m accuracy ceiling for anything touching the route.

Targets come in three flavours (Setup → Target): a distance goal (3–15 km presets plus the half marathon) with percentage checkpoints and a talked run-in, a time goal (treadmill mode — no GPS at all), or a target pace (outdoor only) — no checkpoints, the coach just keeps checking you against the number every couple of minutes: praise while you hold it, a push when you're more than ~4% over it, silence in the narrow band between so a marginal pace doesn't get flip-flop commentary. Km markers fire in every mode.

Distance-target runs also carry a world-record moment: at the exact elapsed time where the marathon world-record holder — Kelvin Kiptum (2:00:35) for men, Ruth Chepngetich (2:09:56) for women, chosen by the account's gender with male as the default — would have finished your target at their record pace, the trainer drops a pre-rendered line: who they are, what they ran, and that they'd be crossing your finish line right now. One line per persona per preset distance per record holder, times baked into the recordings (lib/records.ts documents what to update if a record falls). On 5 and 10 km targets there's a second, earlier moment: the US high school national record holder's literal race time — Daniel Simmons' 13:26 and Jane Hedengren's 14:58 for 5 km, Rudy Chapa's 28:33 (1976!) and Mary Shea's 32:53 (1979) for 10 km — with Ah Beng and Ah Lian at their most merciless, since you've just been beaten by a schoolkid. On a male 10K, Chapa's 1976 time pips Kiptum's extrapolated split by two seconds, so the schoolboy finishes first and both lines fire back to back.

Once per run — somewhere in minutes 5–12 — a second trainer barges in and the two argue for about 25 seconds: a fresh four-line script written live from the run's actual stats (/api/cameo), each line voiced in its own speaker's ElevenLabs voice. Never from a library, never the same twice, and silently absent when the API keys aren't configured — a cameo that half-happens is worse than none, so all four lines render or none play.

Simulated against synthetic noise, this holds a 10-minute stationary phone to 0 m of phantom distance with Doppler (13 m without), and tracks running, walking, intervals, tunnels and Doppler dropouts to within 2.5% of truth.

The chord engine (and the Doppler engine it replaced)

Distance used to be integrated from Doppler speed (a trapezoid over coords.speed), on the argument that speed noise is symmetric where position noise is not. A real 10 km run falsified it: the tracker's own accepted position track measured 10.02 km while the trapezoid credited 9.74 — Doppler dips at turns and gait noise integrate low, and the shortfall was a consistent ~2.5–3% across runs. So the chord sum over accepted fixes is the engine, full stop — a field run after the switch matched an Apple Watch to 0.6%, which retired the rollback toggle. Doppler is demoted to the three jobs it is genuinely best at: declaring the phone stationary, driving the live speed display, and crediting distance while good position fixes are absent — an urban canyon doesn't freeze the counter, and the first chord after re-acquire is reduced by whatever the outage already earned so no stretch counts twice. The legacy trapezoid still runs in parallel as a shadow reading — the summary's "correction added Xm" is the difference, and the simulation suite keeps the legacy engine alive as its comparison baseline. In simulation the chord engine tracks a sparse-fix (2–6 s) run to within 3% — the case that read ~3% short on the trapezoid — holds a stopped-mid-gap runner to ~0 phantom metres, and reads a 10-minute stationary phone at 13 m.

Auto-pause

Detection is only as good as the evidence available, which differs by device:

Signal available	Pause detected	Resume detected
Doppler speed (normal iPhone outdoors)	~2 s	~2 s
iOS drops the speed solution while still	~7–10 s	~2 s
No speed at all (worst case)	~10 s	~5 s

Three things make that usable:

1. Both edges are back-dated. Every fix carries a timestamp, so pausing credits the clock from the first stationary fix, not from when the detector became sure. The confirmation delay costs nothing in the recorded splits — it only affects when the screen and the voice react.
2. Pausing is confirmed harder than resuming (3 fixes vs 2). A false pause eats real distance; a false resume just adds a couple of standing-still seconds and then re-pauses.
3. A tunnel is not a stop. Doppler keeps working where the position fix falls apart, so it carries the decision under bridges and between tower blocks. Where the device reports no speed at all, the fallback watches for distance to stop growing — which a lost signal would fake perfectly — so it refuses to conclude anything unless accurate fixes are still arriving steadily across the whole window. No fixes, coarse fixes, or a collapsed fix rate all mean "no opinion", never "stopped".

Simulated across a 90-second tunnel at running pace, all four signal-loss shapes produce zero auto-pauses, and ten minutes of steady running produces no false pauses on any device profile.

Why ducking, and not pausing, the music

transient ducks other audio; transient-solo interrupts it. Only ducking is used, because only ducking can be reliably undone from a web app.

An interrupted app on iOS resumes when the interrupting session deactivates — native code signals that with setActive(false, .notifyOthersOnDeactivation). The Web Audio Session API exposes no equivalent, and the keep-alive loop that stops Safari suspending the run means our session never falls silent by itself. Solo mode was tried and left players paused for the rest of the run, so it is gone rather than left as a trap.

Boosting the voice through a Web Audio gain node was tried as the alternative and also removed. Routing an element through createMediaElementSource is one-way, and on the target device the AudioContext reported running while producing no audible output once the element was routed — so phrases "played" perfectly, in silence, with nothing to fall back from. Guarding on the context state wasn't enough, because the context lied.

The trainer now always plays straight off the audio element. If the voice is hard to make out, the levers are your music's own volume and the phone's media volume.