docs: start milestone v1.5 Fix Session Recording
Scope: - Phase 24: Fix C++ client crash on Start Recording - Phase 25: Verify Start/Stop/Pause work like desktop native app - Phase 26: Memory leak audit for recording modal Research findings: - Missing RegisterRecordingCallbacks call - Wrong method names (StartMediaRecording vs StartRecording) - Parameter format mismatch 10 requirements across 3 phases. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Nuwan
parent
0d2c76f83d
commit
1512f646ea
|
|
@ -16,9 +16,11 @@ Transform session features from the legacy web project into modern React pattern
|
|||
**Completed (v1.4):**
|
||||
6. ✅ **Memory Leak Prevention** - Fixed memory leaks causing session screen freezes (shipped 2026-02-10)
|
||||
|
||||
**Current Milestone (v1.5):**
|
||||
7. 🔧 **Fix Session Recording** - Fix C++ client crash, verify basic controls, audit memory leaks
|
||||
|
||||
**Future Work:**
|
||||
- **Metronome** - Tempo/sound configuration and playback (deferred)
|
||||
- **Recording Modal Performance** - Audit recording modal for memory leaks (deferred)
|
||||
|
||||
## Context
|
||||
|
||||
|
|
@ -105,12 +107,27 @@ Transform session features from the legacy web project into modern React pattern
|
|||
- ✓ Manual test: session stable after 15+ minutes — v1.4
|
||||
- ✓ No memory growth in browser dev tools — v1.4
|
||||
|
||||
### Active (v1.5 Fix Session Recording)
|
||||
|
||||
**Crash Fix:**
|
||||
- [ ] Fix C++ client crash when Start Recording is clicked
|
||||
- [ ] Recording modal should not freeze after clicking Start Recording
|
||||
|
||||
**Basic Controls:**
|
||||
- [ ] Start recording works like desktop native app
|
||||
- [ ] Stop recording works like desktop native app
|
||||
- [ ] Pause recording works like desktop native app
|
||||
|
||||
**Memory Leak Audit:**
|
||||
- [ ] Audit recording modal for memory leaks
|
||||
- [ ] Fix any leaking intervals, timers, or event listeners
|
||||
- [ ] Verify no memory growth while recording modal is open
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- **Recording modal** - Separate milestone for recording-specific performance
|
||||
- **New features** - Focus purely on fixing existing memory leaks
|
||||
- **Additional recording controls** - Track selection, playback, management deferred
|
||||
- **Backend changes** - Frontend-only fixes
|
||||
- **Refactoring beyond leak fixes** - Minimal changes to fix leaks
|
||||
- **Metronome** - Separate feature, not part of this milestone
|
||||
|
||||
## Key Decisions
|
||||
|
||||
|
|
@ -144,20 +161,16 @@ Transform session features from the legacy web project into modern React pattern
|
|||
|
||||
## Critical Files
|
||||
|
||||
**v1.4 Memory Leak Prevention (Current Focus):**
|
||||
- `jam-ui/src/components/client/JKSessionScreen.js` - Main session screen, parent of all session components
|
||||
- `jam-ui/src/components/client/JKVUMeterBank.js` - VU meter visualization (likely suspect)
|
||||
- `jam-ui/src/components/client/JKChatWindow.js` - Chat window with WebSocket integration
|
||||
- `jam-ui/src/components/client/JKChatMessageList.js` - Message list component
|
||||
- `jam-ui/src/store/features/sessionChatSlice.js` - Chat Redux state
|
||||
- `jam-ui/src/store/features/mixersSlice.js` - Mixer/VU meter Redux state
|
||||
**v1.5 Fix Session Recording (Current Focus):**
|
||||
- Recording modal component (needs identification)
|
||||
- `jam-ui/src/services/jamClientProxy.js` - C++ client bridge for recording commands
|
||||
- Legacy recording implementation for reference
|
||||
|
||||
**Investigation Areas:**
|
||||
- useEffect hooks without cleanup functions
|
||||
- setInterval/setTimeout without clearInterval/clearTimeout
|
||||
- requestAnimationFrame without cancelAnimationFrame
|
||||
- WebSocket event listener registration without removal
|
||||
- Redux state growing unbounded
|
||||
- jamClient recording API calls causing C++ crash
|
||||
- Recording modal useEffect cleanup
|
||||
- Timer/interval cleanup during recording
|
||||
- State management during recording lifecycle
|
||||
|
||||
---
|
||||
*Last updated: 2026-02-18 after v1.4 Memory Leak Prevention milestone complete*
|
||||
*Last updated: 2026-02-19 after v1.5 Fix Session Recording milestone started*
|
||||
|
|
|
|||
|
|
@ -0,0 +1,75 @@
|
|||
# Requirements: Fix Session Recording
|
||||
|
||||
**Defined:** 2026-02-19
|
||||
**Core Value:** Fix recording so users can record their jam sessions without crashes
|
||||
|
||||
## v1.5 Requirements
|
||||
|
||||
Requirements for fixing session recording. Each maps to roadmap phases.
|
||||
|
||||
### Crash Fix
|
||||
|
||||
- [ ] **CRASH-01**: Call RegisterRecordingCallbacks before recording operations
|
||||
- [ ] **CRASH-02**: Use correct method name StartRecording (not StartMediaRecording)
|
||||
- [ ] **CRASH-03**: Use correct method name StopRecording (not FrontStopRecording)
|
||||
- [ ] **CRASH-04**: Pass individual parameters to StartRecording (not settings object)
|
||||
|
||||
### Basic Controls
|
||||
|
||||
- [ ] **CTRL-01**: Start recording works - initiates recording like desktop native app
|
||||
- [ ] **CTRL-02**: Stop recording works - ends recording like desktop native app
|
||||
- [ ] **CTRL-03**: Pause recording works - pauses recording like desktop native app
|
||||
|
||||
### Memory Leak Audit
|
||||
|
||||
- [ ] **MEM-01**: Audit recording modal useEffect cleanup functions
|
||||
- [ ] **MEM-02**: Audit timer/interval cleanup during recording lifecycle
|
||||
- [ ] **MEM-03**: Verify no memory growth while recording modal is open
|
||||
|
||||
## Future Requirements
|
||||
|
||||
Deferred to future milestones.
|
||||
|
||||
### Recording Management
|
||||
|
||||
- **RMGT-01**: Track selection - Choose which tracks to include in recording
|
||||
- **RMGT-02**: Recording playback - Play back recordings within the modal
|
||||
- **RMGT-03**: Recording management - Save, delete, rename recordings
|
||||
|
||||
## Out of Scope
|
||||
|
||||
Explicitly excluded for this milestone.
|
||||
|
||||
| Feature | Reason |
|
||||
|---------|--------|
|
||||
| Track selection | Keep v1.5 focused on crash fix and basic controls |
|
||||
| Recording playback | Not blocking core recording functionality |
|
||||
| Recording management | Defer to future milestone |
|
||||
| Backend changes | Frontend-only fixes |
|
||||
| Metronome | Separate feature |
|
||||
|
||||
## Traceability
|
||||
|
||||
Which phases cover which requirements. Updated during roadmap creation.
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| CRASH-01 | Phase 24 | Pending |
|
||||
| CRASH-02 | Phase 24 | Pending |
|
||||
| CRASH-03 | Phase 24 | Pending |
|
||||
| CRASH-04 | Phase 24 | Pending |
|
||||
| CTRL-01 | Phase 25 | Pending |
|
||||
| CTRL-02 | Phase 25 | Pending |
|
||||
| CTRL-03 | Phase 25 | Pending |
|
||||
| MEM-01 | Phase 26 | Pending |
|
||||
| MEM-02 | Phase 26 | Pending |
|
||||
| MEM-03 | Phase 26 | Pending |
|
||||
|
||||
**Coverage:**
|
||||
- v1.5 requirements: 10 total
|
||||
- Mapped to phases: 10
|
||||
- Unmapped: 0 ✓
|
||||
|
||||
---
|
||||
*Requirements defined: 2026-02-19*
|
||||
*Last updated: 2026-02-19 after initial definition*
|
||||
|
|
@ -0,0 +1,100 @@
|
|||
# Roadmap: Fix Session Recording (v1.5)
|
||||
|
||||
**Created:** 2026-02-19
|
||||
**Milestone:** v1.5 Fix Session Recording
|
||||
**Phases:** 24-26 (continues from v1.4)
|
||||
|
||||
## Overview
|
||||
|
||||
| # | Phase | Goal | Requirements | Success Criteria |
|
||||
|---|-------|------|--------------|------------------|
|
||||
| 24 | Fix Recording Crash | Fix C++ client crash on Start Recording | CRASH-01, CRASH-02, CRASH-03, CRASH-04 | 4 |
|
||||
| 25 | Verify Basic Controls | Verify Start/Stop/Pause work like desktop native app | CTRL-01, CTRL-02, CTRL-03 | 3 |
|
||||
| 26 | Memory Leak Audit | Audit and fix memory leaks in recording modal | MEM-01, MEM-02, MEM-03 | 3 |
|
||||
|
||||
**Total:** 3 phases | 10 requirements | 10 success criteria
|
||||
|
||||
---
|
||||
|
||||
## Phase 24: Fix Recording Crash
|
||||
|
||||
**Goal:** Fix C++ client crash when Start Recording is clicked
|
||||
|
||||
**Requirements:**
|
||||
- CRASH-01: Call RegisterRecordingCallbacks before recording operations
|
||||
- CRASH-02: Use correct method name StartRecording (not StartMediaRecording)
|
||||
- CRASH-03: Use correct method name StopRecording (not FrontStopRecording)
|
||||
- CRASH-04: Pass individual parameters to StartRecording (not settings object)
|
||||
|
||||
**Success Criteria:**
|
||||
1. RegisterRecordingCallbacks is called during session or recording modal initialization
|
||||
2. StartRecording method name matches legacy implementation
|
||||
3. StopRecording method name matches legacy implementation
|
||||
4. Parameters to StartRecording match legacy signature (id, tracks, video, chat, framerate)
|
||||
|
||||
**Dependencies:** None
|
||||
|
||||
**Key Files:**
|
||||
- `jam-ui/src/hooks/useRecordingHelpers.js`
|
||||
- Recording modal component
|
||||
- Session initialization code
|
||||
|
||||
---
|
||||
|
||||
## Phase 25: Verify Basic Controls
|
||||
|
||||
**Goal:** Verify Start/Stop/Pause work like desktop native app
|
||||
|
||||
**Requirements:**
|
||||
- CTRL-01: Start recording works - initiates recording like desktop native app
|
||||
- CTRL-02: Stop recording works - ends recording like desktop native app
|
||||
- CTRL-03: Pause recording works - pauses recording like desktop native app
|
||||
|
||||
**Success Criteria:**
|
||||
1. User can click Start Recording and recording begins without crash
|
||||
2. User can click Stop Recording and recording ends properly
|
||||
3. Pause control works as expected (or is confirmed not applicable)
|
||||
|
||||
**Dependencies:** Phase 24 (crash must be fixed first)
|
||||
|
||||
**Key Files:**
|
||||
- Recording modal component
|
||||
- `jam-ui/src/hooks/useRecordingHelpers.js`
|
||||
|
||||
---
|
||||
|
||||
## Phase 26: Memory Leak Audit
|
||||
|
||||
**Goal:** Audit and fix memory leaks in recording modal
|
||||
|
||||
**Requirements:**
|
||||
- MEM-01: Audit recording modal useEffect cleanup functions
|
||||
- MEM-02: Audit timer/interval cleanup during recording lifecycle
|
||||
- MEM-03: Verify no memory growth while recording modal is open
|
||||
|
||||
**Success Criteria:**
|
||||
1. All useEffect hooks in recording modal have proper cleanup functions
|
||||
2. All timers/intervals are cleared on unmount or state change
|
||||
3. Recording modal can remain open 15+ minutes without memory growth
|
||||
|
||||
**Dependencies:** Phase 25 (controls must work to test memory)
|
||||
|
||||
**Key Files:**
|
||||
- Recording modal component
|
||||
- `jam-ui/src/hooks/useRecordingHelpers.js`
|
||||
- Any recording-related state management
|
||||
|
||||
---
|
||||
|
||||
## Research Reference
|
||||
|
||||
See: `.planning/research/RECORDING-ANALYSIS.md`
|
||||
|
||||
Key findings:
|
||||
- Missing `RegisterRecordingCallbacks` call is primary crash cause
|
||||
- Wrong method names in jam-ui vs legacy
|
||||
- Parameter format mismatch
|
||||
|
||||
---
|
||||
*Roadmap created: 2026-02-19*
|
||||
*Last updated: 2026-02-19 after initial creation*
|
||||
|
|
@ -2,19 +2,19 @@
|
|||
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated 2026-02-18)
|
||||
See: .planning/PROJECT.md (updated 2026-02-19)
|
||||
|
||||
**Core value:** Modernize session features from legacy jQuery/Rails to React patterns
|
||||
**Current focus:** Planning next milestone
|
||||
**Current focus:** v1.5 Fix Session Recording
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: Ready for next milestone
|
||||
Phase: 24 (Fix Recording Crash)
|
||||
Plan: Not started
|
||||
Status: Between milestones (v1.4 complete, v1.5 not started)
|
||||
Last activity: 2026-02-18 - v1.4 Memory Leak Prevention milestone archived
|
||||
Status: Ready for planning
|
||||
Last activity: 2026-02-19 — Roadmap created
|
||||
|
||||
Progress: Ready for `/gsd:new-milestone`
|
||||
Progress: `/gsd:discuss-phase 24` or `/gsd:plan-phase 24`
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
|
|
@ -91,16 +91,17 @@ Decisions are logged in PROJECT.md Key Decisions table.
|
|||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-02-18
|
||||
Stopped at: v1.4 milestone archived
|
||||
Last session: 2026-02-19
|
||||
Stopped at: Roadmap created
|
||||
Resume file: None
|
||||
|
||||
**v1.4 Memory Leak Prevention Milestone Archived**
|
||||
**v1.5 Fix Session Recording**
|
||||
|
||||
Archived to:
|
||||
- `.planning/milestones/v1.4-ROADMAP.md`
|
||||
- `.planning/milestones/v1.4-REQUIREMENTS.md`
|
||||
Phases:
|
||||
- Phase 24: Fix Recording Crash (CRASH-01 to CRASH-04)
|
||||
- Phase 25: Verify Basic Controls (CTRL-01 to CTRL-03)
|
||||
- Phase 26: Memory Leak Audit (MEM-01 to MEM-03)
|
||||
|
||||
**Next steps:**
|
||||
1. Merge `fix_memory_leaks_take2` branch to develop (optional)
|
||||
2. Run `/gsd:new-milestone` to start next feature milestone
|
||||
1. Run `/gsd:discuss-phase 24` to gather context
|
||||
2. Or `/gsd:plan-phase 24` to plan directly
|
||||
|
|
|
|||
|
|
@ -0,0 +1,129 @@
|
|||
# Recording Implementation Analysis
|
||||
|
||||
**Date:** 2026-02-19
|
||||
**Purpose:** Compare legacy vs jam-ui recording to identify crash cause
|
||||
|
||||
## Legacy Implementation (jQuery/Rails) - WORKING
|
||||
|
||||
### Initialization Sequence
|
||||
|
||||
In `session.js` (line 145), the legacy app registers recording callbacks during session initialization:
|
||||
|
||||
```javascript
|
||||
context.jamClient.RegisterRecordingCallbacks(
|
||||
"JK.HandleRecordingStartResult",
|
||||
"JK.HandleRecordingStopResult",
|
||||
"JK.HandleRecordingStarted",
|
||||
"JK.HandleRecordingStopped",
|
||||
"JK.HandleRecordingAborted"
|
||||
);
|
||||
```
|
||||
|
||||
The `recordingModel.js` sets up these callback handlers as global functions on `window.JK` (lines 404-408).
|
||||
|
||||
### Start Recording Flow
|
||||
|
||||
```javascript
|
||||
// recordingModel.js line 99
|
||||
jamClient.StartRecording(recording["id"], groupedTracks, recordVideo, recordChat, recordFramerate);
|
||||
```
|
||||
- Parameters: recording ID, grouped client tracks, video flag, chat flag, framerate
|
||||
|
||||
### Stop Recording Flow
|
||||
|
||||
```javascript
|
||||
// recordingModel.js line 141
|
||||
jamClient.StopRecording(recording.id, groupedTracks);
|
||||
```
|
||||
- Parameters: recording ID, grouped client tracks
|
||||
|
||||
### Key Pattern
|
||||
Callback registration happens BEFORE any recording operations.
|
||||
|
||||
## jam-ui Implementation - INCOMPLETE/BROKEN
|
||||
|
||||
### Current State
|
||||
|
||||
1. **Start Recording** (`useRecordingHelpers.js` line 101):
|
||||
```javascript
|
||||
await jamClient.StartMediaRecording(recording.id, groupedTracks, recordSettings);
|
||||
```
|
||||
- Wrong method name: `StartMediaRecording` vs `StartRecording`
|
||||
- Wrong parameters: passes `recordSettings` object instead of individual params
|
||||
|
||||
2. **Stop Recording** (line 166):
|
||||
```javascript
|
||||
await jamClient.FrontStopRecording(recording.id, groupedTracks);
|
||||
```
|
||||
- Wrong method name: `FrontStopRecording` vs `StopRecording`
|
||||
|
||||
3. **Callback Registration:**
|
||||
- Lines 408-427 define global handlers on `window.JK`
|
||||
- `RegisterRecordingCallbacks` is NEVER called
|
||||
- C++ client doesn't know which callbacks to invoke
|
||||
|
||||
## Identified Gaps
|
||||
|
||||
| Aspect | Legacy App | jam-ui | Status |
|
||||
|--------|-----------|--------|--------|
|
||||
| Callback Registration | Done in session init | Only defined, never registered | **CRITICAL GAP** |
|
||||
| StartRecording Method | `StartRecording(id, tracks, video, chat, framerate)` | `StartMediaRecording(id, tracks, settings)` | **WRONG METHOD** |
|
||||
| StopRecording Method | `StopRecording(id, tracks)` | `FrontStopRecording(id, tracks)` | **WRONG METHOD** |
|
||||
| Callback Handlers | Global functions on window.JK | Global functions on window.JK | OK |
|
||||
| Parameter Format | 5 individual params for Start | Settings object | **FORMAT MISMATCH** |
|
||||
|
||||
## Likely Cause of C++ Client Crash
|
||||
|
||||
1. **Missing RegisterRecordingCallbacks call**: The C++ client doesn't know which JavaScript callbacks to invoke when recording events occur. This causes unhandled callbacks in the C++ layer.
|
||||
|
||||
2. **Wrong method names**: The C++ client expects `StartRecording` not `StartMediaRecording`. These methods may not exist or have different signatures.
|
||||
|
||||
3. **Parameter mismatch**: The C++ client expects unpacked individual parameters, crashes trying to interpret a JavaScript object.
|
||||
|
||||
## Recommended Fix Approach
|
||||
|
||||
### Phase 1: Fix Crash (Critical)
|
||||
|
||||
1. **Add RegisterRecordingCallbacks call** - Call during recording modal mount or session initialization:
|
||||
```javascript
|
||||
await jamClient.RegisterRecordingCallbacks(
|
||||
"JK.HandleRecordingStartResult",
|
||||
"JK.HandleRecordingStopResult",
|
||||
"JK.HandleRecordingStarted",
|
||||
"JK.HandleRecordingStopped",
|
||||
"JK.HandleRecordingAborted"
|
||||
);
|
||||
```
|
||||
|
||||
2. **Fix method names**:
|
||||
- `StartMediaRecording` → `StartRecording`
|
||||
- `FrontStopRecording` → `StopRecording`
|
||||
|
||||
3. **Unpack settings into individual parameters**:
|
||||
```javascript
|
||||
jamClient.StartRecording(
|
||||
id,
|
||||
tracks,
|
||||
recordSettings.videoType || 0, // recordVideo
|
||||
recordSettings.recordChat ? 1 : 0, // recordChat
|
||||
0 // recordFramerate
|
||||
);
|
||||
```
|
||||
|
||||
### Phase 2: Verify Controls
|
||||
|
||||
After fixing the crash, verify Start/Stop/Pause work like the desktop native app.
|
||||
|
||||
### Phase 3: Memory Leak Audit
|
||||
|
||||
Audit recording modal for:
|
||||
- useEffect cleanup functions
|
||||
- Timer/interval cleanup
|
||||
- Event listener cleanup
|
||||
- State management during recording lifecycle
|
||||
|
||||
## Files to Modify
|
||||
|
||||
- Recording modal component (needs identification)
|
||||
- `jam-ui/src/hooks/useRecordingHelpers.js` - Fix method names and parameters
|
||||
- Session initialization - Add RegisterRecordingCallbacks call
|
||||
Loading…
Reference in New Issue