# 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
