Movement Library & Video Reference Schema

Introduced in v1.0.69

The Movement Library is the canonical registry of all movements used across the platform. It serves as the single source of truth for session programming, scaling alternatives, injury restrictions, and the video coaching library.

Overview

Every movement in the platform — from a back squat to a banded pull-apart — is represented as a structured record in the Movement Registry. These records are referenced across:

Session programming — movements are assigned to sessions across all training tracks.
Scaling options — each movement links to its scaling alternatives, supporting multi-tier programming for athletes of varying ability.
Injury restrictions — the injury restriction engine queries movement records to surface safe alternatives when a member has an active restriction.
Video coaching library — each movement can carry a Mux video asset reference for demonstration and annotation.

Movement Record Schema

Each movement record contains the following fields:

Coaching Cues

A structured list of instructional cues associated with the movement. These are surfaced to members during session delivery and to coaches when authoring or annotating sessions.

[
  "Brace your core before the descent.",
  "Drive knees out in line with toes.",
  "Maintain a neutral spine throughout."
]

Fault Descriptors

Common errors and movement breakdown patterns for the movement. Used by the coaching annotation tools to provide structured, repeatable feedback.

[
  "Knee cave on the descent.",
  "Forward lean causing loss of bar path.",
  "Heels rising off the floor at depth."
]

Scaling Alternatives

References to substitute movements that can replace this movement in a session. Scaling alternatives are used by the programming engine to generate appropriate session variants for different athlete tiers.

[
  { "movement_id": "goblet-squat", "tier": 2 },
  { "movement_id": "box-squat",    "tier": 3 },
  { "movement_id": "air-squat",    "tier": 4 }
]

Mobility Prep Links

References to warm-up and mobility movements that are relevant to this movement. Coaches can use these links to automatically populate session preambles with targeted prep work.

[
  { "movement_id": "couch-stretch",         "purpose": "hip flexor prep" },
  { "movement_id": "ankle-banded-distraction", "purpose": "ankle mobility" }
]

Mux Video Asset Reference

Each movement record can carry a reference to a Mux video asset for movement demonstration. The video reference schema stores the Mux asset ID and playback ID, enabling adaptive streaming within the platform's video coaching tools.

{
  "mux_asset_id":    "ds00Spx1CV902MCtPj5hMC9Guw01gntepQaokI3ogCs",
  "mux_playback_id": "EcHgOK9coz5K4rjSwOkoE7Y7O01201YMIC200RI"
}

Note: A movement record without a video reference is valid. Video assets are optional and can be added or updated independently of other record fields.

Relationships

Movement
  ├── coaching_cues[]          (text)
  ├── fault_descriptors[]      (text)
  ├── scaling_alternatives[]   → Movement (by ID + tier)
  ├── mobility_prep_links[]    → Movement (by ID + purpose)
  └── video_reference
        ├── mux_asset_id       (string)
        └── mux_playback_id    (string)

Usage by Feature Area

Feature	How the Movement Library is Used
Session Programming	Movements are assigned to session blocks by coaches or the AI engine
Scaling Tiers	Scaling alternatives provide per-tier substitutions when a session is rendered for an athlete
Injury Restrictions	The restriction engine excludes movements (and their variants) matching active injury profiles
Video Coaching	Mux asset references power demonstration video playback and frame-level annotation
Mobility Prep	Linked mobility movements are surfaced in session warm-up recommendations

Notes for Coaches

Coaching cues and fault descriptors you author on a movement record are reused automatically across every session that includes that movement — you don't need to re-enter them per session.
Scaling alternatives are directional: if Movement A lists Movement B as a scaling alternative, that does not automatically make A a scaling option for B. Both directions must be defined if bidirectional scaling is intended.
Mobility prep links are suggestions, not enforced constraints. The session editor allows coaches to override or supplement auto-populated prep work.

Notes for Developers

The movement record is the root entity for the movement domain. All upstream references (sessions, restrictions, scaling) hold a foreign key to the movement record's ID — not to the movement name string.
Video references use Mux as the asset host. Store both mux_asset_id and mux_playback_id; the playback ID is what the client uses to construct streaming URLs.
Scaling alternatives and mobility prep links are stored as arrays of references (not embedded documents) to allow the referenced movements to be updated independently.