# Phase 5: JamTrack Implementation - Context

**Gathered:** 2026-01-14
**Status:** Ready for planning

<vision>
## How This Should Work

Users should be able to open a JamTrack and experience smooth, predictable playback. The experience should feel familiar to users who've used the Backing Track player from Phase 3 - same control patterns, same responsiveness, same reliability.

The key difference is JamTracks need to download and sync before playing. This download experience should be clear and reassuring - users see exactly what's happening (progress percentage, current step) and understand why they're waiting. No confusion, no "is it stuck?" moments.

Once synced, the JamTrack plays like any other media file. Users can play/pause/seek smoothly. They can also switch between different mixdowns:
- **Master mixdown** - the final polished mix
- **Existing custom mixes** - user-created mixdowns they or others have saved
- **Individual stems** - single instrument tracks

The mixdown switching should feel natural - select a different mix, audio changes. No complexity, just "here are your options, pick one."

</vision>

<essential>
## What Must Be Nailed

All three pillars are equally important:

- **Clear download/sync experience** - Users see progress (percentage, steps), understand the sync state machine (checking → downloading → keying → ready), and get clear feedback at every stage
- **Reliable playback** - Once synced, playback just works. Play/pause/seek respond instantly. No race conditions, no double-click workarounds, no mysterious pauses.
- **Smooth mixdown selection** - Users can browse available mixdowns and switch between them without friction. Master, custom mixes, and stems all accessible and working.

</essential>

<boundaries>
## What's Out of Scope

- **Custom mix creation** - Phase 5 focuses on **playing** existing custom mixes, not creating new ones. The UI to adjust individual stem volumes and save custom mixdowns is deferred to a future phase.
- **Stem editing** - Users can select individual stems to play, but can't edit stem properties (volume, pan, effects)
- **JMEP customization** - JMEP (Jam Enhancement Package) files are loaded automatically if present, but users can't customize tempo/pitch modifications
- **Advanced playback features** - Loop functionality, A-B repeat, playback speed adjustment - deferred
- **Offline mode** - JamTracks must sync with server before playback, no offline-first capability

</boundaries>

<specifics>
## Specific Ideas

**Match Backing Track player feel:**
- Users who learned the Backing Track player should feel at home
- Same control layout (play/pause/stop buttons, seek slider, time display)
- Same responsive behavior (immediate feedback, no lag)
- Same error handling approach (clear messages, recovery actions)
- Apply the same performance optimizations (visibility-aware polling, React optimizations)

**Extend with JamTrack-specific features:**
- Download progress UI (progress bar, step indicator, cancel button)
- Sync state visualization (idle → checking → downloading → keying → synchronized → error)
- Mixdown picker (dropdown or modal showing master/custom/stem hierarchy)
- Handle both modal and popup modes (like Backing Track)

**Quality bar from Phase 3:**
- No race conditions (or document known limitations)
- Comprehensive error handling (network, file, playback errors)
- Clean console output (no diagnostic logging in production)
- Cleanup on unmount (prevent stale state bugs)

</specifics>

<notes>
## Additional Context

**From Phase 4 design work:**
- Architecture already designed: JKSessionJamTrackPlayer component with 10 sub-components
- Redux state structure defined: jamTrackState (playback), downloadState (sync machine), availableMixdowns (mixdown cache)
- 6 async thunks mapped out: loadJamTrack, downloadJamTrack, checkJamTrackSync, loadJMEP, seekJamTrack, closeJamTrack
- Known bug to fix: existing loadJamTrack thunk uses wrong ID format (jamTrack.id instead of fqId)
- Complexity estimate: 2.5-3x Phase 3 Backing Track effort
- High risks identified: download/sync state machine complexity, native client race conditions

**Phase 4 preliminary roadmap suggested 9 plans:**
1. Redux infrastructure & bug fixes
2. Async thunks & WebSocket handlers
3. Player core structure
4. Playback controls
5. Mixdown selection
6. Download/sync UI
7. Modal updates
8. Error handling & edge cases
9. Performance optimization & final UAT

**User confirmed:**
- Phase 5 scope = download + play existing JamTracks + select existing mixdowns
- Custom mix **creation** deferred to future phase
- All three pillars equally important (download UX, playback reliability, mixdown selection)
- Should match Backing Track player feel and quality

</notes>

---

*Phase: 05-jamtrack-implementation*
*Context gathered: 2026-01-14*
