rzen
0f5f11e5e2
Speak exercise setup and form cues aloud with AVSpeechSynthesizer: - Library detail: a speaker toolbar button reads the full reference aloud. - Active workout: an opt-in "Speak Exercise Cues" setting speaks a brief cue (Setup/Execution/Cues) when an exercise starts, hands-free. - Settings › Voice: pick the voice (auto-prefers an installed enhanced/ premium English voice), a premium-download nudge shown only while on a basic voice, and a Speed/Pitch/Volume sheet with Reset to Defaults. On-device and offline; ducks other audio rather than stopping it. iPhone only for now. Shared SpeechSettings is the single source of truth for the voice/prosody, read fresh per utterance so changes preview live. Claude-Session: https://claude.ai/code/session_01BQcEWmAPA78338QuEwRkAh
108 lines
6.6 KiB
Markdown
108 lines
6.6 KiB
Markdown
# Workouts
|
|
|
|
A workout tracking app for iPhone and Apple Watch. Build workout splits, run
|
|
sessions, and track your progress — with your data stored as plain JSON files in
|
|
your own iCloud Drive.
|
|
|
|
## Key Features
|
|
|
|
- **Workout splits** — organize exercises into reusable routines with custom
|
|
colors, icons, and an activity type (strength, HIIT, cardio, …). Built-in
|
|
starter splits (Upper Body / Core / Lower Body
|
|
machine routines, plus an equipment-free **Bodyweight Core** circuit with its
|
|
own warm-up) appear automatically on first launch; editing one makes it your
|
|
own copy, and deleted starters can be restored from Settings.
|
|
- **Exercise library** — a bundled library of 47 exercises to populate your
|
|
splits, authored in `Exercise Library/` with per-exercise setup, cues,
|
|
mistakes, progressions, and an anatomically-rigged 3D stick-figure visual
|
|
system — covering every common movement pattern and gym station (see the
|
|
library's `COVERAGE.md`): the full machine circuit, the barbell and dumbbell
|
|
free-weight canon (deadlifts, squats, benches, rows, curls, raises), the
|
|
cable staples, and the bodyweight staples (push-ups, pull-ups, dips,
|
|
lunges, and the floor core set).
|
|
- **Run a workout** — start a session from a split, then tap an exercise to run it
|
|
as a paged flow: a **Ready?** lead-in, count-up work phases, count-down rests, and
|
|
a **Finish** page — mirroring the Apple Watch. Swipe a row to mark it complete, or
|
|
swipe to edit its plan (sets/reps/weight or duration) and notes. End a workout early
|
|
from the **⋯** menu — **Save** keeps your progress (remaining exercises are marked
|
|
skipped) or **Discard** removes it. Mid-workout, add any exercise from the full
|
|
library — its plan is seeded from your most recent session with it, or from the
|
|
library's authored defaults.
|
|
- **Live Activity** — the running workout lives on the Lock Screen and in the
|
|
Dynamic Island: current exercise, set count, phase, and a live rest countdown,
|
|
updating through every transition without unlocking the phone.
|
|
- **Animated form guide** — every library exercise shows a looping stick-figure
|
|
demonstration on the run screen's bottom half, posed by real joint angles on an
|
|
anatomical 3D skeleton (complete with feet) and rendered live from the Exercise
|
|
Library's rig data with the working limbs highlighted — the camera slowly
|
|
orbits every exercise while it moves, machine equipment (seats, bars, cables,
|
|
roller pads) has world-space 3D form that turns with the figure, and face-on
|
|
machines show true hip abduction and torso rotation.
|
|
- **Spoken instructions** — tap the speaker in any library exercise to hear its
|
|
full reference read aloud, and turn on **Speak Exercise Cues** in Settings to
|
|
have the setup and form cues spoken automatically when you start an exercise, so
|
|
you can follow along hands-free. On-device speech that ducks — never stops — your
|
|
music. A **Voice** section in Settings picks the voice (preferring any enhanced or
|
|
premium voices you've installed) and tunes its speed, pitch, and volume, with a
|
|
live preview.
|
|
- **Machine comfort settings** — machine-based exercises remember your setup
|
|
(seat height, back-rest position, pin position, …), shown on the workout
|
|
screen and editable mid-workout; changes save back to the split for next time.
|
|
- **Per-set actuals** — every completed set is recorded automatically with its
|
|
planned reps and weight, and the rest and finish pages offer a small adjust
|
|
pill to correct what you actually did (in 2.5 lb / 1.25 kg steps) without
|
|
breaking the flow; the completed-exercise page shows the recorded sets.
|
|
- **Progress tracking** — weight-progression charts per exercise across past
|
|
sessions, plotting the top-set weight you actually lifted; workout volume
|
|
sums the recorded sets too.
|
|
- **Apple Watch companion** — starting a workout on the iPhone launches the watch
|
|
app straight into it. The watch lists your in-progress workouts; pick one, pick an
|
|
exercise, and run it as a paged flow: a **Ready?** lead-in, count-up work phases,
|
|
count-down rests with final-three-second haptics and auto-advance, and a **Finish**
|
|
page with **One More** and a **Done** that auto-completes after a countdown. A
|
|
phase-dot row (purple work, teal rest) tracks progress. Rest time and the
|
|
auto-finish countdown are configurable; changes sync back to the phone.
|
|
- **Two-way live run** — prop your iPhone up during an Apple Watch workout and it runs
|
|
the same Ready → work/rest → Finish flow with live timers, in step with the watch. It's
|
|
bidirectional: drive from either device — swipe ahead, finish a set, add one — and the
|
|
other follows. Only *human* transitions are sent; automatic ones (a rest timer ending)
|
|
advance both devices independently off shared start times, so they never fight.
|
|
- **Watch face complication** — a launcher complication you can place on any Apple
|
|
Watch face; tap it to open the app. Available in the circular, corner, inline, and
|
|
rectangular accessory slots.
|
|
- **Apple Health & Activity rings** — workouts recorded on the Apple Watch (heart
|
|
rate + active energy) are saved to Apple Health and credit your Move and Exercise
|
|
rings. See live heart rate and calories on the watch, and a post-workout summary
|
|
(duration, calories, avg/max heart rate, heart-rate zones with a legend, total
|
|
volume) you can revisit on any past workout. Weights display in your choice of
|
|
pounds or kilograms.
|
|
- **iCloud Drive sync** — your data lives as human-readable JSON in your iCloud
|
|
Drive, synced across devices and visible in the Files app. iCloud is required.
|
|
- **Backups** — create point-in-time snapshots of all your data from Settings,
|
|
keep several with retention controls, and restore one with a tap (backup files
|
|
open straight into the app).
|
|
- **Diagnostics** — a Settings screen that shows iCloud account and container
|
|
status, per-document download/eviction state, schema compatibility, and network
|
|
readiness — with a one-tap copyable report.
|
|
|
|
## Architecture
|
|
|
|
iCloud Drive JSON documents are the **sole source of truth**; a local SwiftData
|
|
store is a rebuildable read-through cache populated exclusively by an
|
|
`NSMetadataQuery` observer (one-way flow: files → observer → cache). The phone is
|
|
the only device that touches iCloud Drive; the Apple Watch is a thin remote that
|
|
round-trips workout changes through the phone via WatchConnectivity.
|
|
|
|
See `REQUIREMENTS.md` for the data model and `CLAUDE.md` for project guidance.
|
|
|
|
## Building
|
|
|
|
The Xcode project is generated with [XcodeGen](https://github.com/yonaskolb/XcodeGen):
|
|
|
|
```sh
|
|
xcodegen generate
|
|
open Workouts.xcodeproj
|
|
```
|
|
|
|
Requires Xcode 26 (iOS 26 / watchOS 26, Swift 6).
|