diff --git a/.planning/phases/05-jamtrack-implementation/05-CONTEXT.md b/.planning/phases/05-jamtrack-implementation/05-CONTEXT.md new file mode 100644 index 000000000..c33f42266 --- /dev/null +++ b/.planning/phases/05-jamtrack-implementation/05-CONTEXT.md @@ -0,0 +1,101 @@ +# Phase 5: JamTrack Implementation - Context + +**Gathered:** 2026-01-14 +**Status:** Ready for planning + + +## 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." + + + + +## 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. + + + + +## 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 + + + + +## 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) + + + + +## 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 + + + +--- + +*Phase: 05-jamtrack-implementation* +*Context gathered: 2026-01-14*