Fix: media stream resource leak + lazy idle cleanup

[amitayks]

Problem

The app creates system-level media resources (ScreenCaptureKit sessions, camera streams, AudioContext, WebSocket connections, main-process timers) during recording but never cleans them up on window close, app quit, or view transitions.

On macOS, ScreenCaptureKit sessions are managed by WindowServer — outside the Electron process boundary. When the process terminates without calling .stop() on stream tracks, those sessions become orphans. Over multiple dev restarts this accumulates, eventually starving the GPU readback path that captureStream + MediaRecorder depend on — causing recordings to produce only a handful of frames. The only recovery is a full system reboot.

Resources that were leaking

Resource	Created in	Cleanup existed?
screenStream tracks	updateScreenStream()	Only when switching source — not on quit/close
cameraStream tracks	updateCameraStream()	Only when switching source — not on quit/close
audioStream tracks	updateAudioStream()	Only when switching source — not on quit/close
AudioContext	startAudioMeter()	On source change — not on quit/close
MediaRecorder × 2	startRecording()	On stopRecording() — not on quit during recording
scribeWs WebSocket	startRecording()	On stopRecording() — not on quit during recording
Mouse trail timer	start-mouse-trail IPC	On stop-mouse-trail — not on main process quit

Fix: cleanup on quit

Added a centralized cleanupAllMedia() function that synchronously stops all media resources. Called from:

• beforeunload in the renderer — releases all streams, AudioContext, MediaRecorder, WebSocket, intervals, and animation frames on window close / Cmd+Q
• before-quit in the main process — clears the mouse trail timer independently

Verified via macOS unified logging (/usr/bin/log stream) that every SCStream startCapture gets a matching stopCapture on normal quit.

Improvement: lazy idle cleanup (30s timeout)

Beyond the leak fix, streams were also staying alive unnecessarily. The camera and screen capture sessions remain active even when the user is in the timeline/editor view — where they're not needed at all (the editor plays back recorded files, not live streams).

New behavior: When the user leaves the recording view, a 30-second idle timer starts. If they don't return to recording within that window, all media streams are released. When they navigate back to recording, streams are re-acquired automatically.

This means:

• Quick back-and-forth (record → review → record): streams stay alive, no re-acquisition cost
• Extended editing session: streams cleaned after 30s idle, freeing camera/screen/GPU resources
• Leak window shrinks from "forever until app close" to "30 seconds max"

Verification

Confirmed via macOS ScreenCaptureKit system logs:

• Normal quit (Cmd+Q): all sessions paired (start → stop) ✅
• Idle cleanup: sessions released after timeout ✅
• Force kill (Ctrl+C / terminal): sessions leak (expected — OS limitation, beforeunload doesn't fire)

Related

Fixes included in PR #3

Related commits

• 0b04bc2 — feat: add media stream cleanup on quit and lazy idle release

[m13v]

Really solid analysis of the leak sources. We dealt with nearly identical issues building macos-session-replay (our screen recording SDK for Fazm). ScreenCaptureKit sessions are indeed managed by WindowServer, and orphaned sessions accumulate until they starve the GPU readback path exactly as you described.

A few things we learned:

1. The beforeunload approach is good but unreliable for force-quit scenarios. We added a secondary cleanup: on app launch, we enumerate existing SCK sessions via SCShareableContent.current and compare against known active sessions. Any orphans get cleaned up immediately.

2. For the idle timeout, 30 seconds is reasonable. We settled on a similar approach but also pause the SCStream rather than fully tearing it down. Calling stream.stopCapture() releases the GPU readback resources while keeping the session object alive, so re-acquisition on return is much faster (no new TCC permission check, no new WindowServer session).

3. One subtle leak we missed initially: CMSampleBuffer references from the stream output delegate. If your frame handler retains sample buffers (for thumbnail generation, etc.), those hold IOSurface backing stores that pin GPU memory. We had to explicitly call CMSampleBufferInvalidate in our cleanup path.

The 30s lazy cleanup pattern is a good balance between responsiveness and resource usage.

[m13v]

Here is our ScreenCaptureKit service that handles the cleanup lifecycle we mentioned (session start/stop, delegate management, resource teardown). It is part of our open-source macOS session replay library:

https://github.com/m13v/macos-session-replay/blob/main/Sources/SessionReplay/ScreenCaptureService.swift