seth
/
jam-cloud
mirror of https://bitbucket.org/jamkazam/jam-cloud.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity
jam-cloud/.planning/PROJECT.md

8.3 KiB
Raw Blame History

JamKazam Media Features Modernization

One-liner: Modernize session features from legacy jQuery/Rails to React patterns in jam-ui, with comprehensive test coverage

Vision

Transform session features from the legacy web project into modern React patterns in jam-ui. The features exist in the legacy codebase with jQuery dialogs and polling-based playback monitoring - we're bringing them into the React architecture with proper component structure, hooks, and Redux integration where appropriate.

Completed Features (v1.0 - v1.6):

  1. ✅ Backing Track - File-based audio playback with player controls
  2. ✅ JamTrack - Collaborative track loading with mixdown selection
  3. ✅ Session Chat - Real-time chat with message history and read/unread tracking
  4. ✅ Session Attachments - File upload/download integration with chat window
  5. ✅ Session Settings Tests - Jest unit tests and Playwright integration tests
  6. ✅ Memory Leak Prevention - Fixed memory leaks causing session screen freezes (shipped 2026-02-10)
  7. ✅ Fix Session Recording - Fixed C++ client crash and memory leaks (shipped 2026-02-25)
  8. ✅ Media Features Polish - Fixed JamTrack loading, Backing Track sync, multiple media prevention (shipped 2026-03-03)

Current Milestone (v1.7): 9. 🔧 Performance Optimization - Eliminate page freezes from excessive re-renders, optimize VU/mixer state updates

Future Work:

  • Additional recording controls (track selection, playback, management)

Context

Current State

v1.6 Media Features Polish (SHIPPED 2026-03-03):

  • ✅ JamTrack loading sequence fixed (defer UI until backend ready)
  • ✅ JamTrack player window sizing (460x350) without scrollbars
  • ✅ "Create custom mix" navigation to JamTrack editor
  • ✅ JamTrack callback cleanup (memory leak prevention)
  • ✅ Backing track sync to session screen via Redux
  • ✅ Async cleanup pattern for unmount state warnings
  • ✅ Prevent opening multiple media players simultaneously

v1.5 Fix Session Recording (SHIPPED 2026-02-25):

  • ✅ Fixed C++ client crash on Start Recording (JSON parsing fix)
  • ✅ Timer cleanup for recording hook (waitingOnStopTimer)
  • ✅ Conditional callback cleanup for window.JK (prevents race conditions)
  • ✅ Async operation guards with ignore flag pattern
  • ✅ User verified 15+ minute recording stability

v1.4 Memory Leak Prevention (SHIPPED 2026-02-10):

  • ✅ Audit and fix VU meter animation/interval cleanup
  • ✅ Audit and fix chat window WebSocket listeners and state management
  • ✅ Audit and fix session screen polling and useEffect cleanup
  • ✅ User verified 15+ minute session stability

v1.3 Session Settings Tests (SHIPPED 2026-02-08):

  • ✅ Jest unit tests for JKSessionSettingsModal component
  • ✅ Playwright integration tests for Settings modal user flows
  • ✅ Coverage for critical paths: save, cancel, validation, errors

v1.2 Session Attachments (SHIPPED 2026-02-07):

  • ✅ File attachment capability from session toolbar
  • ✅ Integration with existing chat window
  • ✅ Real-time attachment notifications via WebSocket
  • ✅ File viewing in new browser tab

v1.1 Music Session Chat (SHIPPED 2026-01-27):

  • ✅ Redux state management with WebSocket integration
  • ✅ Modeless chat window with message list and auto-scroll
  • ✅ Message composition and real-time delivery
  • ✅ Read/unread status tracking with badge indicators
  • ✅ Error handling, accessibility, and edge cases

v1.0 Media Players (SHIPPED 2026-01-14):

  • ✅ Backing Track - Complete with playback monitoring, seek controls, error handling
  • ✅ JamTrack - Complete with mixdown selection, player controls, download UI

Deferred:

  • Metronome - Tempo/sound configuration and playback

Architecture Context

  • Frontend: React 16.13.1 SPA with Redux Toolkit 1.6.1
  • Native Bridge: C++ desktop client exposed via jamClientProxy.js QWebChannel tunnel
  • State Management: Redux for global state, local component state for transient playback data
  • Legacy Reference: jQuery-based implementation in web/app/assets/javascripts/ using 500ms polling

Requirements

Validated (v1.0 - v1.5)

Core Architecture:

  • ✓ Native file dialog for track selection — v1.0
  • ✓ jamClient API integration — v1.0
  • ✓ Redux state management architecture — v1.1
  • ✓ WebSocket real-time communication — v1.1
  • ✓ Modeless dialog pattern — v1.1
  • ✓ Backend API integration — v1.2
  • ✓ File attachment upload to S3 — v1.2
  • ✓ Attachment display in chat — v1.2

Memory Management:

  • ✓ VU meter animation/interval cleanup — v1.4
  • ✓ Chat window WebSocket listener cleanup — v1.4
  • ✓ Session screen useEffect cleanup — v1.4
  • ✓ 15+ minute session stability — v1.4

Recording:

  • ✓ Recording crash fix (JSON parsing) — v1.5
  • ✓ Recording modal memory leak fixes — v1.5
  • ✓ Timer cleanup on unmount — v1.5
  • ✓ Conditional callback cleanup — v1.5
  • ✓ 15+ minute recording stability — v1.5

Media Features Polish:

  • ✓ JamTrack defer UI until backend ready — v1.6
  • ✓ JamTrack window sizing (460x350) — v1.6
  • ✓ JamTrack "Create custom mix" navigation — v1.6
  • ✓ JamTrack callback cleanup — v1.6
  • ✓ Backing track sync to session screen — v1.6
  • ✓ Async cleanup for unmount warnings — v1.6
  • ✓ Prevent multiple media players — v1.6

Out of Scope

  • Additional recording controls - Track selection, playback, management deferred
  • Backend changes - Frontend-only fixes
  • Metronome - Separate feature

Key Decisions

Decision Rationale Outcome
Keep native file dialogs Already working, platform-native UX, no need to rebuild Validated (v1.0)
Use Redux for chat state Global visibility needed for badge, history, WebSocket sync Validated (v1.1)
Reuse existing backend MusicNotation model already has S3, API, attachment_type Validated (v1.2)
Only toolbar upload Simplifies UX, avoids dual upload paths, matches common patterns Validated (v1.2)
10 MB file size limit Matches legacy app limit, reasonable for notation/audio files Validated (v1.2)
Browser handles view/download No custom preview UI, leverages native browser capabilities Validated (v1.2)
Display in chat window Natural integration, attachments are part of session communication Validated (v1.2)
Critical paths only Focus on save/cancel/validation/errors, not exhaustive coverage Confirmed (v1.3)
Both test types Jest for unit tests, Playwright for integration Confirmed (v1.3)
Conditional callback cleanup Multiple hook instances share window.JK callbacks Validated (v1.5)
Ignore flag pattern Prevents state updates on unmounted components Validated (v1.5)
Defer JamTrack UI until synchronized Prevents empty controls showing before backend ready Validated (v1.6)
WindowPortal sizing 460x350 Matches content dimensions plus padding for JamTrack Validated (v1.6)
openBackingTrack action for sync Centralized Redux + server sync for backing tracks Validated (v1.6)
Prevent multiple media players Only one media type (JamTrack/BackingTrack/Metronome) at a time Validated (v1.6)

Constraints

Technical

  • React 16 patterns only - No async/await in useEffect without proper cleanup
  • Minimal changes - Fix leaks with smallest possible code changes
  • No new dependencies - Use existing patterns and tools
  • Preserve existing behavior - Fixes should not change user-facing functionality

Testing

  • Manual verification - Session must remain stable for 15+ minutes
  • Memory monitoring - Use browser dev tools to verify no memory growth
  • Existing tests must pass - Don't break anything while fixing leaks

Critical Files

Recording (v1.5):

  • jam-ui/src/hooks/useRecordingHelpers.js - Recording hook with cleanup patterns
  • jam-ui/src/components/client/JKSessionRecordingModal.js - Recording modal with async guards
  • jam-ui/src/services/jamClientProxy.js - C++ client bridge for recording commands

Memory Management (v1.4):

  • jam-ui/src/components/client/JKSessionScreen.js - Session screen with callback cleanup
  • jam-ui/src/store/features/chatSlice.js - Chat state with MAX_MESSAGES bounds
  • jam-ui/src/store/features/mixersSlice.js - Mixer state with removeVuState

Last updated: 2026-03-03 after v1.7 Performance Optimization milestone started