docs(05): capture phase context
Phase 5: JamTrack Implementation - Vision and goals documented - Essential requirements identified - Scope boundaries defined Focus: Download + play JamTracks + select existing mixdowns Quality bar: Match Backing Track player feel and reliability Out of scope: Custom mix creation (future phase) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Nuwan
parent
aed2f97c18
commit
81feb2666e
|
|
@ -0,0 +1,101 @@
|
|||
# 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*
|
||||
Loading…
Reference in New Issue