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.

Animations: the quality rules and the media resolver

Duarte Santosa9b47ced89ec
diff --git a/frontend/src/lib/anim-quality.js b/frontend/src/lib/anim-quality.js
new file mode 100644
index 000000000..214fbbbbd
--- /dev/null
+++ b/frontend/src/lib/anim-quality.js
@@ -0,0 +1,100 @@
+// Which picture an exercise animation is drawn from in the store apps: the quality the person
+// picked (Settings → Animations), the asset packs this device has, and the files built into the
+// app. Pure: no plugin, no store, no DOM, so every rule here is a unit test (anim-quality.test.js).
+//
+// LICENCE. The animations are licensed from Gym visual. The repository, the web build and every
+// self-hosted server only ever have the 180 px files; anything larger reaches people only inside
+// the official store apps: built into the package, or in an Apple-hosted asset pack (Background
+// Assets) / a Play asset pack that the store itself delivers. Never from a server of ours, never as
+// a URL anyone can fetch. This file only ever names files by drawing id; it never reads one.
+//
+// The packs: one per quality and figure, `anim-<px>-male` / `anim-<px>-female`. A figure's pack
+// holds every drawing that figure shows: each catalogue exercise's drawing for that figure, or its
+// own when it is drawn once (those are in both packs). scripts/media/make-pack-manifests.mjs writes
+// them from the catalogue with the same rule (packDrawingId below). Inside a pack a drawing sits at
+// `<packId>/<drawing id>.webp`, so two packs installed side by side never share a path.
+//
+// Custom exercises never come here: their media are their own (components/CustomMedia.jsx).
+
+// The qualities a pack exists in, smallest first. The built-in files are BUILTIN_PX.
+export const PACK_QUALITIES = [240, 360, 480, 720, 1080]
+export const FIGURES = ['male', 'female']
+// What the app package carries itself. The repository's 180 px unless the release build says
+// otherwise (VITE_BUILTIN_CLIP_PX, set together with APP_MEDIA_DIR).
+const ENV = import.meta.env || {}
+export const BUILTIN_PX = Number(ENV.VITE_BUILTIN_CLIP_PX) > 0 ? Number(ENV.VITE_BUILTIN_CLIP_PX) : 180
+
+// The choices: 'auto', 'still' (no animation), 'builtin', or a pack quality in px.
+export const DEFAULT_CHOICE = 'auto'
+/** The qualities offered as packs: only those sharper than what is built in. */
+export const packQualities = (builtin = BUILTIN_PX) => PACK_QUALITIES.filter(px => px > builtin)
+
+export const packId = (px, figure) => `anim-${px}-${figure === 'female' ? 'female' : 'male'}`
+/** { px, figure } of a pack id, or null for anything else. */
+export function parsePackId(id) {
+ const m = /^anim-(\d+)-(male|female)$/.exec(String(id || ''))
+ return m && PACK_QUALITIES.includes(+m[1]) ? { px: +m[1], figure: m[2] } : null
+}
+
+/** Auto: 360 on a phone, 720 on a tablet (a short side of 600 CSS px or more). */
+export const autoPx = ({ shortSide = 0 } = {}) => (shortSide >= 600 ? 720 : 360)
+
+/** A stored choice read back: anything unknown is Auto. */
+export function readChoice(v) {
+ if (v === 'auto' || v === 'still' || v === 'builtin') return v
+ const n = Number(v)
+ return PACK_QUALITIES.includes(n) ? n : DEFAULT_CHOICE
+}
+
+/**
+ * The quality a choice stands for: a px, 'still' or 'builtin'. A pack quality no sharper than the
+ * built-in files is the built-in files.
+ */
+export function wantedQuality(choice, device = {}, builtin = BUILTIN_PX) {
+ const c = readChoice(choice)
+ if (c === 'still' || c === 'builtin') return c
+ const px = c === 'auto' ? autoPx(device) : c
+ return px > builtin ? px : 'builtin'
+}
+
+/**
+ * The drawing an exercise shows for a figure, the same rule as lib/exercises.js gifSrc: its twin
+ * drawn on that figure when it has one, else its own. The file name, without its extension.
+ */
+export function packDrawingId(ex, figure) {
+ const twin = figure === 'female' ? ex?.fv : figure === 'male' ? ex?.mv : null
+ if (twin) return twin
+ const own = typeof ex?.gif === 'string' && ex.gif ? ex.gif.replace(/\.[a-z0-9]+$/i, '') : ex?.id
+ return own ? String(own) : null
+}
+
+/**
+ * Where an animation comes from, best first, never empty:
+ * 1. the chosen quality's pack for this figure, if installed,
+ * 2. every smaller pack of this figure that is installed, sharpest first,
+ * 3. the built-in file (`builtin`, lib/exercises.js gifSrc).
+ * `installed` maps a pack id to the base its files are read from (Capacitor.convertFileSrc of the
+ * native path); a pack not in it, or without a base, is not there. 'still' gives no animation at
+ * all: `{ still: true, sources: [] }`, and the caller shows the still.
+ */
+export function clipSources({ ex, figure, choice, device, installed = {}, builtin, builtinPx = BUILTIN_PX }) {
+ const want = wantedQuality(choice, device, builtinPx)
+ if (want === 'still') return { still: true, sources: [] }
+ const sources = []
+ const id = packDrawingId(ex, figure)
+ if (id && want !== 'builtin') {
+ for (const px of [...PACK_QUALITIES].reverse()) {
+ if (px > want || px <= builtinPx) continue
+ const base = installed[packId(px, figure)]
+ if (typeof base === 'string' && base) sources.push(base.replace(/\/$/, '') + '/' + id + '.webp')
+ }
+ }
+ if (builtin) sources.push(builtin)
+ return { still: false, sources }
+}
+
+/** The pack a choice wants downloaded for a figure, or null (still, built in). */
+export function wantedPack(choice, figure, device, builtin = BUILTIN_PX) {
+ const want = wantedQuality(choice, device, builtin)
+ return typeof want === 'number' ? packId(want, figure) : null
+}
diff --git a/frontend/src/lib/anim-quality.test.js b/frontend/src/lib/anim-quality.test.js
new file mode 100644
index 000000000..e13559c63
--- /dev/null
+++ b/frontend/src/lib/anim-quality.test.js
@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest'
+import {
+ PACK_QUALITIES, BUILTIN_PX, packQualities, packId, parsePackId, autoPx, readChoice, wantedQuality,
+ packDrawingId, clipSources, wantedPack,
+} from './anim-quality.js'
+import { EXDB } from './exercises-data.js'
+
+/* Which file an exercise animation is drawn from in the store apps (lib/anim-quality.js). Only
+ names are looked at here: no media file is ever opened. */
+const male = { id: '0001', gif: '0001.mp4', img: '0001.webp', fv: '2476' } // drawn on both figures
+const female = { id: '9001', gif: '9001.mp4', img: '9001.webp', mv: '9002' } // a female exercise with a male twin
+const once = { id: '5965', gif: '5965.mp4', img: '5965.webp' } // drawn once
+const base = (px, fig) => `http://localhost/_capacitor_file_/packs/anim-${px}-${fig}`
+const all = fig => Object.fromEntries(PACK_QUALITIES.map(px => [packId(px, fig), base(px, fig)]))
+const phone = { shortSide: 390 }, tablet = { shortSide: 820 }
+
+describe('choices and qualities', () => {
+ it('the repository build has 180 px built in and offers every pack above it', () => {
+ expect(BUILTIN_PX).toBe(180)
+ expect(packQualities()).toEqual([240, 360, 480, 720, 1080])
+ expect(packQualities(240)).toEqual([360, 480, 720, 1080])
+ })
+ it('auto is 360 on a phone, 720 on a tablet', () => {
+ expect(autoPx(phone)).toBe(360)
+ expect(autoPx(tablet)).toBe(720)
+ expect(autoPx()).toBe(360)
+ })
+ it('reads anything unknown as auto', () => {
+ for (const v of [undefined, null, '', 'hd', 999, '360px', {}]) expect(readChoice(v)).toBe('auto')
+ expect(readChoice('720')).toBe(720)
+ expect(readChoice('still')).toBe('still')
+ })
+ it('a pack no sharper than the built-in files is the built-in files', () => {
+ expect(wantedQuality(240, phone, 240)).toBe('builtin')
+ expect(wantedQuality(480, phone, 240)).toBe(480)
+ expect(wantedQuality('auto', tablet)).toBe(720)
+ })
+ it('names packs per quality and figure, and reads them back', () => {
+ expect(packId(720, 'female')).toBe('anim-720-female')
+ expect(packId(720, 'whatever')).toBe('anim-720-male')
+ expect(parsePackId('anim-1080-male')).toEqual({ px: 1080, figure: 'male' })
+ expect(parsePackId('anim-999-male')).toBeNull()
+ expect(wantedPack('auto', 'female', phone)).toBe('anim-360-female')
+ expect(wantedPack('still', 'male', phone)).toBeNull()
+ expect(wantedPack('builtin', 'male', phone)).toBeNull()
+ })
+})
+
+describe('packDrawingId', () => {
+ it('the twin on that figure, else the exercise’s own drawing', () => {
+ expect(packDrawingId(male, 'male')).toBe('0001')
+ expect(packDrawingId(male, 'female')).toBe('2476')
+ expect(packDrawingId(female, 'male')).toBe('9002')
+ expect(packDrawingId(female, 'female')).toBe('9001')
+ expect(packDrawingId(once, 'female')).toBe('5965')
+ expect(packDrawingId(once, 'male')).toBe('5965')
+ })
+ it('agrees with lib/exercises.js gifSrc for every catalogue exercise', async () => {
+ const { gifSrc } = await import('./exercises.js')
+ for (const ex of EXDB) {
+ for (const fig of ['male', 'female']) {
+ expect(gifSrc(ex, fig).split('/').pop().replace(/\.(mp4|webp)$/, ''), ex.id + ' ' + fig).toBe(packDrawingId(ex, fig))
+ }
+ }
+ })
+})
+
+describe('clipSources', () => {
+ const builtin = 'exercise-media/clip/0001.webp'
+ it('the chosen pack first, then every smaller one installed, then the built-in file', () => {
+ const r = clipSources({ ex: male, figure: 'female', choice: 720, device: phone, installed: all('female'), builtin })
+ expect(r.sources).toEqual([
+ base(720, 'female') + '/2476.webp', base(480, 'female') + '/2476.webp', base(360, 'female') + '/2476.webp',
+ base(240, 'female') + '/2476.webp', builtin,
+ ])
+ })
+ it('the chosen pack not there yet: the next smaller one of the same figure, never the other figure’s', () => {
+ const installed = { [packId(360, 'male')]: base(360, 'male'), [packId(1080, 'female')]: base(1080, 'female') }
+ const r = clipSources({ ex: male, figure: 'male', choice: 720, device: phone, installed, builtin })
+ expect(r.sources).toEqual([base(360, 'male') + '/0001.webp', builtin])
+ })
+ it('nothing installed: the built-in file, so there is never a blank', () => {
+ for (const choice of ['auto', 240, 360, 480, 720, 1080, 'builtin', 'nonsense']) {
+ expect(clipSources({ ex: once, figure: 'female', choice, device: tablet, installed: {}, builtin }).sources).toEqual([builtin])
+ }
+ })
+ it('built in means built in, even with packs installed', () => {
+ expect(clipSources({ ex: male, figure: 'male', choice: 'builtin', installed: all('male'), builtin }).sources).toEqual([builtin])
+ })
+ it('still only: no animation at all, the caller shows the still', () => {
+ expect(clipSources({ ex: male, figure: 'male', choice: 'still', installed: all('male'), builtin })).toEqual({ still: true, sources: [] })
+ })
+ it('auto follows the device: a phone reads up to 360, a tablet up to 720', () => {
+ const p = clipSources({ ex: once, figure: 'male', choice: 'auto', device: phone, installed: all('male'), builtin })
+ expect(p.sources[0]).toBe(base(360, 'male') + '/5965.webp')
+ const t = clipSources({ ex: once, figure: 'male', choice: 'auto', device: tablet, installed: all('male'), builtin })
+ expect(t.sources[0]).toBe(base(720, 'male') + '/5965.webp')
+ })
+ it('a pack whose base is missing or empty counts as not there', () => {
+ const r = clipSources({ ex: once, figure: 'male', choice: 360, installed: { [packId(360, 'male')]: '' }, builtin })
+ expect(r.sources).toEqual([builtin])
+ })
+})