Practice Studio — PRD (design + execution spec)
_v1 · 2026-10-03 · owner Byron · live target https://music.arnao.ai/_
Plan + first critique: https://practice-plan.arnao.ai/ · Mockups: https://practice-plan.arnao.ai/mockups/ · Teacher critique: critique/teacher.md
1. Goal
One installable web app (PWA, offline) on the Galaxy Z TriFold (unfolded 2160×1584, 204.8×150.2 mm) that makes Byron measurably better at piano, guitar and ukulele:
- Fretboards at true 1:1 (guitar nut→6th fret, concert uke nut→12th) with on-glass finger placement that turns green when right.
- Mic is the source of truth: the app listens to the real instrument, verifies the expected chord (chroma match), grades strum timing against the metronome, and only then calls a chord "mastered".
- Piano on glass = theory/reference view (note geography, chord shapes, inversions). Web MIDI is the real piano practice path.
- Guided daily session as the home screen: warm-up → chord changes → looped song section → spaced-repetition review. ~20 min.
- Song catalog of the most common songs, playable on all three instruments with the C–G–Am–F family (+D, Em, Dm, E, A, G7, D7), sequenced so each new song adds at most one chord.
- Record takes from the mic and keep a practice log.
2. Non-goals (v1)
Strumming on glass · audio chord recognition from scratch (we only verify an expected chord) · copyrighted lyrics/melodies · accounts/cloud sync · iOS.
3. Users & device
Byron only. Samsung Galaxy Z TriFold, Chrome. Landscape, unfolded. Also usable folded (cover screen) for the 90-second "daily changes" habit loop and chord lookup (v1.1).
4. Screen math (settled)
- 267.9 ppi → 10.55 px/mm. Browser estimate
cssPxPerMm = screen.width·DPR / 204.8, seed only.
- Calibration is mandatory: ISO ID-1 card (85.60 × 53.98 mm) outline, −/+ nudge, "edges match". Stored per
{screen.width, DPR}; re-prompt if either changes.
- Frets:
d(n) = L·(1 − 2^(−n/12)). Scale lengths selectable + "measure my instrument" (nut→12th fret ×2).
- Piano white key 23.5 mm, black 13.7 mm. Modes: Playable (2 oct, 14.6 mm) · Overview (88, view-only) · 1:1 (8 keys, hand-shape reference).
- Folds at x = ⅓ and ⅔ of width. Fret window snaps so no fret wire lies within ±4 mm of a fold.
5. Features (v1 scope, in build order)
5.1 Calibration (E)
Card outline, nudge, ruler, instrument-measure alternative. Persist pxPerMm.
5.2 Instruments & chord library
- Instruments: guitar (648/628/650 mm, EADGBE, nut 43/52), ukulele (soprano 346 / concert 381 / tenor 432, GCEA, low-G option), piano.
- Chord dictionary for guitar + uke + piano: all triads (maj/min), 7, maj7, m7, sus2, sus4, dim, aug, add9 in 12 keys; curated easy voicings with finger numbers for tiers:
- Guitar T1 Em Am D A E · T2 G C D7 G7 E7 A7 Cadd9 · T3 Dm B7 Fmaj7 mini-F sus · T4 F barre, Bm, B, movable.
- Uke T1 C Am F G7 · T2 G C7 A A7 Dm Em D7 · T3 D E7 Bm B♭ · T4 E, movable.
- Piano T1 C F G Am (RH root + LH bass) · T2 Dm Em G7 + first inversions · T3 D A E, 7ths, LH broken · T4 all keys, slash, sus/add9.
- Generated voicings for anything not curated (nearest-fret algorithm, ≤4-fret span).
5.3 Song catalog
- Format ChordPro (
{title:} {key:} {tempo:} {time:} {strum:} {tier:} {section:} + [G]lyric).
- 30 starter songs: 15 public-domain with full lyrics (Amazing Grace, Saints, Oh! Susanna, Jingle Bells, Silent Night, Happy Birthday, Auld Lang Syne, Clementine, Red River Valley, Michael Row, Swing Low, Circle Be Unbroken, House of the Rising Sun, Scarborough Fair, Greensleeves) + 15 modern as chords + structure only (Stand By Me, Let It Be, Knockin', Three Little Birds, Riptide, I'm Yours, Country Roads, Zombie, Bad Moon Rising, Sweet Home Alabama, Love Me Do, Ring of Fire, Hallelujah, Horse With No Name, Perfect).
- Each song: key, tempo, time sig, tier, strumming pattern id, per-instrument chord set (same chords, instrument-specific shapes); transpose/capo/simplify with "graduation nudge".
- Import: paste ChordPro.
- Sorted so each next song adds ≤1 new chord.
5.4 Strumming / rhythm (new, from teacher)
- Pattern library: D–DU–UDU, D–D–DU, boom-chick, island (D–DU–UDU uke), 3/4 waltz, 6/8, Travis basic; piano LH patterns: whole-note bass, broken chord, Alberti.
- Visual: beat grid with arrows, metronome-locked playhead.
- Mic onset grading: detect strum onsets (energy flux), score vs expected beat grid (±60 ms tight / ±120 ms ok).
5.5 Fretboard trainer (A, C)
- 1:1 neck render, high-e-on-top default with flip, lefty mirror.
- Targets with finger numbers; touch→(string,fret) mapping; palm rejection (contact > 25 mm or > 10 touches ignored); barre = touches clustered on one fret across ≥3 strings within 150 ms.
- Grading: landing time (first touch → full shape).
- Drills: single chord · change pairs (one-minute changes) · chords of current song.
- Glass pass = "shape known". Mastered = mic-verified clean chord 5× with change < 2 s.
- Touch spike result is shown in the calibration screen ("touch test") so Byron can report.
5.6 Listening (mic)
- Tuner (YIN) · single-note check · expected-chord verification (chroma vs chord pitch classes; pass if expected classes ≥ 0.6 of energy, missing none) · strum onset timing.
5.7 Piano (B)
- Modes playable/overview/1:1; mini-map; chord highlight with LH/RH finger numbers; inversions; voice-leading view (C→G/B→Am).
- Web MIDI input: note-on highlights keys; graded chord/scale drills from MIDI.
- Starter pieces (PD, in order): Ode to Joy, When the Saints, Amazing Grace lead-sheet, Jingle Bells, Minuet in G, Bach Prelude C. (No Für Elise.)
- Audio: synth piano (Web Audio, simple additive/FM) — sampled piano v1.1.
5.8 Song player (D)
- Chords above lyrics; section loop (tap two bars) · tempo 50–100 % · count-in 1 bar · metronome · chord now/next · tap chord → drill.
- Strum pattern bar synced to the metronome.
5.9 Guided session (home)
- 20-min script: warm-up (scale/5-finger) → changes (weakest pair) → song section loop → review (spaced repetition: songs due today).
- Progress store: per chord {shapeKnown, masteredCount, bestChange}, per song {lastPlayed, interval, ease}, minutes/day.
- Cover-screen "90-second changes" (v1.1).
5.10 Recorder
- MediaRecorder (audio/webm;codecs=opus) → IndexedDB, list, play back, delete. Tied to song + date. Export v1.1.
5.11 Posture card
One illustrated checklist per instrument at session start + "prop the phone at stand height".
6. Architecture
Static site, vanilla ES modules, no bundler, deployed to Vercel (music.arnao.ai). index.html + js/*.js + css/app.css + sw.js + manifest.json. All state in localStorage (small) and IndexedDB (recordings). No backend. Module contracts in EXECUTION.md.
7. Acceptance
- Calibration persists; ruler on screen matches a real ruler within 1 mm over 100 mm.
- Guitar neck frets 1–6 and uke frets 1–12 at correct mm (unit test on
fretMm()).
- Touch on the neck maps to the right (string, fret); G chord placement passes; palm resting on glass does not false-trigger.
- Tuner reads A4 ±2 cents on a sine; expected-chord check passes synthetic C major and fails synthetic A minor; onsets within ±60 ms on a synthetic click.
- 30 songs load; every chord in every song has a shape for guitar, uke and piano.
- Section loop + count-in + tempo change work; MIDI note-on highlights keys (tested with a virtual MIDI message).
- Recorder saves and replays a take.
- Playwright tests pass at 960×704 @2.25 (TriFold) headless.
- Every link in the app and docs is clickable https.
8. Risks
Palm rejection on Samsung panels (spike first) · Chrome mic latency 60–150 ms (fine for grading, not for play-along sound) · DPR/zoom changes (re-calibrate) · copyright (modern songs = chords only, no lyrics or melody).