Documentation Index
Fetch the complete documentation index at: https://docs.kynasmith.dev/llms.txt
Use this file to discover all available pages before exploring further.
MoveSpec YAML reference
MoveSpec definitions are authored in YAML. This page documents the schema structure with well-commented examples covering all available features.
Minimal example
The simplest valid MoveSpec defines a single movement with two phases:
# Every MoveSpec starts with a name and version.
name: squat
version: "1.0"
# The detection block defines what movements to detect.
detection:
type: repetition # Count repeated movement cycles.
movement:
name: squat
phases:
- name: standing # Starting position.
criteria:
- joint: knee
angle_min: 160
angle_max: 180
- name: bottom # Bottom of the squat.
criteria:
- joint: knee
angle_min: 60
angle_max: 100
sequence: # The phase order that defines one repetition.
- standing
- bottom
- standing
Full-featured example
This example demonstrates all supported schema features:
# Top-level metadata
name: workout-combo
version: "1.0"
description: "Detect a squat-to-lunge combination with feedback cues."
# Detection configuration
detection:
type: repetition
movement:
name: squat-lunge-combo
# Phases define the discrete positions in the movement.
phases:
- name: standing
description: "Upright standing position"
criteria:
- joint: knee
angle_min: 160
angle_max: 180
- joint: hip
angle_min: 160
angle_max: 180
- name: squat-bottom
description: "Bottom of squat — knees at roughly 90 degrees"
criteria:
- joint: knee
angle_min: 70
angle_max: 110
- joint: hip
angle_min: 70
angle_max: 110
- name: lunge-bottom
description: "Bottom of lunge — front knee bent, back leg extended"
criteria:
- joint: knee
side: front
angle_min: 70
angle_max: 100
- joint: knee
side: back
angle_min: 150
angle_max: 180
# Sequence defines the phase ordering for one complete repetition.
sequence:
- standing
- squat-bottom
- standing
- lunge-bottom
- standing
# Feedback cues emitted during detection.
feedback:
- trigger: squat-bottom
cue: "Good depth — hold briefly"
- trigger: lunge-bottom
cue: "Keep your back knee extended"
# Timing constraints (optional).
timing:
min_phase_duration_ms: 200 # Ignore phases shorter than 200ms (likely noise).
max_phase_duration_ms: 5000 # Fail phases longer than 5 seconds.
# Confidence thresholds (optional).
thresholds:
min_landmark_confidence: 0.5 # Ignore frames below this landmark confidence.
Schema reference
Top-level fields
| Field | Type | Required | Description |
|---|
name | string | Yes | Human-readable name for the MoveSpec. |
version | string | Yes | Schema version string (e.g., "1.0"). |
description | string | No | Optional description of the MoveSpec purpose. |
detection | object | Yes | The detection configuration block. |
detection object
| Field | Type | Required | Description |
|---|
type | string | Yes | Detection mode. Currently "repetition" for counting repeated movement cycles. |
movement | object | Yes | The movement definition. |
movement object
| Field | Type | Required | Description |
|---|
name | string | Yes | Identifier for the movement being detected. |
phases | array | Yes | List of phase definitions that make up the movement. |
sequence | array | Yes | Ordered list of phase names defining one repetition cycle. |
feedback | array | No | Optional feedback cues to emit during detection. |
timing | object | No | Optional timing constraints for phase transitions. |
thresholds | object | No | Optional confidence thresholds for frame filtering. |
phase object
| Field | Type | Required | Description |
|---|
name | string | Yes | Unique name for this phase within the movement. |
description | string | No | Human-readable description of the phase. |
criteria | array | Yes | List of joint-angle criteria that define the phase. |
criteria object
| Field | Type | Required | Description |
|---|
joint | string | Yes | The joint to evaluate (e.g., "knee", "hip", "elbow", "shoulder"). |
angle_min | number | Yes | Minimum joint angle in degrees (0-180). |
angle_max | number | Yes | Maximum joint angle in degrees (0-180). |
side | string | No | Which side to evaluate: "front", "back", "left", "right". Defaults to both sides. |
feedback object
| Field | Type | Required | Description |
|---|
trigger | string | Yes | Phase name that triggers this feedback cue. |
cue | string | Yes | The feedback message to emit. |
timing object
| Field | Type | Required | Description |
|---|
min_phase_duration_ms | number | No | Minimum phase duration in milliseconds. Phases shorter than this are ignored. |
max_phase_duration_ms | number | No | Maximum phase duration in milliseconds. Phases exceeding this trigger an interruption. |
thresholds object
| Field | Type | Required | Description |
|---|
min_landmark_confidence | number | No | Minimum landmark confidence (0.0 to 1.0). Frames below this threshold are skipped. |
Validation
Always validate your MoveSpec draft before creating a version:
- Errors block version creation and must be resolved.
- Warnings flag risky but non-blocking YAML patterns.
Use validateDraft() (SDKs) or POST /api/movespecs/{id}/validate (API) to check your YAML before versioning.
See MoveSpec validation troubleshooting if validation fails.