Skip to content

Open-source gym & body-weight tracker, now in the App Store (iPhone + Apple Watch) and as an Android APK. Plan routines, log workouts, see which muscles are trained, import from Strong/Hevy/FitNotes. Self-host it or use it on the phone alone.

Docs: where the phone keeps the photos and videos of custom exercises, what its backups do with them, and a README line for the feature

Duarte Santos0cac6d8db243
diff --git a/README.md b/README.md
index 7447640aa..1b5b77da5 100644
--- a/README.md
+++ b/README.md
@@ -72,6 +72,7 @@ as a home-screen app, passkey sign-in, offline support, sync across your phone a
- 🌈 **Colour-coded RIR / RPE** — one tap logs how hard a set was, with a sentence per level ("one more rep in the tank"); the same colour whether you think in RIR or RPE, a free field for in-between values
- 📖 **History without leaving the workout** — the exercise's last sessions and a progress line, from the ⋯ menu or the exercise details
- ⭐ **Favourite exercises** — star what you use, it sorts first in the picker and the library
+- 🖼️ **Your own exercises, with your own picture** — create what the library lacks from a name and a body part, then give it a photo, a GIF or a short video and a link to a video or guide. The file is shrunk and stripped of its location data on the device before it goes anywhere; signed in, it syncs with your profile and still shows offline
- ▶️ **Guided workouts** — it knows what day it is and starts today's session; asks your body weight first, pre-fills your weights from last time, rest timer, PR detection, per-exercise weight tracking. On a rest day it doesn't just say "rest day" — it names when your next session is and what it is
- 🙈 **Animations are your call** — the exercise demos can be full size, small, or hidden entirely during a workout. Hidden collapses the media rather than leaving a gap, for anyone who finds a looping GIF between sets more distracting than useful
- ☀️ **The screen stays awake while you train** — no unlocking the phone and finding your place again between every set. On for as long as a workout is running, released the moment you finish it, and switchable off in Settings
diff --git a/docs/MOBILE.md b/docs/MOBILE.md
index fb6d74fb6..9c7e41cd4 100644
--- a/docs/MOBILE.md
+++ b/docs/MOBILE.md
@@ -87,6 +87,39 @@ Where the phone keeps things, in case you ever need them by hand:
the copies versions before 1.3.9 wrote straight into `Documents/`, stay until you remove
them yourself. Settings → **Import backup** reads any of them back, wherever it is.
+### Photos and videos of your own exercises
+
+An exercise you create can carry one photo, GIF or short video, and a link to a video or guide.
+The file is prepared on the phone before it is kept anywhere: a photo is re-encoded (at most
+1600 px, WebP or JPEG — the location and camera data a phone writes into a photo do not
+survive), a GIF loses its comment and metadata blocks, and an MP4/MOV keeps its picture and
+sound while its metadata and any GPS or sensor track are zeroed. The original file name is
+never stored.
+
+- **Where it lives:** `Library/opengym-media/` in the app's own storage (iOS's Library folder,
+ Android's files directory), one file per photo or video named by its SHA-256, plus a small
+ `index.json`. The state keeps only a reference of a few hundred bytes. A MOV is stored with
+ an `.mp4` name so the WebView plays it.
+- **Local mode:** that folder is the only copy. **Export with photos & videos (.zip)** in
+ Settings → Data writes a zip with the usual JSON backup and every file, through the share
+ sheet; **Import backup** takes that zip back. The daily auto-backup stays JSON only.
+- **Paired with a server:** files go up to the server (`PUT /api/media/{hash}`) and come down
+ with the phone's token into the same folder, so they show offline too. A file that has not
+ reached the server yet is owed like an unsynced change: **Disconnect** says so and keeps it.
+ Big files wait for Wi-Fi unless you tap Settings → **Photos & videos**.
+- **Backups:** Android's cloud backup leaves `opengym-media/` out
+ (`res/xml/backup_rules.xml`, `res/xml/data_extraction_rules.xml`) — Auto Backup drops an
+ app's whole backup past 25 MB, and a few videos would take the state file down with them. A
+ device-to-device transfer keeps it. iOS includes Library in iCloud and computer backups.
+- **Permissions:** Android already has the camera. iOS asks for the camera
+ (`NSCameraUsageDescription`, now also for photos and videos of exercises) and, to record a
+ video with sound from the picker, the microphone (`NSMicrophoneUsageDescription`).
+
+Worth checking on a real device after changes here, since no test runs a WebView: a short
+video autoplays muted in the Android WebView; a long video seeks from its `_capacitor_file_`
+URL on both platforms; an iPhone photo arrives as JPEG and an iPhone video (HEVC or H.264 MOV)
+plays; the zip export opens the share sheet.
+
## Prerequisites
- Node 20+