# Workout Cues System - Roadmap & Vision

## Overview

The **Workout Cues System** is an overlay system for audio-visual feedback during workouts. It provides countdowns, voice announcements, and coaching cues at key moments throughout the workout experience.

## Current Implementation (v1)

### v1 Features
- **3-2-1-GO countdown** at workout start
- Visual: Anton font, black text with white glow, displayed over greyscale video
- Audio: Boxing bell sound on "GO"
- Duration: ~3.5 seconds
- Not skippable

### v1 Files
```
/shared/workout-cues/
├── index.js              # Main WorkoutCues manager singleton
├── styles.css            # Base overlay + countdown styles
└── cues/
    └── countdown.js      # 3-2-1-GO logic with audio
```

### v1 Integration Point
- `/pages/stage/workout-overlay-manager.js` - After exercise modal opens, before timer starts

---

## Future Phases

### Phase 2: Exercise Announcements

**Goal:** Generic voice announces upcoming exercises

**Trigger Points:**
- When navigating to next exercise
- Before each new exercise starts

**Audio Format:**
- Pre-recorded generic voice (not the coach clone)
- Text-to-Speech (TTS) or pre-recorded audio files
- Format: "Next up. [Exercise Name]. [Reps] reps."

**Examples:**
- "Next up. Push up. 15 reps."
- "Next up. Squat hold. 30 seconds."
- "Next up. Alternating lunges. 10 reps each side."

**Technical Approach:**
1. **Option A: Pre-recorded library** - Record common exercise names and numbers
2. **Option B: TTS API** - Use Web Speech API or cloud TTS (AWS Polly, Google TTS)
3. **Option C: Hybrid** - TTS for exercise names, pre-recorded for common phrases

**Cue Handler:**
```javascript
// /shared/workout-cues/cues/exercise-announce.js
export const ExerciseAnnounceCue = {
  async execute(container, options) {
    // options: { exerciseName, reps, unit, side }
    // 1. Show exercise name visually
    // 2. Play audio announcement
    // 3. Brief pause
  }
};
```

---

### Phase 3: Coach Voice Clone - Form Coaching

**Goal:** Sascha's voice clone provides form cues and coaching during exercises

**Trigger Points:**
- During rest periods
- At specific moments within exercises
- Between sets

**Voice Source:**
- Voice clone of Coach Sascha (Bachmann)
- Created using AI voice cloning service (e.g., ElevenLabs, PlayHT, Descript)
- Pre-recorded phrases with the cloned voice

**Content Types:**

1. **Form Reminders**
   - "Keep your core tight"
   - "Eyes forward, chin tucked"
   - "Breathe through it"

2. **Motivation/Encouragement**
   - "You've got this"
   - "Strong finish"
   - "Last few reps, push through"

3. **Technique Tips (Exercise-Specific)**
   - Push-up: "Elbows at 45 degrees, not flared out"
   - Squat: "Drive through the heels"
   - Plank: "Don't let those hips sag"

**Technical Approach:**

1. **Audio Files on S3/CloudFront**
   - Pre-recorded coaching phrases
   - Organized by: `/audio/coaching/{category}/{phrase-id}.mp3`

2. **Coaching Map in Database**
   - Each exercise can have associated coaching cues
   - Timing metadata: when during the exercise to play each cue

3. **Smart Cue Selection**
   - Don't repeat the same cue too often
   - Rotate through available cues for variety
   - Consider workout progress (more encouragement at end)

**Data Structure:**
```javascript
// Example coaching cue data (from database or static)
const coachingCues = {
  'push-up': {
    form: [
      { audio: 'elbows-45.mp3', timing: 'mid-set' },
      { audio: 'chest-to-floor.mp3', timing: 'start' },
    ],
    motivation: [
      { audio: 'strong-push.mp3', timing: 'end-set' }
    ]
  }
};
```

---

### Phase 4: Rest Period Countdown

**Goal:** Audio-visual countdown during rest periods between sets

**Features:**
- Visual countdown timer (30, 20, 10, 5, 4, 3, 2, 1)
- Audio beeps or voice at key intervals
- Coach voice: "10 seconds" or "Get ready"

**Cue Handler:**
```javascript
// /shared/workout-cues/cues/rest-timer.js
export const RestTimerCue = {
  async execute(container, options) {
    // options: { duration: 30, voiceCues: true }
    // 1. Display countdown
    // 2. Play audio cues at intervals
    // 3. Return when rest complete
  }
};
```

---

### Phase 5: Set/Round Complete Feedback

**Goal:** Quick feedback when completing sets and rounds

**Cues:**
- "Set 2 of 3 complete"
- "Round 1 done. 2 rounds to go."
- "Great set!"

**Visual:**
- Quick text overlay with checkmark animation
- Fade out after 1-2 seconds

---

### Phase 6: Workout Progress Milestones

**Goal:** Motivational cues at workout progress points

**Trigger Points:**
- 25% complete: "Quarter of the way there"
- 50% complete: "Halfway done!"
- 75% complete: "Almost there, finish strong"
- Final exercise: "Last one! Give it everything"

---

## Technical Architecture

### Cue Registry Pattern

```javascript
// /shared/workout-cues/index.js
const cueHandlers = {
  'workout-start': CountdownCue,           // v1
  'exercise-announce': ExerciseAnnounceCue, // Phase 2
  'form-coaching': FormCoachingCue,         // Phase 3
  'rest-timer': RestTimerCue,               // Phase 4
  'set-complete': SetCompleteCue,           // Phase 5
  'workout-milestone': MilestoneCue,        // Phase 6
};
```

### Audio Management

```javascript
// /shared/workout-cues/audio-manager.js
export const AudioManager = {
  cache: new Map(),  // Preloaded audio
  queue: [],         // Queue for sequential playback

  async preload(urls) { /* Preload audio files */ },
  async play(url, options) { /* Play with volume, timing */ },
  stopAll() { /* Stop any playing audio */ },
};
```

### Integration with App.js

Key methods in `app.js` that will trigger cues:

```javascript
// When navigating to next exercise
navigateToNext() {
  WorkoutCues.exerciseAnnounce(nextExercise);
}

// When completing a set
completeCurrentAndAdvance() {
  WorkoutCues.setComplete(setNum, totalSets);
}

// Between rounds
onRoundComplete() {
  WorkoutCues.roundComplete(roundNum, totalRounds);
}
```

---

## Content Creation Workflow

### Generic Voice (Phase 2)
1. Write script for all exercise name announcements
2. Record or generate with TTS
3. Upload to S3
4. Create mapping file

### Coach Voice Clone (Phase 3)
1. Record ~30 minutes of Sascha speaking coaching phrases
2. Create voice clone with chosen service
3. Generate all coaching phrases with clone
4. Review and quality check
5. Upload to S3
6. Create coaching cue database/mapping

---

## File Organization (Future State)

```
/shared/workout-cues/
├── index.js                    # Main CueManager
├── audio-manager.js            # Audio loading/playback
├── styles.css                  # All cue styles
├── cues/
│   ├── countdown.js            # 3-2-1-GO
│   ├── exercise-announce.js    # Voice announcements
│   ├── form-coaching.js        # Coach voice clips
│   ├── rest-timer.js           # Rest countdown
│   ├── set-complete.js         # Set feedback
│   └── workout-milestone.js    # Progress cues
└── data/
    └── coaching-cues.json      # Coaching phrase mappings
```

---

## Audio Assets (S3 Structure)

```
s3://coachbachmann-site-images/audio/
├── cues/
│   └── boxing-bell.mp3         # GO sound
├── announcements/              # Generic voice
│   ├── next-up.mp3
│   ├── exercises/
│   │   ├── push-up.mp3
│   │   ├── squat.mp3
│   │   └── ...
│   └── numbers/
│       ├── 1.mp3 - 30.mp3
│       └── ...
└── coaching/                   # Sascha voice clone
    ├── form/
    │   ├── core-tight.mp3
    │   ├── breathe.mp3
    │   └── ...
    └── motivation/
        ├── you-got-this.mp3
        ├── strong-finish.mp3
        └── ...
```

---

## Success Metrics

- **User engagement**: Do users complete more workouts with audio cues?
- **Feedback**: User satisfaction surveys
- **Retention**: Does coaching increase return usage?
- **Completion rate**: Do users skip fewer exercises?

---

## Notes

- All audio should be optional/configurable (user preference)
- Consider mobile data usage (preload vs stream)
- Accessibility: visual cues should work without audio
- Volume controls for different cue types