Skip to main content

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
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

FieldTypeRequiredDescription
namestringYesHuman-readable name for the MoveSpec.
versionstringYesSchema version string (e.g., "1.0").
descriptionstringNoOptional description of the MoveSpec purpose.
detectionobjectYesThe detection configuration block.

detection object

FieldTypeRequiredDescription
typestringYesDetection mode. Currently "repetition" for counting repeated movement cycles.
movementobjectYesThe movement definition.

movement object

FieldTypeRequiredDescription
namestringYesIdentifier for the movement being detected.
phasesarrayYesList of phase definitions that make up the movement.
sequencearrayYesOrdered list of phase names defining one repetition cycle.
feedbackarrayNoOptional feedback cues to emit during detection.
timingobjectNoOptional timing constraints for phase transitions.
thresholdsobjectNoOptional confidence thresholds for frame filtering.

phase object

FieldTypeRequiredDescription
namestringYesUnique name for this phase within the movement.
descriptionstringNoHuman-readable description of the phase.
criteriaarrayYesList of joint-angle criteria that define the phase.

criteria object

FieldTypeRequiredDescription
jointstringYesThe joint to evaluate (e.g., "knee", "hip", "elbow", "shoulder").
angle_minnumberYesMinimum joint angle in degrees (0-180).
angle_maxnumberYesMaximum joint angle in degrees (0-180).
sidestringNoWhich side to evaluate: "front", "back", "left", "right". Defaults to both sides.

feedback object

FieldTypeRequiredDescription
triggerstringYesPhase name that triggers this feedback cue.
cuestringYesThe feedback message to emit.

timing object

FieldTypeRequiredDescription
min_phase_duration_msnumberNoMinimum phase duration in milliseconds. Phases shorter than this are ignored.
max_phase_duration_msnumberNoMaximum phase duration in milliseconds. Phases exceeding this trigger an interruption.

thresholds object

FieldTypeRequiredDescription
min_landmark_confidencenumberNoMinimum 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.