TRN File Format Specification

Version: 0.4.0 For: AI systems generating .trn workout files Source of Truth: TRN Parser (packages/trn-parser/src/)

---

IMPORTANT: Instructions for AI Systems

This document is the complete and authoritative specification for generating .trn workout files. When generating TRN files:

1. Use ONLY the syntax and fields documented here - do not invent new fields
2. Follow format patterns exactly - tempo must be N-N-N-N, not N-N-N
3. Include required fields - files without them will fail to parse
4. Use notes and description for extra information - don't create custom fields
5. When uncertain, use the simplest valid structure
6. Validate your output against the rules in this document

DO NOT:

• Invent new field names
• Use different format patterns than specified
• Add nested structures not shown in this spec
• Use complex YAML features (anchors, aliases, custom tags)
• Include executable code or scripts
• Use colons (:) in string values like notes - they break YAML parsing

---

Overview

TRN (Training Notation) is a YAML-based text format for describing workouts and training programs.

• File extension: .trn
• Encoding: UTF-8
• YAML version: 1.2 (parsed with yaml library v2.x)

Two Document Types

The parser checks for program key first, then workout key.

---

Quick Start

Minimal Workout

workout: Upper Body
exercises:
  - name: Bench Press
    sets: 3
    reps: 8

Minimal Program

program: Push Pull Legs
type: rotation
workouts:
  - id: push
    name: Push Day
    exercises:
      - name: Bench Press
        sets: 3
        reps: 8

---

Single Workout Format

Required Fields

Optional Metadata Fields

Location Values

Use one of these standard values:

• any - Works anywhere
• gym - Requires gym equipment
• home - Home gym setup
• hotel - Limited hotel gym
• outdoor - Park/outdoor

Custom strings are also accepted.

Workout Type Values

Warmup Section (Optional)

warmup:
  - name: Light Cardio
    duration: 5min
    notes: Bike or rowing
    exercises: [arm circles, leg swings]

Cooldown Section (Optional)

cooldown:
  - name: Static Stretching
    duration: 5min
    notes: Hold each stretch 30s

Progression Rules (Optional)

progression:
  rule: linear
  increment: 2.5kg
  when: "all reps completed"
  deload_after: "4 weeks"
  deload_amount: "10%"

Valid rule values: linear, weekly, percentage, percentage_wave

Additional optional fields: type, base, after_cycle.

---

Exercise Object

Required Fields

IMPORTANT: The reps field is ALWAYS required unless the exercise uses duration instead (timed exercises like planks).

For timed exercises only:

Optional Fields

Exercise Classification Fields (Optional)

These fields provide metadata about the exercise for filtering and categorization:

exercises:
  - name: Bench Press
    sets: 4
    reps: "6-8"
    weight: user
    type: strength
    mechanics: compound
    movement: push_horizontal
    measurement: weight_reps
    muscle_groups: [chest, triceps, front_delts]
    secondary_muscles: [biceps]

---

Data Format Specifications

Reps Format

# Valid examples
reps: 10
reps: "8-10"
reps: "AMRAP"
reps: "max"
reps: "failure"
reps: "8 + 4"

Weight Format

# Valid examples
weight: "80kg"
weight: "176lbs"
weight: "bodyweight"
weight: "+20kg"
weight: "-10kg"
weight: "80%1RM"
weight: "user"
weight: null

Rest Format

# Valid examples
rest: "90s"
rest: "2min"
rest: "1min30s"
rest: "120"

Tempo Format

Format: E-P-C-P (Eccentric-Pause-Concentric-Pause)

MUST have exactly 4 numbers separated by hyphens.

• E = Eccentric (lowering) in seconds
• P = Pause at bottom in seconds
• C = Concentric (lifting) in seconds
• P = Pause at top in seconds

# Valid
tempo: "3-0-1-0"    # 3s down, no pause, 1s up, no pause
tempo: "2-1-1-0"    # 2s down, 1s pause, 1s up, no pause
tempo: "4-0-2-1"    # 4s down, no pause, 2s up, 1s pause

# INVALID - will cause parse error
tempo: "3-0-1"      # Only 3 parts
tempo: "2-1-0"      # Only 3 parts

Duration Format

For timed exercises (planks, cardio, etc.):

duration: "30s"
duration: "5min"
duration: "1h30min"

RPE Format

Rate of Perceived Exertion, scale 1-10:

rpe: 8    # Must be between 1 and 10

---

Advanced Structures

Per-Set Prescription

When each set has different targets, use an array of set details instead of a single number:

exercises:
  - name: Squat
    sets:
      - reps: 5
        weight: "100kg"
        type: working
      - reps: 5
        weight: "107.5kg"
        type: working
      - reps: "AMRAP"
        weight: "115kg"
        type: amrap
    reps: 5
    rest: "180s"

IMPORTANT: Even when using per-set details, the top-level reps field is still required (use the primary set's reps value).

Set Detail Fields

Set Types

Training Tier

Used in GZCL-style and tiered programming to classify exercise importance:

exercises:
  - name: Back Squat
    sets: 5
    reps: 3
    tier: "T1"
    rest: "180s"

  - name: Romanian Deadlift
    sets: 3
    reps: 10
    tier: "T2"
    rest: "120s"

  - name: Leg Curl
    sets: 3
    reps: "12-15"
    tier: "T3"
    rest: "60s"

Any string value is accepted for tier.

Warmup Sets

exercises:
  - name: Back Squat
    sets: 4
    reps: 6
    weight: "120kg"
    warmup_sets:
      - reps: 10
        weight: "40kg"
      - reps: 5
        weight: "80kg"
      - reps: 3
        weight: "100kg"

Alternative Exercises

Simple list:

alternatives: [Dumbbell Press, Machine Press]

Detailed alternatives:

alternatives:
  - name: Dumbbell Press
    sets: 3
    reps: "10-12"
    weight: "30kg"
    notes: Good for home workouts

Exercise Groups (Supersets, Tri-Sets, Giant Sets, Circuits)

Use the group field to link exercises together. All exercises with the same group value are performed as a group.

exercises:
  # Superset A (2 exercises)
  - name: Bicep Curl
    sets: 3
    reps: 12
    rest: "0s"
    group: A

  - name: Tricep Extension
    sets: 3
    reps: 12
    rest: "90s"
    group: A

  # Superset B (3 exercises = tri-set)
  - name: Lateral Raise
    sets: 3
    reps: 15
    rest: "0s"
    group: B

  - name: Front Raise
    sets: 3
    reps: 12
    rest: "0s"
    group: B

  - name: Rear Delt Fly
    sets: 3
    reps: 15
    rest: "90s"
    group: B

The group type is derived from the number of exercises:

• 2 exercises = superset
• 3 exercises = tri-set
• 4+ exercises = giant set

You can also explicitly set the group type:

- name: Clean
  sets: 3
  reps: 3
  group: complex1
  group_type: complex

- name: Front Squat
  sets: 3
  reps: 3
  group: complex1
  group_type: complex

Group Type Values

NOTE: superset_with is deprecated. Use group instead.

Images

images:
  start: "https://example.com/squat-start.jpg"
  end: "https://example.com/squat-end.jpg"

image_gif: "https://example.com/squat-animation.gif"

Multiple Videos

videos:
  - url: "https://youtube.com/watch?v=overview"
    title: Full Movement
  - url: "https://youtube.com/watch?v=technique"
    title: Technique Breakdown
    timestamp: "1:45"

---

Technique Field Values

Use exactly one of these values for the technique field:

Drop Set Example

- name: Lateral Raises
  technique: drop_set
  sets: 3
  reps: 10
  weight: user
  rest: "90s"
  notes: Drop weight ~20% after each set, no rest between drops

Rest-Pause Example

- name: Leg Press
  technique: rest_pause
  sets: 1
  reps: 20
  weight: "200kg"
  rest_pause:
    - reps: 12
      rest: "15s"
    - reps: 5
      rest: "15s"
    - reps: 3

Myo-Reps Example

- name: Bicep Curls
  technique: myo_reps
  sets: 1
  reps: 20
  activation_set:
    reps: 20
    weight: "15kg"
    rest: "15s"
  mini_sets:
    reps: 5
    count: 4
    rest: "5s"

Cluster Sets Example

- name: Deadlift
  technique: cluster
  sets: 3
  reps: 5
  weight: "180kg"
  cluster_rest: "20s"
  rest: "180s"

Lengthened Partials Example

- name: Squat
  sets: 3
  reps: 10
  technique: lengthened_partials
  range: bottom_half

Range values: bottom_half, top_half, mid_range

---

Multi-Day Program Format

Required Fields

Optional Fields

Program Types

Workout Definition (in Program)

workouts:
  - id: push           # Required: unique identifier
    name: Push Day     # Required: display name
    description: Chest, shoulders, triceps  # Optional
    duration: "60min"  # Optional
    location: gym      # Optional
    notes: |           # Optional
      Multi-line notes here
    exercises:         # Required: array of exercises
      - name: Bench Press
        sets: 3
        reps: 8

Schedule Configuration

Simple Rotation:

schedule:
  sequence: [push, pull, legs]
  rhythm: "1-1-0"

With Total Sessions:

schedule:
  sequence: [A, B, C, D, E]
  rhythm: "1-0-1-1-0"
  total_sessions: 5

Phased Programs:

schedule:
  per_phase: [squat_day, bench_day, deadlift_day]
  rhythm: "1-0-1-1-0"

Use per_phase instead of sequence when the same workout IDs are reused across phases (each phase modifies the exercises via by_phase).

Rhythm Syntax

Pattern of 1 (training) and 0 (rest) separated by hyphens:

---

Program Phases

For programs that cycle through different training phases (5/3/1, DUP, block periodization), define phases at the program level and use by_phase overrides on individual exercises.

Phase Definition

program: "Wendler 5/3/1"
type: phased
phases:
  - id: week1
    name: "5s Week"
  - id: week2
    name: "3s Week"
  - id: week3
    name: "531 Week"
  - id: deload
    name: "Deload Week"

Exercise Phase Overrides

Use by_phase on any exercise to change sets, reps, weight, rest, rpe, or notes per phase:

workouts:
  - id: squat_day
    name: Squat Day
    exercises:
      - name: Back Squat
        sets: 3
        reps: 5
        weight: user
        rest: "180s"
        tier: "T1"
        by_phase:
          week1:
            reps: 5
            weight: "75%"
            notes: "3x5 at 65%, 75%, 85%"
          week2:
            reps: 3
            weight: "80%"
            notes: "3x3 at 70%, 80%, 90%"
          week3:
            reps: 1
            weight: "85%"
            notes: "5/3/1 at 75%, 85%, 95%"
          deload:
            sets: 3
            reps: 5
            weight: "60%"

Phase Override Fields

---

Validation Rules

Errors (File Will Not Parse)

Warnings (File Parses, User Notified)

---

Complete Examples

Example 1: Gym Strength Workout

workout: Full Body Strength
author: Coach Mike
version: "1.0"
location: gym
duration: 60min
tags: [strength, full-body, intermediate]
description: |
  Compound movement focus for overall strength development.
  Rest 2-3 minutes between heavy sets.

default_rest: "120s"

warmup:
  - name: Light Cardio
    duration: 5min
  - name: Dynamic Stretching
    duration: 5min

exercises:
  - name: Barbell Back Squat
    sets: 4
    reps: 6
    weight: user
    rest: "180s"
    rpe: 8
    tempo: "3-0-1-0"
    type: strength
    mechanics: compound
    movement: squat
    muscle_groups: [quads, glutes, hamstrings]
    equipment: barbell
    notes: Focus on depth and bracing
    warmup_sets:
      - reps: 10
        weight: "40kg"
      - reps: 5
        weight: "70kg"
      - reps: 3
        weight: "90kg"
    alternatives: [Front Squat, Leg Press]

  - name: Bench Press
    sets: 4
    reps: 6
    weight: user
    rest: "180s"
    rpe: 8
    type: strength
    mechanics: compound
    movement: push_horizontal
    muscle_groups: [chest, triceps, front_delts]

  - name: Barbell Row
    sets: 3
    reps: 8
    weight: user
    rest: "120s"
    muscle_groups: [back, biceps]

  - name: Overhead Press
    sets: 3
    reps: 8
    weight: user
    rest: "120s"
    muscle_groups: [shoulders, triceps]

  - name: Romanian Deadlift
    sets: 3
    reps: 10
    weight: user
    rest: "120s"
    muscle_groups: [hamstrings, glutes, lower_back]

cooldown:
  - name: Static Stretching
    duration: 5min

notes: |
  Progress by adding 2.5kg when all reps completed.
  Deload every 4th week.

Example 2: Program with Supersets and Tiers

program: GZCL Upper Lower
type: rotation
author: Cody LeFever
weeks: null
repeat: true
tags: [hypertrophy, intermediate, 4-day]
description: |
  GZCL-style upper/lower split with tiered exercises.
  T1 = heavy compounds, T2 = moderate compounds, T3 = isolation.

schedule:
  sequence: [upper, lower]
  rhythm: "1-1-0-1-1-0-0"

workouts:
  - id: upper
    name: Upper Body
    exercises:
      - name: Bench Press
        sets: 5
        reps: 3
        weight: user
        rest: "180s"
        tier: "T1"
        rpe: 9

      - name: Barbell Row
        sets: 3
        reps: 10
        weight: user
        rest: "120s"
        tier: "T2"

      # T3 superset
      - name: Lateral Raise
        sets: 3
        reps: "12-15"
        weight: user
        rest: "0s"
        tier: "T3"
        group: A

      - name: Face Pull
        sets: 3
        reps: "15-20"
        weight: user
        rest: "60s"
        tier: "T3"
        group: A

  - id: lower
    name: Lower Body
    exercises:
      - name: Back Squat
        sets: 5
        reps: 3
        weight: user
        rest: "180s"
        tier: "T1"
        rpe: 9

      - name: Romanian Deadlift
        sets: 3
        reps: 10
        weight: user
        rest: "120s"
        tier: "T2"

      - name: Leg Curl
        sets: 3
        reps: "12-15"
        weight: user
        rest: "60s"
        tier: "T3"

      - name: Calf Raises
        sets: 4
        reps: "12-15"
        weight: user
        rest: "60s"
        tier: "T3"

Example 3: Phased Program (5/3/1 Style)

program: "5/3/1 BBB"
type: phased
author: Jim Wendler
weeks: 16
repeat: true
tags: [strength, intermediate, 4-day]
description: |
  Wendler 5/3/1 Boring But Big.
  4-week cycles with progressive overload.

phases:
  - id: fives
    name: "5s Week"
  - id: threes
    name: "3s Week"
  - id: one
    name: "5/3/1 Week"
  - id: deload
    name: "Deload"

schedule:
  per_phase: [squat, bench, deadlift, ohp]
  rhythm: "1-0-1-0-1-0-1-0-0"

workouts:
  - id: squat
    name: Squat Day
    exercises:
      - name: Back Squat
        sets: 3
        reps: 5
        weight: user
        rest: "180s"
        tier: "T1"
        by_phase:
          fives:
            reps: 5
            weight: "85%"
            notes: "Sets of 5 at 65%, 75%, 85%"
          threes:
            reps: 3
            weight: "90%"
            notes: "Sets of 3 at 70%, 80%, 90%"
          one:
            reps: 1
            weight: "95%"
            notes: "5/3/1 at 75%, 85%, 95%"
          deload:
            reps: 5
            weight: "60%"

      - name: Back Squat (BBB)
        sets: 5
        reps: 10
        weight: "50%"
        rest: "90s"
        tier: "T2"
        notes: Boring But Big supplemental volume

      - name: Leg Curl
        sets: 3
        reps: "10-15"
        weight: user
        rest: "60s"
        tier: "T3"

  - id: bench
    name: Bench Day
    exercises:
      - name: Bench Press
        sets: 3
        reps: 5
        weight: user
        rest: "180s"
        tier: "T1"
        by_phase:
          fives:
            reps: 5
            weight: "85%"
          threes:
            reps: 3
            weight: "90%"
          one:
            reps: 1
            weight: "95%"
          deload:
            reps: 5
            weight: "60%"

      - name: Bench Press (BBB)
        sets: 5
        reps: 10
        weight: "50%"
        rest: "90s"
        tier: "T2"

      - name: Barbell Row
        sets: 3
        reps: "10-15"
        weight: user
        rest: "60s"
        tier: "T3"

  - id: deadlift
    name: Deadlift Day
    exercises:
      - name: Deadlift
        sets: 3
        reps: 5
        weight: user
        rest: "180s"
        tier: "T1"
        by_phase:
          fives:
            reps: 5
            weight: "85%"
          threes:
            reps: 3
            weight: "90%"
          one:
            reps: 1
            weight: "95%"
          deload:
            reps: 5
            weight: "60%"

      - name: Deadlift (BBB)
        sets: 5
        reps: 10
        weight: "50%"
        rest: "90s"
        tier: "T2"

      - name: Hanging Leg Raise
        sets: 3
        reps: "10-15"
        weight: bodyweight
        rest: "60s"
        tier: "T3"

  - id: ohp
    name: OHP Day
    exercises:
      - name: Overhead Press
        sets: 3
        reps: 5
        weight: user
        rest: "180s"
        tier: "T1"
        by_phase:
          fives:
            reps: 5
            weight: "85%"
          threes:
            reps: 3
            weight: "90%"
          one:
            reps: 1
            weight: "95%"
          deload:
            reps: 5
            weight: "60%"

      - name: Overhead Press (BBB)
        sets: 5
        reps: 10
        weight: "50%"
        rest: "90s"
        tier: "T2"

      - name: Chin-ups
        sets: 3
        reps: "6-10"
        weight: bodyweight
        rest: "90s"
        tier: "T3"

Example 4: Per-Set Prescription

workout: nSuns 531 LP - Bench Day
author: nSuns
tags: [strength, linear-progression, advanced]

exercises:
  - name: Bench Press
    sets:
      - reps: 5
        weight: "75%"
        type: working
      - reps: 3
        weight: "85%"
        type: working
      - reps: "1+"
        weight: "95%"
        type: amrap
      - reps: 3
        weight: "90%"
        type: working
      - reps: 3
        weight: "85%"
        type: working
      - reps: 3
        weight: "80%"
        type: working
      - reps: 5
        weight: "75%"
        type: backoff
      - reps: 5
        weight: "70%"
        type: backoff
      - reps: "5+"
        weight: "65%"
        type: amrap
    reps: 5
    rest: "180s"

Example 5: Advanced Techniques

workout: Arm Specialization
author: AdvancedLifter
location: gym
duration: 45min
tags: [arms, hypertrophy, advanced]
description: |
  Intensity techniques for experienced lifters.
  Allow extra recovery time after this workout.

exercises:
  - name: EZ Bar Curl
    sets: 3
    reps: "8-10"
    weight: user
    rest: "90s"
    rpe: 9
    technique: rest_pause
    notes: After failure, rest 15s, continue for 3-4 more reps

  # Superset: biceps + triceps
  - name: Incline Dumbbell Curl
    sets: 3
    reps: "10-12"
    weight: user
    rest: "0s"
    tempo: "3-0-1-0"
    technique: lengthened_partials
    range: bottom_half
    group: A

  - name: Overhead Tricep Extension
    sets: 3
    reps: "10-12"
    weight: user
    rest: "90s"
    tempo: "3-0-1-0"
    technique: lengthened_partials
    range: bottom_half
    group: A

  - name: Cable Curl
    technique: drop_set
    sets: 3
    reps: 12
    weight: user
    rest: "90s"
    notes: 12 reps, then drop weight ~20% for 10 reps, drop again for 8 reps

  - name: Cable Pushdown
    technique: myo_reps
    sets: 1
    reps: 20
    weight: user
    activation_set:
      reps: 20
      weight: user
      rest: "15s"
    mini_sets:
      reps: 5
      count: 4
      rest: "5s"

---

Summary for AI Generation

Always Include

1. workout or program name
2. exercises array with at least one exercise
3. Each exercise needs: name, sets, reps (or duration)

Recommended to Include

• author - Attribution
• description - Context for users
• rest - Important for pacing
• notes - Exercise guidance

Format Rules Checklist

• Tempo has exactly 4 numbers: "N-N-N-N"
• RPE is between 1-10
• Rest includes unit: "90s", "2min"
• Weight includes unit or uses special value
• Reps are number or valid string format
• Program has type field (rotation, phased, or custom)
• Workout IDs in programs are unique
• group field used for supersets (not superset_with)
• by_phase keys match phases[].id values

When User Asks for Variations

Use notes and description fields to explain variations rather than inventing new syntax:

exercises:
  - name: Squat
    sets: 3
    reps: "8-10"
    notes: |
      Week 1-2: Use lighter weight, focus on form
      Week 3-4: Increase weight, aim for lower rep range
      Advanced option: Add pause at bottom

When to Use Advanced Features

---

End of Specification

This document reflects the TRN Parser v0.4.0 implementation. For updates, refer to the parser source code in packages/trn-parser/src/.