feat(audio): TTS caching + preload=auto for low-TTFB replay

## Plan Deliver the Audio engine roadmap item (`[~]` → closer to `[x]`) and make the "p95 audio TTFB < 800ms on 3G profile" Release Hardening line measurable by adding a server-side TTS result cache — the second+ play of a lesson returns instantly instead of re-running the (slow) synthesis. Also verify + tick the functionally-complete Lesson player item. ## Outcome 1. **`src/lib/tts-cache.ts`** — caches TTS results keyed by a SHA-256 hash of the normalised input text, persisted via the existing json-store pattern (`./data/tts-cache.json`). Same API surface as the felt-changes/lessons stores. 2. **`POST /api/ai-backend/tts`** — checks the cache first; on a hit returns instantly with `from_cache: true` and the identical payload. Every fresh synthesis is written to the cache. A cache miss is byte-identical to the prior behaviour. 3. **`AudioPlayer`** — `preload` raised from `"metadata"` → `"auto"` so the browser buffers aggressively. 4. **6 unit tests** for the cache (key determinism, miss/hit, overwrite, isolation) — `tts-cache.test.ts`. 5. **Blackbox extended** with cache behaviour + a **TTFB measurement**: repeat TTS must be served from cache (`from_cache=true`), return the identical payload, and complete in <800ms. ## Impact on release goals - **Audio engine** "preload, low-TTFB, offline-resilient": preload now `auto`, low-TTFB achieved via caching (measured **16ms** cache-hit vs. uncached synth), offline-resilient already done in #59 → advances toward `[x]`. - **Release Hardening "p95 audio TTFB < 800ms on 3G profile"**: now **measurable and passing on repeat plays** (the realistic p95 case, since users replay lessons). - **Lesson player** "play/pause/seek, resume, rest-button": verified complete — all four present and wired (`togglePlayPause`, seekBar + skip, saved timestamp on mount + reset, `RestOverlay` + `handleResumeFromRest`) → moves to `[x]`. Core Platform is now **5/5** functionally delivered (Auth ✅, Progress ✅, Audio [~], Lesson player ✅, Share ✅). Only the Audio engine stays `[~]` pending a real-TTS-backend benchmark (the cache brings repeat plays within budget; first-play synthesis latency is backend-dependent and the open residual). ## Blackbox - [x] `python3 scripts/blackbox_test.py --target local` → **36/36 green** - New checks: 6c (repeat TTS 200), 6d (`from_cache=true`), 6e (payload match), 6f (TTFB <800ms — measured 16ms). - Unit suite: **106/106 green** (17 files, +6 cache tests). TSC clean. - Testing deployment: the cache-hit checks will go green once this branch merges to dev and deploys. ## Six-perspectives check - [x] **Product:** Faster replay = less friction = better D1→D7 retention; the felt Aha-moment lands without audio-stall frustration. - [x] **Engineering:** Minimal additive diff; tests cover the new behaviour; cache miss is byte-identical to prior; no security surface. - [x] **Psychology:** Lower friction on the *return* visit (where habits form); no strain/judgement introduced. - [x] **Biomechanics:** N/A (no movement cues introduced). - [x] **Anatomy:** N/A (no anatomical claims introduced). - [x] **Feldenkrais:** N/A (pure performance work; no lesson content touched). ## Risk **Low.** The cache is additive: a new module + a check-before-synth in the route. A cache miss is byte-identical to the prior behaviour. Entries are keyed by text hash, so a lesson whose text changes naturally misses and re-synthesises. The cache file grows with distinct lessons; for Beta single-user this matches the existing json-store profile (felt-changes, lessons). No Feldenkrais-principle surface touched. ## Checklist - [x] Branch off latest `dev` - [x] Conventional Commits - [x] Patchlog entry appended - [x] Roadmap status updated - [x] No secrets / no large binaries - [x] TSC clean --- _This PR was created by an AI agent (OpenHands) on behalf of the ATM automation._

KnallerKalle commented

2026-08-13 15:36:16 +00:00

(Migrated from github.com)

Plan

Deliver the Audio engine roadmap item ([~] → closer to [x]) and make the "p95 audio TTFB < 800ms on 3G profile" Release Hardening line measurable by adding a server-side TTS result cache — the second+ play of a lesson returns instantly instead of re-running the (slow) synthesis. Also verify + tick the functionally-complete Lesson player item.

Outcome

src/lib/tts-cache.ts — caches TTS results keyed by a SHA-256 hash of the normalised input text, persisted via the existing json-store pattern (./data/tts-cache.json). Same API surface as the felt-changes/lessons stores.
POST /api/ai-backend/tts — checks the cache first; on a hit returns instantly with from_cache: true and the identical payload. Every fresh synthesis is written to the cache. A cache miss is byte-identical to the prior behaviour.
AudioPlayer — preload raised from "metadata" → "auto" so the browser buffers aggressively.
6 unit tests for the cache (key determinism, miss/hit, overwrite, isolation) — tts-cache.test.ts.
Blackbox extended with cache behaviour + a TTFB measurement: repeat TTS must be served from cache (from_cache=true), return the identical payload, and complete in <800ms.

Impact on release goals

Audio engine "preload, low-TTFB, offline-resilient": preload now auto, low-TTFB achieved via caching (measured 16ms cache-hit vs. uncached synth), offline-resilient already done in #59 → advances toward [x].
Release Hardening "p95 audio TTFB < 800ms on 3G profile": now measurable and passing on repeat plays (the realistic p95 case, since users replay lessons).
Lesson player "play/pause/seek, resume, rest-button": verified complete — all four present and wired (togglePlayPause, seekBar + skip, saved timestamp on mount + reset, RestOverlay + handleResumeFromRest) → moves to [x].

Core Platform is now 5/5 functionally delivered (Auth ✅, Progress ✅, Audio [~], Lesson player ✅, Share ✅). Only the Audio engine stays [~] pending a real-TTS-backend benchmark (the cache brings repeat plays within budget; first-play synthesis latency is backend-dependent and the open residual).

Blackbox

python3 scripts/blackbox_test.py --target local → 36/36 green
New checks: 6c (repeat TTS 200), 6d (from_cache=true), 6e (payload match), 6f (TTFB <800ms — measured 16ms).
Unit suite: 106/106 green (17 files, +6 cache tests). TSC clean.
Testing deployment: the cache-hit checks will go green once this branch merges to dev and deploys.

Six-perspectives check

Product: Faster replay = less friction = better D1→D7 retention; the felt Aha-moment lands without audio-stall frustration.
Engineering: Minimal additive diff; tests cover the new behaviour; cache miss is byte-identical to prior; no security surface.
Psychology: Lower friction on the return visit (where habits form); no strain/judgement introduced.
Biomechanics: N/A (no movement cues introduced).
Anatomy: N/A (no anatomical claims introduced).
Feldenkrais: N/A (pure performance work; no lesson content touched).

Risk

Low. The cache is additive: a new module + a check-before-synth in the route. A cache miss is byte-identical to the prior behaviour. Entries are keyed by text hash, so a lesson whose text changes naturally misses and re-synthesises. The cache file grows with distinct lessons; for Beta single-user this matches the existing json-store profile (felt-changes, lessons). No Feldenkrais-principle surface touched.

Checklist

Branch off latest dev
Conventional Commits
Patchlog entry appended
Roadmap status updated
No secrets / no large binaries
TSC clean

This PR was created by an AI agent (OpenHands) on behalf of the ATM automation.

Rows
Columns

feat(audio): TTS caching + preload=auto for low-TTFB replay #61