Phase 2: Core Recording Engine

[coderabbitai]

🎯 Objective

Implement the core screen recording functionality using Windows Desktop Duplication API with cursor tracking, audio capture, and video encoding.

📋 Tasks

2.1 Windows Desktop Duplication API Integration ⚡ HIGH PRIORITY

• Research available libraries:
  • Evaluate windows-capture npm package
  • Assess if custom native C++ addon is needed
  • Document pros/cons of each approach
• Choose implementation strategy
• If using native addon:
  • Set up node-addon-api project structure
  • Create C++ bindings to DXGI Desktop Duplication API
  • Implement IDXGIOutputDuplication interface wrapper
  • Implement frame acquisition from GPU
  • Test on different GPU vendors (NVIDIA, AMD, Intel)
• If using library:
  • Install and configure chosen library
  • Create wrapper module for consistent API
• Implement features:
  • Capture frames from specific monitor
  • Support multi-monitor selection
  • Target 60 FPS minimum capture rate
  • Implement frame buffer retrieval
  • Add frame timing/synchronization
• Set up IPC for streaming frames to renderer process
• Optimize memory usage (reuse buffers)
• Add error handling for GPU unavailable scenarios

2.2 Cursor Position Tracking

File: electron/recorder/cursorTracking.js

• Create cursor tracking module
• Integrate Windows GetCursorPos API
  • Capture cursor position at 120Hz+ frequency
  • Store X/Y coordinates with precise timestamps
• Track cursor state changes:
  • Detect cursor icon type (arrow, hand, text, etc.)
  • Record cursor visibility state
• Implement click detection:
  • Capture left mouse button events
  • Capture right mouse button events
  • Store click events with timestamps
  • Add optional keyboard event tracking
• Create synchronized data structure:
  • Align cursor data with frame timestamps
  • Implement efficient storage format (JSON/binary)
  • Add data serialization for saving

2.3 Audio Capture

• Implement system audio capture:
  • Research Windows WASAPI vs Web Audio API
  • Choose implementation approach
  • Capture desktop audio output
  • Handle audio device selection
• Implement microphone capture:
  • Add microphone input support
  • Allow user to toggle mic on/off
  • Mix system audio and mic audio
• Audio processing:
  • Synchronize audio with video frames
  • Handle sample rate conversion if needed
  • Add audio level monitoring
  • Implement audio buffer management

2.4 Video Encoding Pipeline

File: electron/recorder/videoEncoder.js

• Integrate FFmpeg:
  • Download and bundle FFmpeg binaries
  • Create FFmpeg process wrapper
  • Set up frame streaming to FFmpeg stdin
• Implement encoding options:
  • Configure H.264 codec settings
  • Support quality presets (720p, 1080p, 1440p, 4K)
  • Configure bitrate settings
  • Set up frame rate control
• Create encoding modes:
  • Real-time encoding mode (encode while recording)
  • Raw capture mode (save frames, encode later)
  • Allow user to choose mode
• Audio encoding:
  • Mux audio streams with video
  • Configure AAC audio codec
  • Sync audio/video streams
• Add progress monitoring:
  • Parse FFmpeg output for progress
  • Calculate encoding speed
  • Estimate time remaining

2.5 Recording Session Management

• Create recording controller:
  • Start recording command
  • Stop recording command
  • Pause/resume functionality
  • Cancel recording with cleanup
• Implement session state:
  • Track recording status
  • Store session metadata
  • Calculate recording duration
• File management:
  • Generate unique filenames
  • Save to user-specified directory
  • Handle disk space checks
  • Implement auto-save on crash

🎯 Success Criteria

• Can capture screen at 60 FPS or higher
• Cursor position is accurately tracked
• Audio is captured and synchronized
• Video is encoded to MP4 successfully
• Can record, pause, and stop without crashes

🔧 Technical Notes

• Desktop Duplication API requires Windows 8 or later
• GPU must support DirectX 11.1
• Consider fallback for older systems (GDI+ capture)

🔗 Related

• Original feature request: make screen recorder #1
• Depends on: Phase 1

Estimated Duration: Weeks 2-3

[traycerai]

Plan

Observations

The repository is currently empty except for a README. Phase 1 (basic project setup) appears incomplete, so this plan includes minimal foundational structure. The implementation prioritizes the Desktop Duplication API approach over libraries for maximum performance and control, uses native addons for Windows-specific features, and leverages ffmpeg-static for cross-platform FFmpeg bundling.

Approach

This plan implements a high-performance Windows screen recorder using the Desktop Duplication API for 60+ FPS capture, native cursor tracking at 120Hz+, multi-channel audio capture (system + microphone), and FFmpeg-based H.264 encoding. The architecture uses Electron's main process for recording logic with IPC communication to the renderer, native C++ addons for Windows API integration, and a modular design separating capture, encoding, and session management concerns.

Reasoning

Listed the repository structure and found it empty. Read the README confirming a new project. Searched for existing configuration files and found none. Researched Windows Desktop Duplication API integration options, FFmpeg bundling strategies, audio capture approaches, and native addon development patterns for Electron to inform the implementation strategy.

Proposed File Changes

📄 package.json ^(NEW) 🔗

Create the main package.json file for the Electron application with the following configuration:

• Set name to "screen-recorder" and version to "0.1.0"
• Add main entry point as "electron/main.js"
• Configure scripts:
  • "start": Launch Electron in development mode
  • "build": Build native addons using node-gyp
  • "rebuild": Rebuild native addons for Electron
  • "package": Package the application using electron-builder
• Add dependencies:
  • "electron": Latest stable version for the desktop framework
  • "fluent-ffmpeg": For FFmpeg command interface
  • "ffmpeg-static": For bundled FFmpeg binaries
  • "ffprobe-static": For FFprobe binaries
  • "node-addon-api": For native C++ addon development
  • "bindings": For loading native modules
• Add devDependencies:
  • "electron-builder": For packaging the application
  • "node-gyp": For building native addons
• Configure electron-builder settings:
  • Set appId to "com.omniblocks.screenrecorder"
  • Configure asarUnpack to exclude ffmpeg-static and native addons from ASAR archive
  • Set target platforms to Windows (win32)
  • Configure file patterns to include electron directory and node_modules

📄 binding.gyp ^(NEW) 🔗

Create the node-gyp configuration file for building native C++ addons:

• Define target "desktop_duplication_addon" for the Desktop Duplication API wrapper
• Set sources to include "native/desktop_duplication/desktop_duplication.cc" and "native/desktop_duplication/frame_capturer.cc"
• Include node-addon-api headers
• Add Windows-specific configurations:
  • Link against d3d11.lib, dxgi.lib, and windowscodecs.lib
  • Define UNICODE and _UNICODE macros
  • Set C++ standard to C++17
• Define target "cursor_tracking_addon" for cursor tracking
• Set sources to include "native/cursor_tracking/cursor_tracking.cc"
• Link against user32.lib for GetCursorPos and mouse event APIs
• Configure conditions to ensure builds only on Windows platform
• Set exception handling and runtime library flags

📁 electron ^(NEW) 🔗

Create the main Electron directory to house all main process code, IPC handlers, and recording logic.

📄 electron/main.js ^(NEW) 🔗

Create the Electron main process entry point:

• Import required Electron modules (app, BrowserWindow, ipcMain, screen)
• Import the recording controller from electron/recorder/recordingController.js
• Configure FFmpeg paths using ffmpeg-static and ffprobe-static with ASAR unpacking support (replace 'app.asar' with 'app.asar.unpacked')
• Create main window function:
  • Set window dimensions (1200x800)
  • Configure webPreferences with nodeIntegration disabled and contextIsolation enabled
  • Set up preload script path
  • Load the renderer HTML file
• Set up IPC handlers:
  • "get-displays": Return list of available displays using screen.getAllDisplays()
  • "start-recording": Invoke recording controller start method with display ID and options
  • "stop-recording": Invoke recording controller stop method
  • "pause-recording": Invoke recording controller pause method
  • "resume-recording": Invoke recording controller resume method
  • "get-recording-status": Return current recording state
• Handle app lifecycle events (ready, window-all-closed, activate)
• Add error handling for uncaught exceptions

📄 electron/preload.js ^(NEW) 🔗

Create the preload script for secure IPC communication between renderer and main process:

• Import contextBridge and ipcRenderer from Electron
• Expose safe API to renderer process via contextBridge.exposeInMainWorld:
  • "screenRecorder" namespace with methods:
    • getDisplays(): Invoke "get-displays" IPC
    • startRecording(displayId, options): Invoke "start-recording" IPC
    • stopRecording(): Invoke "stop-recording" IPC
    • pauseRecording(): Invoke "pause-recording" IPC
    • resumeRecording(): Invoke "resume-recording" IPC
    • getRecordingStatus(): Invoke "get-recording-status" IPC
    • onRecordingProgress(callback): Listen to "recording-progress" events
    • onRecordingComplete(callback): Listen to "recording-complete" events
    • onRecordingError(callback): Listen to "recording-error" events
• Ensure all IPC channels are whitelisted and validated

📁 native ^(NEW) 🔗

Create the native directory to house all C++ native addon source code for Windows API integration.

📁 native/desktop_duplication ^(NEW) 🔗

Create directory for Desktop Duplication API native addon implementation.

📄 native/desktop_duplication/desktop_duplication.cc ^(NEW) 🔗

Create the main C++ source file for Desktop Duplication API addon:

• Include necessary headers: napi.h, d3d11.h, dxgi1_2.h, wincodec.h
• Implement initialization function:
  • Create D3D11 device and device context
  • Enumerate DXGI adapters and outputs
  • Support multi-GPU systems (NVIDIA, AMD, Intel)
  • Initialize IDXGIOutputDuplication interface for specified monitor
  • Handle errors for unsupported systems (pre-Windows 8, no DX11.1)
• Implement frame capture function:
  • Call AcquireNextFrame() on IDXGIOutputDuplication
  • Handle timeout scenarios (no new frame available)
  • Retrieve DXGI_OUTDUPL_FRAME_INFO for metadata
  • Get IDXGIResource from frame
  • Query for ID3D11Texture2D interface
  • Copy texture to staging texture for CPU access
  • Map staging texture to get pixel data
  • Convert BGRA to RGBA if needed
  • Return frame data as Node.js Buffer with timestamp
  • Release frame and unmap resources
• Implement cleanup function to release all COM interfaces
• Implement monitor enumeration function returning array of display info
• Export Node-API module with Init function
• Register functions: initialize, captureFrame, cleanup, getDisplays
• Add error handling for all DirectX operations with descriptive messages

📄 native/desktop_duplication/frame_capturer.cc ^(NEW) 🔗

Create helper C++ class for optimized frame capture:

• Define FrameCapturer class with private members:
  • ID3D11Device pointer
  • ID3D11DeviceContext pointer
  • IDXGIOutputDuplication pointer
  • ID3D11Texture2D staging texture pointer
  • Frame buffer pool for memory reuse
  • Frame timing tracker
• Implement constructor:
  • Accept monitor index parameter
  • Initialize DirectX resources
  • Create staging texture with CPU read access
  • Allocate frame buffer pool (3-5 buffers)
• Implement CaptureFrame method:
  • Acquire next frame with 16ms timeout (for 60 FPS)
  • Check frame timing to maintain target FPS
  • Copy frame to staging texture
  • Map texture and copy to reused buffer from pool
  • Unmap and release frame
  • Return buffer with metadata (timestamp, frame number, dimensions)
• Implement GetFrameRate method returning current capture rate
• Implement SetTargetFPS method to adjust timeout values
• Implement destructor to clean up all DirectX resources
• Add error recovery for GPU device lost scenarios
• Optimize for minimal CPU usage and memory allocations

📁 native/cursor_tracking ^(NEW) 🔗

Create directory for cursor tracking native addon implementation.

📄 native/cursor_tracking/cursor_tracking.cc ^(NEW) 🔗

Create the C++ source file for cursor tracking addon:

• Include headers: napi.h, windows.h, winuser.h
• Implement GetCursorPosition function:
  • Call Windows GetCursorPos API to get screen coordinates
  • Return JavaScript object with x, y coordinates and high-precision timestamp
• Implement GetCursorInfo function:
  • Call GetCursorInfo API to get cursor state
  • Determine cursor visibility (hidden/visible)
  • Get cursor handle and type (arrow, hand, text, wait, etc.)
  • Return object with position, visibility, and cursor type
• Implement mouse event tracking:
  • Set up low-level mouse hook using SetWindowsHookEx
  • Capture WM_LBUTTONDOWN, WM_LBUTTONUP for left clicks
  • Capture WM_RBUTTONDOWN, WM_RBUTTONUP for right clicks
  • Store events in thread-safe queue with timestamps
  • Implement GetMouseEvents function to retrieve queued events
• Implement StartTracking function:
  • Accept target frequency parameter (default 120Hz)
  • Create high-resolution timer thread
  • Poll cursor position at specified frequency
  • Store positions in circular buffer
  • Return tracking session ID
• Implement StopTracking function to halt tracking and cleanup
• Implement GetTrackingData function:
  • Return array of cursor positions with timestamps
  • Include mouse click events merged with position data
  • Clear retrieved data from buffer
• Export Node-API module with all functions
• Add thread safety for concurrent access
• Optimize for minimal overhead (< 1% CPU usage)

📁 electron/recorder ^(NEW) 🔗

Create directory for all recording-related modules including capture, encoding, and session management.

📄 electron/recorder/desktopCapture.js ^(NEW) 🔗

Create the desktop capture module that wraps the native Desktop Duplication addon:

• Import the native desktop_duplication addon using bindings package
• Import EventEmitter for event-driven architecture
• Define DesktopCapture class extending EventEmitter:
  • Constructor accepts monitor ID and target FPS (default 60)
  • Initialize native addon with specified monitor
  • Set up frame buffer queue
  • Track capture statistics (frames captured, dropped frames, actual FPS)
• Implement start method:
  • Validate monitor ID exists
  • Initialize native capturer
  • Start capture loop using setImmediate for non-blocking iteration
  • In each iteration:
    • Call native captureFrame function
    • Calculate frame timing and actual FPS
    • Emit 'frame' event with frame data and metadata
    • Handle frame drops if capture falls behind
    • Continue loop if still recording
  • Emit 'started' event
• Implement stop method:
  • Set recording flag to false
  • Wait for current frame to complete
  • Call native cleanup function
  • Emit 'stopped' event with final statistics
• Implement pause/resume methods for temporary suspension
• Implement getStatistics method returning capture metrics
• Add error handling:
  • Catch native addon errors
  • Emit 'error' events
  • Implement fallback for GPU device lost
• Add support for multi-monitor selection
• Optimize memory usage by reusing frame buffers

📄 electron/recorder/cursorTracking.js ^(NEW) 🔗

Create the cursor tracking module as specified in the GitHub issue:

• Import the native cursor_tracking addon using bindings package
• Import EventEmitter
• Define CursorTracker class extending EventEmitter:
  • Constructor accepts tracking frequency (default 120Hz)
  • Initialize tracking data storage array
  • Set up mouse event queue
• Implement start method:
  • Call native StartTracking with specified frequency
  • Store tracking session ID
  • Set up periodic data retrieval (every 100ms to avoid buffer overflow)
  • In retrieval callback:
    • Call native GetTrackingData to get cursor positions
    • Call native GetMouseEvents to get click events
    • Merge cursor positions with click events by timestamp
    • Store in synchronized data structure with format:
      • timestamp (high-precision)
      • x, y coordinates
      • cursorType (arrow, hand, text, etc.)
      • visibility (boolean)
      • clickEvent (null, 'left-down', 'left-up', 'right-down', 'right-up')
  • Emit 'started' event
• Implement stop method:
  • Call native StopTracking
  • Retrieve any remaining data
  • Emit 'stopped' event
• Implement getData method:
  • Return complete tracking data array
  • Optionally filter by time range
• Implement saveToFile method:
  • Accept file path parameter
  • Serialize tracking data to JSON format
  • Write to file asynchronously
  • Support both JSON and binary formats for efficiency
• Implement synchronizeWithFrames method:
  • Accept frame timestamps array
  • Align cursor data with video frame timestamps
  • Interpolate cursor positions between samples if needed
  • Return synchronized data structure
• Add getStatistics method returning:
  • Total tracking duration
  • Number of cursor position samples
  • Number of click events
  • Average sampling rate
• Handle errors from native addon gracefully

📄 electron/recorder/audioCapture.js ^(NEW) 🔗

Create the audio capture module for system and microphone audio:

• Import required modules: EventEmitter, child_process for native audio tools
• Consider using @thesusheer/node-miniaudio or implementing WASAPI wrapper
• Define AudioCapture class extending EventEmitter:
  • Constructor accepts configuration:
    • captureSystemAudio (boolean, default true)
    • captureMicrophone (boolean, default false)
    • sampleRate (default 48000 Hz)
    • channels (default 2 for stereo)
    • bitDepth (default 16)
  • Initialize audio buffers for system and microphone streams
• Implement start method:
  • If captureSystemAudio is true:
    • Initialize WASAPI loopback capture for system audio
    • Use ActivateAudioInterfaceAsync on Windows 10+
    • Set up audio format (PCM, sample rate, channels)
    • Start capture thread
  • If captureMicrophone is true:
    • Enumerate available microphone devices
    • Use default or user-selected microphone
    • Initialize WASAPI capture for microphone
    • Start separate capture thread
  • Set up audio mixing if both sources enabled:
    • Create mixer that combines both streams
    • Normalize audio levels
    • Synchronize timestamps
  • Emit 'started' event
• Implement audio buffer management:
  • Use circular buffers to prevent memory overflow
  • Target 2-3 seconds of buffered audio
  • Emit 'audio-data' events with audio chunks and timestamps
• Implement stop method:
  • Stop all capture threads
  • Flush remaining audio buffers
  • Release audio device resources
  • Emit 'stopped' event
• Implement pause/resume methods
• Implement getAudioDevices method:
  • Enumerate system audio devices
  • Return list with device IDs and names
• Implement setMicrophoneDevice method for device switching
• Implement getAudioLevel method:
  • Calculate current audio level (RMS or peak)
  • Return separate levels for system and microphone
  • Useful for UI visualization
• Add synchronization with video:
  • Maintain precise timestamps for all audio samples
  • Implement getSynchronizedAudio method accepting video timestamp range
• Handle audio device changes (device unplugged, etc.)
• Add error handling for audio device access failures

📄 electron/recorder/videoEncoder.js ^(NEW) 🔗

Create the video encoding pipeline module as specified in the GitHub issue:

• Import fluent-ffmpeg, path, fs, EventEmitter
• Import ffmpeg-static and ffprobe-static for binary paths
• Define VideoEncoder class extending EventEmitter:
  • Constructor accepts encoding configuration:
    • outputPath (file path for final video)
    • resolution (720p, 1080p, 1440p, 4K)
    • frameRate (default 60)
    • videoBitrate (calculated based on resolution)
    • codec (default 'libx264')
    • preset (ultrafast, fast, medium, slow for quality/speed tradeoff)
    • encodingMode ('realtime' or 'raw-capture')
  • Set FFmpeg binary paths using ffmpeg-static with ASAR unpacking
  • Initialize encoding statistics
• Implement start method:
  • Create FFmpeg command using fluent-ffmpeg
  • Configure input:
    • Set input format to rawvideo
    • Set pixel format to rgba or bgra
    • Set frame size based on resolution
    • Set frame rate
    • Use pipe:0 for stdin input
  • Configure video encoding:
    • Set codec to libx264
    • Set bitrate based on resolution (e.g., 5000k for 1080p, 10000k for 4K)
    • Set preset for encoding speed
    • Add -movflags +faststart for web playback
    • Set keyframe interval (GOP size)
  • Configure audio encoding:
    • Set audio codec to aac
    • Set audio bitrate (192k or 256k)
    • Set audio sample rate (48000 Hz)
  • Set output format to mp4
  • Set output path
  • If encodingMode is 'realtime':
    • Start FFmpeg process immediately
    • Pipe frames directly to stdin as they arrive
  • If encodingMode is 'raw-capture':
    • Store frames to temporary directory
    • Encode after recording completes
  • Listen to FFmpeg events:
    • 'progress': Parse and emit encoding progress
    • 'error': Handle encoding errors
    • 'end': Emit completion event
  • Emit 'started' event
• Implement encodeFrame method:
  • Accept frame buffer and timestamp
  • If realtime mode:
    • Write frame buffer to FFmpeg stdin
    • Handle backpressure if FFmpeg can't keep up
  • If raw-capture mode:
    • Save frame to temporary file with timestamp
  • Update frame counter and statistics
• Implement encodeAudio method:
  • Accept audio buffer and timestamp
  • Write to FFmpeg audio input
  • Ensure audio/video synchronization
• Implement stop method:
  • If realtime mode:
    • Close FFmpeg stdin
    • Wait for FFmpeg to finish encoding
  • If raw-capture mode:
    • Start FFmpeg process
    • Feed all saved frames in order
    • Wait for completion
  • Clean up temporary files
  • Emit 'stopped' event with final file path
• Implement pause/resume methods:
  • For realtime mode: buffer frames during pause
  • For raw-capture mode: simply stop saving frames
• Implement getProgress method:
  • Parse FFmpeg output for progress information
  • Calculate:
    • Frames encoded
    • Current encoding FPS
    • Time elapsed
    • Estimated time remaining
    • Output file size
  • Return progress object
• Implement quality preset configurations:
  • Map resolution strings to actual dimensions
  • Calculate appropriate bitrates
  • Set FFmpeg preset based on user choice
• Add error handling:
  • Handle FFmpeg process crashes
  • Handle disk space issues
  • Handle invalid frame data
  • Emit 'error' events with descriptive messages
• Optimize for performance:
  • Use hardware acceleration if available (h264_nvenc, h264_qsv, h264_amf)
  • Implement frame buffer pooling
  • Minimize memory copies

📄 electron/recorder/recordingController.js ^(NEW) 🔗

Create the main recording session management controller:

• Import all recorder modules:
  • DesktopCapture from electron/recorder/desktopCapture.js
  • CursorTracker from electron/recorder/cursorTracking.js
  • AudioCapture from electron/recorder/audioCapture.js
  • VideoEncoder from electron/recorder/videoEncoder.js
• Import EventEmitter, path, fs
• Define RecordingController class extending EventEmitter:
  • Constructor initializes:
    • currentSession object (null when not recording)
    • sessionMetadata object
    • recordingState ('idle', 'recording', 'paused', 'encoding')
  • Store references to all component instances
• Implement startRecording method:
  • Accept parameters:
    • displayId (monitor to record)
    • outputDirectory (where to save file)
    • options object (resolution, fps, audio settings, encoding mode)
  • Validate parameters:
    • Check display exists
    • Verify output directory is writable
    • Check available disk space (warn if < 1GB)
  • Generate unique filename using timestamp
  • Create session object:
    • sessionId (UUID)
    • startTime (timestamp)
    • displayId
    • outputPath
    • options
  • Initialize all components:
    • Create DesktopCapture instance with displayId and FPS
    • Create CursorTracker instance with 120Hz frequency
    • Create AudioCapture instance with audio options
    • Create VideoEncoder instance with output path and encoding options
  • Set up event handlers:
    • DesktopCapture 'frame' event:
      • Pass frame to VideoEncoder.encodeFrame
      • Update frame counter
      • Emit 'recording-progress' to renderer
    • AudioCapture 'audio-data' event:
      • Pass audio to VideoEncoder.encodeAudio
    • VideoEncoder 'progress' event:
      • Emit 'encoding-progress' to renderer
    • Handle errors from all components
  • Start all components in sequence:
    • Start AudioCapture first (to avoid missing audio)
    • Start CursorTracker
    • Start DesktopCapture
    • Start VideoEncoder
  • Set recordingState to 'recording'
  • Store session in currentSession
  • Emit 'recording-started' event
  • Return session object
• Implement stopRecording method:
  • Validate recording is active
  • Set recordingState to 'encoding'
  • Stop all components in reverse order:
    • Stop DesktopCapture first
    • Stop CursorTracker
    • Stop AudioCapture
    • Stop VideoEncoder (this may take time for final encoding)
  • Save cursor tracking data:
    • Get data from CursorTracker
    • Synchronize with frame timestamps
    • Save to JSON file alongside video
  • Calculate session statistics:
    • Total duration
    • Total frames captured
    • Average FPS
    • Final file size
  • Update session metadata
  • Set recordingState to 'idle'
  • Emit 'recording-complete' event with session data
  • Clear currentSession
  • Return final session object with file paths
• Implement pauseRecording method:
  • Validate recording is active
  • Pause all components:
    • Pause DesktopCapture
    • Pause CursorTracker
    • Pause AudioCapture
    • Pause VideoEncoder
  • Set recordingState to 'paused'
  • Store pause timestamp
  • Emit 'recording-paused' event
• Implement resumeRecording method:
  • Validate recording is paused
  • Resume all components in same order as start
  • Calculate pause duration
  • Adjust timestamps to account for pause
  • Set recordingState to 'recording'
  • Emit 'recording-resumed' event
• Implement cancelRecording method:
  • Stop all components
  • Delete partial output files
  • Clean up temporary files
  • Set recordingState to 'idle'
  • Emit 'recording-cancelled' event
• Implement getRecordingStatus method:
  • Return object with:
    • recordingState
    • currentSession (if active)
    • duration (if recording)
    • framesCaptured
    • currentFPS
    • audioLevel
    • outputFileSize (if available)
• Implement getSessionMetadata method returning current session info
• Add auto-save on crash:
  • Listen to process 'exit' and 'SIGINT' events
  • If recording active, attempt to stop gracefully
  • Save partial recording with '_incomplete' suffix
• Add disk space monitoring:
  • Check available space every 10 seconds during recording
  • If space < 100MB, emit warning
  • If space < 50MB, auto-stop recording
• Implement error recovery:
  • If DesktopCapture fails, attempt restart
  • If VideoEncoder fails, switch to raw-capture mode
  • Log all errors for debugging
• Export singleton instance of RecordingController

📁 renderer ^(NEW) 🔗

Create directory for renderer process files (UI).

📄 renderer/index.html ^(NEW) 🔗

Create the main HTML file for the renderer process:

• Set up basic HTML5 structure with DOCTYPE and meta tags
• Set title to "Screen Recorder"
• Link to CSS file at renderer/styles.css
• Create UI structure:
  • Header section with app title
  • Display selection dropdown (populated via IPC)
  • Recording controls section:
    • Start recording button
    • Stop recording button (disabled initially)
    • Pause/Resume button (disabled initially)
  • Settings section:
    • Resolution selector (720p, 1080p, 1440p, 4K)
    • FPS selector (30, 60)
    • Audio options checkboxes (system audio, microphone)
    • Encoding mode selector (realtime, raw-capture)
    • Output directory selector
  • Status section:
    • Recording status indicator
    • Duration display
    • FPS counter
    • Audio level meter
  • Progress section (shown during encoding):
    • Progress bar
    • Encoding speed display
    • Time remaining estimate
• Include script tag for renderer/app.js
• Add minimal inline styles for basic layout

📄 renderer/app.js ^(NEW) 🔗

Create the renderer process JavaScript for UI logic:

• Access the exposed screenRecorder API from preload script
• Initialize UI on DOMContentLoaded:
  • Load available displays and populate dropdown
  • Set default recording options
  • Attach event listeners to all controls
• Implement startRecording function:
  • Get selected display ID
  • Get recording options from UI (resolution, fps, audio, encoding mode)
  • Get output directory
  • Call screenRecorder.startRecording with parameters
  • Update UI state (disable start button, enable stop/pause)
  • Start status update interval
• Implement stopRecording function:
  • Call screenRecorder.stopRecording
  • Update UI state
  • Clear status update interval
  • Show completion message with file path
• Implement pauseRecording function:
  • Call screenRecorder.pauseRecording
  • Update button text to "Resume"
• Implement resumeRecording function:
  • Call screenRecorder.resumeRecording
  • Update button text to "Pause"
• Set up status update interval:
  • Call screenRecorder.getRecordingStatus every 500ms
  • Update duration display
  • Update FPS counter
  • Update audio level meter
• Listen to recording events:
  • onRecordingProgress: Update frame counter and duration
  • onRecordingComplete: Show success message, reset UI
  • onRecordingError: Show error message, reset UI
• Implement output directory selection:
  • Use file input or IPC to open directory picker
  • Display selected path
• Add validation:
  • Ensure display is selected
  • Ensure output directory is set
  • Show warnings for invalid configurations
• Add keyboard shortcuts:
  • Ctrl+R to start recording
  • Ctrl+S to stop recording
  • Ctrl+P to pause/resume

📄 renderer/styles.css ^(NEW) 🔗

Create the CSS file for renderer UI styling:

• Define CSS variables for consistent theming (colors, spacing, fonts)
• Style body with modern font family and background
• Style header section with prominent title
• Style display selector dropdown with clear labels
• Style recording controls:
  • Large, prominent buttons with hover effects
  • Different colors for start (green), stop (red), pause (orange)
  • Disabled state styling
• Style settings section:
  • Organized layout with labels and inputs
  • Checkbox styling
  • Dropdown styling
• Style status section:
  • Status indicator with color coding (idle, recording, paused, encoding)
  • Monospace font for counters
  • Audio level meter with gradient bar
• Style progress section:
  • Progress bar with smooth animation
  • Percentage display
• Add responsive design for different window sizes
• Add transitions for smooth UI updates

📄 .gitignore ^(NEW) 🔗

Create .gitignore file to exclude:

• node_modules directory
• build directory (native addon builds)
• dist directory (packaged application)
• Temporary recording files (*.tmp)
• Native addon build artifacts (*.node, *.obj, *.o)
• FFmpeg temporary files
• OS-specific files (.DS_Store, Thumbs.db)
• IDE files (.vscode, .idea)
• Log files (*.log)
• Package lock files if using yarn

📄 README.md ^(MODIFY) 🔗

Update the README.md file with comprehensive project documentation:

• Replace the existing minimal content
• Add project title and description:
  • Explain this is a high-performance Windows screen recorder
  • Mention key features: 60+ FPS capture, cursor tracking, audio capture, H.264 encoding
• Add Features section:
  • Desktop Duplication API for GPU-accelerated capture
  • 120Hz cursor position tracking with click detection
  • System audio and microphone capture
  • Real-time and post-recording encoding modes
  • Multiple resolution support (720p to 4K)
  • Multi-monitor support
• Add Requirements section:
  • Windows 8 or later
  • DirectX 11.1 compatible GPU
  • Node.js 16+ and npm
  • Visual Studio Build Tools (for native addons)
  • Python 3.x (for node-gyp)
• Add Installation section:
  • Clone repository command
  • npm install command
  • npm run build command (to build native addons)
• Add Usage section:
  • npm start command to launch application
  • Brief UI usage instructions
• Add Development section:
  • Explain project structure
  • List main directories (electron, native, renderer)
  • Explain how to rebuild native addons
  • Mention debugging tips
• Add Building section:
  • npm run package command
  • Explain output location
• Add Technical Details section:
  • Explain Desktop Duplication API usage
  • Mention FFmpeg integration
  • Describe cursor tracking implementation
  • Explain audio capture approach
• Add Troubleshooting section:
  • Common issues and solutions
  • GPU compatibility notes
  • Audio device issues
• Add License section (if applicable)
• Keep the original motivation line about Focusee

Diagram

sequenceDiagram
    participant UI as Renderer Process
    participant Main as Main Process
    participant RC as RecordingController
    participant DC as DesktopCapture
    participant CT as CursorTracker
    participant AC as AudioCapture
    participant VE as VideoEncoder
    participant Native as Native Addons

    UI->>Main: startRecording(displayId, options)
    Main->>RC: startRecording()
    
    RC->>DC: new DesktopCapture(displayId, fps)
    RC->>CT: new CursorTracker(120Hz)
    RC->>AC: new AudioCapture(options)
    RC->>VE: new VideoEncoder(outputPath, options)
    
    RC->>AC: start()
    RC->>CT: start()
    CT->>Native: StartTracking()
    
    RC->>DC: start()
    DC->>Native: Initialize Desktop Duplication API
    Native-->>DC: IDXGIOutputDuplication
    
    RC->>VE: start()
    VE->>VE: Spawn FFmpeg process
    
    loop Every Frame (60+ FPS)
        DC->>Native: captureFrame()
        Native-->>DC: Frame buffer + timestamp
        DC->>VE: encodeFrame(buffer, timestamp)
        VE->>VE: Write to FFmpeg stdin
        DC->>UI: emit 'recording-progress'
    end
    
    loop Every 8ms (120Hz)
        CT->>Native: GetCursorPosition()
        Native-->>CT: x, y, timestamp, cursor type
        CT->>CT: Store in buffer
    end
    
    loop Audio Capture
        AC->>Native: WASAPI Capture
        Native-->>AC: Audio samples
        AC->>VE: encodeAudio(samples, timestamp)
    end
    
    UI->>Main: stopRecording()
    Main->>RC: stopRecording()
    
    RC->>DC: stop()
    RC->>CT: stop()
    CT->>CT: synchronizeWithFrames()
    CT->>CT: saveToFile(cursorData.json)
    RC->>AC: stop()
    RC->>VE: stop()
    VE->>VE: Close FFmpeg stdin & wait
    VE-->>RC: Encoding complete
    
    RC->>UI: emit 'recording-complete' (filePath)

Loading

Import In IDE

🤖 Prompt for AI Agents

I have created the following plan after thorough exploration and analysis of the codebase. Follow the below plan verbatim. Trust the files and references. Do not re-verify what's written in the plan. Explore only when absolutely necessary. First implement all the proposed file changes and then I'll review all the changes together at the end.

### Observations

The repository is currently empty except for a README. Phase 1 (basic project setup) appears incomplete, so this plan includes minimal foundational structure. The implementation prioritizes the Desktop Duplication API approach over libraries for maximum performance and control, uses native addons for Windows-specific features, and leverages ffmpeg-static for cross-platform FFmpeg bundling.


### Approach

This plan implements a high-performance Windows screen recorder using the Desktop Duplication API for 60+ FPS capture, native cursor tracking at 120Hz+, multi-channel audio capture (system + microphone), and FFmpeg-based H.264 encoding. The architecture uses Electron's main process for recording logic with IPC communication to the renderer, native C++ addons for Windows API integration, and a modular design separating capture, encoding, and session management concerns.


### Reasoning

Listed the repository structure and found it empty. Read the README confirming a new project. Searched for existing configuration files and found none. Researched Windows Desktop Duplication API integration options, FFmpeg bundling strategies, audio capture approaches, and native addon development patterns for Electron to inform the implementation strategy.


## Mermaid Diagram

sequenceDiagram
    participant UI as Renderer Process
    participant Main as Main Process
    participant RC as RecordingController
    participant DC as DesktopCapture
    participant CT as CursorTracker
    participant AC as AudioCapture
    participant VE as VideoEncoder
    participant Native as Native Addons

    UI->>Main: startRecording(displayId, options)
    Main->>RC: startRecording()
    
    RC->>DC: new DesktopCapture(displayId, fps)
    RC->>CT: new CursorTracker(120Hz)
    RC->>AC: new AudioCapture(options)
    RC->>VE: new VideoEncoder(outputPath, options)
    
    RC->>AC: start()
    RC->>CT: start()
    CT->>Native: StartTracking()
    
    RC->>DC: start()
    DC->>Native: Initialize Desktop Duplication API
    Native-->>DC: IDXGIOutputDuplication
    
    RC->>VE: start()
    VE->>VE: Spawn FFmpeg process
    
    loop Every Frame (60+ FPS)
        DC->>Native: captureFrame()
        Native-->>DC: Frame buffer + timestamp
        DC->>VE: encodeFrame(buffer, timestamp)
        VE->>VE: Write to FFmpeg stdin
        DC->>UI: emit 'recording-progress'
    end
    
    loop Every 8ms (120Hz)
        CT->>Native: GetCursorPosition()
        Native-->>CT: x, y, timestamp, cursor type
        CT->>CT: Store in buffer
    end
    
    loop Audio Capture
        AC->>Native: WASAPI Capture
        Native-->>AC: Audio samples
        AC->>VE: encodeAudio(samples, timestamp)
    end
    
    UI->>Main: stopRecording()
    Main->>RC: stopRecording()
    
    RC->>DC: stop()
    RC->>CT: stop()
    CT->>CT: synchronizeWithFrames()
    CT->>CT: saveToFile(cursorData.json)
    RC->>AC: stop()
    RC->>VE: stop()
    VE->>VE: Close FFmpeg stdin & wait
    VE-->>RC: Encoding complete
    
    RC->>UI: emit 'recording-complete' (filePath)

## Proposed File Changes

### package.json(NEW)

Create the main package.json file for the Electron application with the following configuration:

- Set name to "screen-recorder" and version to "0.1.0"
- Add main entry point as "electron/main.js"
- Configure scripts:
  - "start": Launch Electron in development mode
  - "build": Build native addons using node-gyp
  - "rebuild": Rebuild native addons for Electron
  - "package": Package the application using electron-builder
- Add dependencies:
  - "electron": Latest stable version for the desktop framework
  - "fluent-ffmpeg": For FFmpeg command interface
  - "ffmpeg-static": For bundled FFmpeg binaries
  - "ffprobe-static": For FFprobe binaries
  - "node-addon-api": For native C++ addon development
  - "bindings": For loading native modules
- Add devDependencies:
  - "electron-builder": For packaging the application
  - "node-gyp": For building native addons
- Configure electron-builder settings:
  - Set appId to "com.omniblocks.screenrecorder"
  - Configure asarUnpack to exclude ffmpeg-static and native addons from ASAR archive
  - Set target platforms to Windows (win32)
  - Configure file patterns to include electron directory and node_modules

### binding.gyp(NEW)

Create the node-gyp configuration file for building native C++ addons:

- Define target "desktop_duplication_addon" for the Desktop Duplication API wrapper
- Set sources to include "native/desktop_duplication/desktop_duplication.cc" and "native/desktop_duplication/frame_capturer.cc"
- Include node-addon-api headers
- Add Windows-specific configurations:
  - Link against d3d11.lib, dxgi.lib, and windowscodecs.lib
  - Define UNICODE and _UNICODE macros
  - Set C++ standard to C++17
- Define target "cursor_tracking_addon" for cursor tracking
- Set sources to include "native/cursor_tracking/cursor_tracking.cc"
- Link against user32.lib for GetCursorPos and mouse event APIs
- Configure conditions to ensure builds only on Windows platform
- Set exception handling and runtime library flags

### electron(NEW)

Create the main Electron directory to house all main process code, IPC handlers, and recording logic.

### electron/main.js(NEW)

Create the Electron main process entry point:

- Import required Electron modules (app, BrowserWindow, ipcMain, screen)
- Import the recording controller from `electron/recorder/recordingController.js`
- Configure FFmpeg paths using ffmpeg-static and ffprobe-static with ASAR unpacking support (replace 'app.asar' with 'app.asar.unpacked')
- Create main window function:
  - Set window dimensions (1200x800)
  - Configure webPreferences with nodeIntegration disabled and contextIsolation enabled
  - Set up preload script path
  - Load the renderer HTML file
- Set up IPC handlers:
  - "get-displays": Return list of available displays using screen.getAllDisplays()
  - "start-recording": Invoke recording controller start method with display ID and options
  - "stop-recording": Invoke recording controller stop method
  - "pause-recording": Invoke recording controller pause method
  - "resume-recording": Invoke recording controller resume method
  - "get-recording-status": Return current recording state
- Handle app lifecycle events (ready, window-all-closed, activate)
- Add error handling for uncaught exceptions

### electron/preload.js(NEW)

Create the preload script for secure IPC communication between renderer and main process:

- Import contextBridge and ipcRenderer from Electron
- Expose safe API to renderer process via contextBridge.exposeInMainWorld:
  - "screenRecorder" namespace with methods:
    - getDisplays(): Invoke "get-displays" IPC
    - startRecording(displayId, options): Invoke "start-recording" IPC
    - stopRecording(): Invoke "stop-recording" IPC
    - pauseRecording(): Invoke "pause-recording" IPC
    - resumeRecording(): Invoke "resume-recording" IPC
    - getRecordingStatus(): Invoke "get-recording-status" IPC
    - onRecordingProgress(callback): Listen to "recording-progress" events
    - onRecordingComplete(callback): Listen to "recording-complete" events
    - onRecordingError(callback): Listen to "recording-error" events
- Ensure all IPC channels are whitelisted and validated

### native(NEW)

Create the native directory to house all C++ native addon source code for Windows API integration.

### native/desktop_duplication(NEW)

Create directory for Desktop Duplication API native addon implementation.

### native/desktop_duplication/desktop_duplication.cc(NEW)

Create the main C++ source file for Desktop Duplication API addon:

- Include necessary headers: napi.h, d3d11.h, dxgi1_2.h, wincodec.h
- Implement initialization function:
  - Create D3D11 device and device context
  - Enumerate DXGI adapters and outputs
  - Support multi-GPU systems (NVIDIA, AMD, Intel)
  - Initialize IDXGIOutputDuplication interface for specified monitor
  - Handle errors for unsupported systems (pre-Windows 8, no DX11.1)
- Implement frame capture function:
  - Call AcquireNextFrame() on IDXGIOutputDuplication
  - Handle timeout scenarios (no new frame available)
  - Retrieve DXGI_OUTDUPL_FRAME_INFO for metadata
  - Get IDXGIResource from frame
  - Query for ID3D11Texture2D interface
  - Copy texture to staging texture for CPU access
  - Map staging texture to get pixel data
  - Convert BGRA to RGBA if needed
  - Return frame data as Node.js Buffer with timestamp
  - Release frame and unmap resources
- Implement cleanup function to release all COM interfaces
- Implement monitor enumeration function returning array of display info
- Export Node-API module with Init function
- Register functions: initialize, captureFrame, cleanup, getDisplays
- Add error handling for all DirectX operations with descriptive messages

### native/desktop_duplication/frame_capturer.cc(NEW)

Create helper C++ class for optimized frame capture:

- Define FrameCapturer class with private members:
  - ID3D11Device pointer
  - ID3D11DeviceContext pointer
  - IDXGIOutputDuplication pointer
  - ID3D11Texture2D staging texture pointer
  - Frame buffer pool for memory reuse
  - Frame timing tracker
- Implement constructor:
  - Accept monitor index parameter
  - Initialize DirectX resources
  - Create staging texture with CPU read access
  - Allocate frame buffer pool (3-5 buffers)
- Implement CaptureFrame method:
  - Acquire next frame with 16ms timeout (for 60 FPS)
  - Check frame timing to maintain target FPS
  - Copy frame to staging texture
  - Map texture and copy to reused buffer from pool
  - Unmap and release frame
  - Return buffer with metadata (timestamp, frame number, dimensions)
- Implement GetFrameRate method returning current capture rate
- Implement SetTargetFPS method to adjust timeout values
- Implement destructor to clean up all DirectX resources
- Add error recovery for GPU device lost scenarios
- Optimize for minimal CPU usage and memory allocations

### native/cursor_tracking(NEW)

Create directory for cursor tracking native addon implementation.

### native/cursor_tracking/cursor_tracking.cc(NEW)

Create the C++ source file for cursor tracking addon:

- Include headers: napi.h, windows.h, winuser.h
- Implement GetCursorPosition function:
  - Call Windows GetCursorPos API to get screen coordinates
  - Return JavaScript object with x, y coordinates and high-precision timestamp
- Implement GetCursorInfo function:
  - Call GetCursorInfo API to get cursor state
  - Determine cursor visibility (hidden/visible)
  - Get cursor handle and type (arrow, hand, text, wait, etc.)
  - Return object with position, visibility, and cursor type
- Implement mouse event tracking:
  - Set up low-level mouse hook using SetWindowsHookEx
  - Capture WM_LBUTTONDOWN, WM_LBUTTONUP for left clicks
  - Capture WM_RBUTTONDOWN, WM_RBUTTONUP for right clicks
  - Store events in thread-safe queue with timestamps
  - Implement GetMouseEvents function to retrieve queued events
- Implement StartTracking function:
  - Accept target frequency parameter (default 120Hz)
  - Create high-resolution timer thread
  - Poll cursor position at specified frequency
  - Store positions in circular buffer
  - Return tracking session ID
- Implement StopTracking function to halt tracking and cleanup
- Implement GetTrackingData function:
  - Return array of cursor positions with timestamps
  - Include mouse click events merged with position data
  - Clear retrieved data from buffer
- Export Node-API module with all functions
- Add thread safety for concurrent access
- Optimize for minimal overhead (< 1% CPU usage)

### electron/recorder(NEW)

Create directory for all recording-related modules including capture, encoding, and session management.

### electron/recorder/desktopCapture.js(NEW)

Create the desktop capture module that wraps the native Desktop Duplication addon:

- Import the native desktop_duplication addon using bindings package
- Import EventEmitter for event-driven architecture
- Define DesktopCapture class extending EventEmitter:
  - Constructor accepts monitor ID and target FPS (default 60)
  - Initialize native addon with specified monitor
  - Set up frame buffer queue
  - Track capture statistics (frames captured, dropped frames, actual FPS)
- Implement start method:
  - Validate monitor ID exists
  - Initialize native capturer
  - Start capture loop using setImmediate for non-blocking iteration
  - In each iteration:
    - Call native captureFrame function
    - Calculate frame timing and actual FPS
    - Emit 'frame' event with frame data and metadata
    - Handle frame drops if capture falls behind
    - Continue loop if still recording
  - Emit 'started' event
- Implement stop method:
  - Set recording flag to false
  - Wait for current frame to complete
  - Call native cleanup function
  - Emit 'stopped' event with final statistics
- Implement pause/resume methods for temporary suspension
- Implement getStatistics method returning capture metrics
- Add error handling:
  - Catch native addon errors
  - Emit 'error' events
  - Implement fallback for GPU device lost
- Add support for multi-monitor selection
- Optimize memory usage by reusing frame buffers

### electron/recorder/cursorTracking.js(NEW)

Create the cursor tracking module as specified in the GitHub issue:

- Import the native cursor_tracking addon using bindings package
- Import EventEmitter
- Define CursorTracker class extending EventEmitter:
  - Constructor accepts tracking frequency (default 120Hz)
  - Initialize tracking data storage array
  - Set up mouse event queue
- Implement start method:
  - Call native StartTracking with specified frequency
  - Store tracking session ID
  - Set up periodic data retrieval (every 100ms to avoid buffer overflow)
  - In retrieval callback:
    - Call native GetTrackingData to get cursor positions
    - Call native GetMouseEvents to get click events
    - Merge cursor positions with click events by timestamp
    - Store in synchronized data structure with format:
      - timestamp (high-precision)
      - x, y coordinates
      - cursorType (arrow, hand, text, etc.)
      - visibility (boolean)
      - clickEvent (null, 'left-down', 'left-up', 'right-down', 'right-up')
  - Emit 'started' event
- Implement stop method:
  - Call native StopTracking
  - Retrieve any remaining data
  - Emit 'stopped' event
- Implement getData method:
  - Return complete tracking data array
  - Optionally filter by time range
- Implement saveToFile method:
  - Accept file path parameter
  - Serialize tracking data to JSON format
  - Write to file asynchronously
  - Support both JSON and binary formats for efficiency
- Implement synchronizeWithFrames method:
  - Accept frame timestamps array
  - Align cursor data with video frame timestamps
  - Interpolate cursor positions between samples if needed
  - Return synchronized data structure
- Add getStatistics method returning:
  - Total tracking duration
  - Number of cursor position samples
  - Number of click events
  - Average sampling rate
- Handle errors from native addon gracefully

### electron/recorder/audioCapture.js(NEW)

Create the audio capture module for system and microphone audio:

- Import required modules: EventEmitter, child_process for native audio tools
- Consider using @thesusheer/node-miniaudio or implementing WASAPI wrapper
- Define AudioCapture class extending EventEmitter:
  - Constructor accepts configuration:
    - captureSystemAudio (boolean, default true)
    - captureMicrophone (boolean, default false)
    - sampleRate (default 48000 Hz)
    - channels (default 2 for stereo)
    - bitDepth (default 16)
  - Initialize audio buffers for system and microphone streams
- Implement start method:
  - If captureSystemAudio is true:
    - Initialize WASAPI loopback capture for system audio
    - Use ActivateAudioInterfaceAsync on Windows 10+
    - Set up audio format (PCM, sample rate, channels)
    - Start capture thread
  - If captureMicrophone is true:
    - Enumerate available microphone devices
    - Use default or user-selected microphone
    - Initialize WASAPI capture for microphone
    - Start separate capture thread
  - Set up audio mixing if both sources enabled:
    - Create mixer that combines both streams
    - Normalize audio levels
    - Synchronize timestamps
  - Emit 'started' event
- Implement audio buffer management:
  - Use circular buffers to prevent memory overflow
  - Target 2-3 seconds of buffered audio
  - Emit 'audio-data' events with audio chunks and timestamps
- Implement stop method:
  - Stop all capture threads
  - Flush remaining audio buffers
  - Release audio device resources
  - Emit 'stopped' event
- Implement pause/resume methods
- Implement getAudioDevices method:
  - Enumerate system audio devices
  - Return list with device IDs and names
- Implement setMicrophoneDevice method for device switching
- Implement getAudioLevel method:
  - Calculate current audio level (RMS or peak)
  - Return separate levels for system and microphone
  - Useful for UI visualization
- Add synchronization with video:
  - Maintain precise timestamps for all audio samples
  - Implement getSynchronizedAudio method accepting video timestamp range
- Handle audio device changes (device unplugged, etc.)
- Add error handling for audio device access failures

### electron/recorder/videoEncoder.js(NEW)

Create the video encoding pipeline module as specified in the GitHub issue:

- Import fluent-ffmpeg, path, fs, EventEmitter
- Import ffmpeg-static and ffprobe-static for binary paths
- Define VideoEncoder class extending EventEmitter:
  - Constructor accepts encoding configuration:
    - outputPath (file path for final video)
    - resolution (720p, 1080p, 1440p, 4K)
    - frameRate (default 60)
    - videoBitrate (calculated based on resolution)
    - codec (default 'libx264')
    - preset (ultrafast, fast, medium, slow for quality/speed tradeoff)
    - encodingMode ('realtime' or 'raw-capture')
  - Set FFmpeg binary paths using ffmpeg-static with ASAR unpacking
  - Initialize encoding statistics
- Implement start method:
  - Create FFmpeg command using fluent-ffmpeg
  - Configure input:
    - Set input format to rawvideo
    - Set pixel format to rgba or bgra
    - Set frame size based on resolution
    - Set frame rate
    - Use pipe:0 for stdin input
  - Configure video encoding:
    - Set codec to libx264
    - Set bitrate based on resolution (e.g., 5000k for 1080p, 10000k for 4K)
    - Set preset for encoding speed
    - Add -movflags +faststart for web playback
    - Set keyframe interval (GOP size)
  - Configure audio encoding:
    - Set audio codec to aac
    - Set audio bitrate (192k or 256k)
    - Set audio sample rate (48000 Hz)
  - Set output format to mp4
  - Set output path
  - If encodingMode is 'realtime':
    - Start FFmpeg process immediately
    - Pipe frames directly to stdin as they arrive
  - If encodingMode is 'raw-capture':
    - Store frames to temporary directory
    - Encode after recording completes
  - Listen to FFmpeg events:
    - 'progress': Parse and emit encoding progress
    - 'error': Handle encoding errors
    - 'end': Emit completion event
  - Emit 'started' event
- Implement encodeFrame method:
  - Accept frame buffer and timestamp
  - If realtime mode:
    - Write frame buffer to FFmpeg stdin
    - Handle backpressure if FFmpeg can't keep up
  - If raw-capture mode:
    - Save frame to temporary file with timestamp
  - Update frame counter and statistics
- Implement encodeAudio method:
  - Accept audio buffer and timestamp
  - Write to FFmpeg audio input
  - Ensure audio/video synchronization
- Implement stop method:
  - If realtime mode:
    - Close FFmpeg stdin
    - Wait for FFmpeg to finish encoding
  - If raw-capture mode:
    - Start FFmpeg process
    - Feed all saved frames in order
    - Wait for completion
  - Clean up temporary files
  - Emit 'stopped' event with final file path
- Implement pause/resume methods:
  - For realtime mode: buffer frames during pause
  - For raw-capture mode: simply stop saving frames
- Implement getProgress method:
  - Parse FFmpeg output for progress information
  - Calculate:
    - Frames encoded
    - Current encoding FPS
    - Time elapsed
    - Estimated time remaining
    - Output file size
  - Return progress object
- Implement quality preset configurations:
  - Map resolution strings to actual dimensions
  - Calculate appropriate bitrates
  - Set FFmpeg preset based on user choice
- Add error handling:
  - Handle FFmpeg process crashes
  - Handle disk space issues
  - Handle invalid frame data
  - Emit 'error' events with descriptive messages
- Optimize for performance:
  - Use hardware acceleration if available (h264_nvenc, h264_qsv, h264_amf)
  - Implement frame buffer pooling
  - Minimize memory copies

### electron/recorder/recordingController.js(NEW)

Create the main recording session management controller:

- Import all recorder modules:
  - DesktopCapture from `electron/recorder/desktopCapture.js`
  - CursorTracker from `electron/recorder/cursorTracking.js`
  - AudioCapture from `electron/recorder/audioCapture.js`
  - VideoEncoder from `electron/recorder/videoEncoder.js`
- Import EventEmitter, path, fs
- Define RecordingController class extending EventEmitter:
  - Constructor initializes:
    - currentSession object (null when not recording)
    - sessionMetadata object
    - recordingState ('idle', 'recording', 'paused', 'encoding')
  - Store references to all component instances
- Implement startRecording method:
  - Accept parameters:
    - displayId (monitor to record)
    - outputDirectory (where to save file)
    - options object (resolution, fps, audio settings, encoding mode)
  - Validate parameters:
    - Check display exists
    - Verify output directory is writable
    - Check available disk space (warn if < 1GB)
  - Generate unique filename using timestamp
  - Create session object:
    - sessionId (UUID)
    - startTime (timestamp)
    - displayId
    - outputPath
    - options
  - Initialize all components:
    - Create DesktopCapture instance with displayId and FPS
    - Create CursorTracker instance with 120Hz frequency
    - Create AudioCapture instance with audio options
    - Create VideoEncoder instance with output path and encoding options
  - Set up event handlers:
    - DesktopCapture 'frame' event:
      - Pass frame to VideoEncoder.encodeFrame
      - Update frame counter
      - Emit 'recording-progress' to renderer
    - AudioCapture 'audio-data' event:
      - Pass audio to VideoEncoder.encodeAudio
    - VideoEncoder 'progress' event:
      - Emit 'encoding-progress' to renderer
    - Handle errors from all components
  - Start all components in sequence:
    - Start AudioCapture first (to avoid missing audio)
    - Start CursorTracker
    - Start DesktopCapture
    - Start VideoEncoder
  - Set recordingState to 'recording'
  - Store session in currentSession
  - Emit 'recording-started' event
  - Return session object
- Implement stopRecording method:
  - Validate recording is active
  - Set recordingState to 'encoding'
  - Stop all components in reverse order:
    - Stop DesktopCapture first
    - Stop CursorTracker
    - Stop AudioCapture
    - Stop VideoEncoder (this may take time for final encoding)
  - Save cursor tracking data:
    - Get data from CursorTracker
    - Synchronize with frame timestamps
    - Save to JSON file alongside video
  - Calculate session statistics:
    - Total duration
    - Total frames captured
    - Average FPS
    - Final file size
  - Update session metadata
  - Set recordingState to 'idle'
  - Emit 'recording-complete' event with session data
  - Clear currentSession
  - Return final session object with file paths
- Implement pauseRecording method:
  - Validate recording is active
  - Pause all components:
    - Pause DesktopCapture
    - Pause CursorTracker
    - Pause AudioCapture
    - Pause VideoEncoder
  - Set recordingState to 'paused'
  - Store pause timestamp
  - Emit 'recording-paused' event
- Implement resumeRecording method:
  - Validate recording is paused
  - Resume all components in same order as start
  - Calculate pause duration
  - Adjust timestamps to account for pause
  - Set recordingState to 'recording'
  - Emit 'recording-resumed' event
- Implement cancelRecording method:
  - Stop all components
  - Delete partial output files
  - Clean up temporary files
  - Set recordingState to 'idle'
  - Emit 'recording-cancelled' event
- Implement getRecordingStatus method:
  - Return object with:
    - recordingState
    - currentSession (if active)
    - duration (if recording)
    - framesCaptured
    - currentFPS
    - audioLevel
    - outputFileSize (if available)
- Implement getSessionMetadata method returning current session info
- Add auto-save on crash:
  - Listen to process 'exit' and 'SIGINT' events
  - If recording active, attempt to stop gracefully
  - Save partial recording with '_incomplete' suffix
- Add disk space monitoring:
  - Check available space every 10 seconds during recording
  - If space < 100MB, emit warning
  - If space < 50MB, auto-stop recording
- Implement error recovery:
  - If DesktopCapture fails, attempt restart
  - If VideoEncoder fails, switch to raw-capture mode
  - Log all errors for debugging
- Export singleton instance of RecordingController

### renderer(NEW)

Create directory for renderer process files (UI).

### renderer/index.html(NEW)

Create the main HTML file for the renderer process:

- Set up basic HTML5 structure with DOCTYPE and meta tags
- Set title to "Screen Recorder"
- Link to CSS file at `renderer/styles.css`
- Create UI structure:
  - Header section with app title
  - Display selection dropdown (populated via IPC)
  - Recording controls section:
    - Start recording button
    - Stop recording button (disabled initially)
    - Pause/Resume button (disabled initially)
  - Settings section:
    - Resolution selector (720p, 1080p, 1440p, 4K)
    - FPS selector (30, 60)
    - Audio options checkboxes (system audio, microphone)
    - Encoding mode selector (realtime, raw-capture)
    - Output directory selector
  - Status section:
    - Recording status indicator
    - Duration display
    - FPS counter
    - Audio level meter
  - Progress section (shown during encoding):
    - Progress bar
    - Encoding speed display
    - Time remaining estimate
- Include script tag for `renderer/app.js`
- Add minimal inline styles for basic layout

### renderer/app.js(NEW)

Create the renderer process JavaScript for UI logic:

- Access the exposed screenRecorder API from preload script
- Initialize UI on DOMContentLoaded:
  - Load available displays and populate dropdown
  - Set default recording options
  - Attach event listeners to all controls
- Implement startRecording function:
  - Get selected display ID
  - Get recording options from UI (resolution, fps, audio, encoding mode)
  - Get output directory
  - Call screenRecorder.startRecording with parameters
  - Update UI state (disable start button, enable stop/pause)
  - Start status update interval
- Implement stopRecording function:
  - Call screenRecorder.stopRecording
  - Update UI state
  - Clear status update interval
  - Show completion message with file path
- Implement pauseRecording function:
  - Call screenRecorder.pauseRecording
  - Update button text to "Resume"
- Implement resumeRecording function:
  - Call screenRecorder.resumeRecording
  - Update button text to "Pause"
- Set up status update interval:
  - Call screenRecorder.getRecordingStatus every 500ms
  - Update duration display
  - Update FPS counter
  - Update audio level meter
- Listen to recording events:
  - onRecordingProgress: Update frame counter and duration
  - onRecordingComplete: Show success message, reset UI
  - onRecordingError: Show error message, reset UI
- Implement output directory selection:
  - Use file input or IPC to open directory picker
  - Display selected path
- Add validation:
  - Ensure display is selected
  - Ensure output directory is set
  - Show warnings for invalid configurations
- Add keyboard shortcuts:
  - Ctrl+R to start recording
  - Ctrl+S to stop recording
  - Ctrl+P to pause/resume

### renderer/styles.css(NEW)

Create the CSS file for renderer UI styling:

- Define CSS variables for consistent theming (colors, spacing, fonts)
- Style body with modern font family and background
- Style header section with prominent title
- Style display selector dropdown with clear labels
- Style recording controls:
  - Large, prominent buttons with hover effects
  - Different colors for start (green), stop (red), pause (orange)
  - Disabled state styling
- Style settings section:
  - Organized layout with labels and inputs
  - Checkbox styling
  - Dropdown styling
- Style status section:
  - Status indicator with color coding (idle, recording, paused, encoding)
  - Monospace font for counters
  - Audio level meter with gradient bar
- Style progress section:
  - Progress bar with smooth animation
  - Percentage display
- Add responsive design for different window sizes
- Add transitions for smooth UI updates

### .gitignore(NEW)

Create .gitignore file to exclude:

- node_modules directory
- build directory (native addon builds)
- dist directory (packaged application)
- Temporary recording files (*.tmp)
- Native addon build artifacts (*.node, *.obj, *.o)
- FFmpeg temporary files
- OS-specific files (.DS_Store, Thumbs.db)
- IDE files (.vscode, .idea)
- Log files (*.log)
- Package lock files if using yarn

### README.md(MODIFY)

Update the README.md file with comprehensive project documentation:

- Replace the existing minimal content
- Add project title and description:
  - Explain this is a high-performance Windows screen recorder
  - Mention key features: 60+ FPS capture, cursor tracking, audio capture, H.264 encoding
- Add Features section:
  - Desktop Duplication API for GPU-accelerated capture
  - 120Hz cursor position tracking with click detection
  - System audio and microphone capture
  - Real-time and post-recording encoding modes
  - Multiple resolution support (720p to 4K)
  - Multi-monitor support
- Add Requirements section:
  - Windows 8 or later
  - DirectX 11.1 compatible GPU
  - Node.js 16+ and npm
  - Visual Studio Build Tools (for native addons)
  - Python 3.x (for node-gyp)
- Add Installation section:
  - Clone repository command
  - npm install command
  - npm run build command (to build native addons)
- Add Usage section:
  - npm start command to launch application
  - Brief UI usage instructions
- Add Development section:
  - Explain project structure
  - List main directories (electron, native, renderer)
  - Explain how to rebuild native addons
  - Mention debugging tips
- Add Building section:
  - npm run package command
  - Explain output location
- Add Technical Details section:
  - Explain Desktop Duplication API usage
  - Mention FFmpeg integration
  - Describe cursor tracking implementation
  - Explain audio capture approach
- Add Troubleshooting section:
  - Common issues and solutions
  - GPU compatibility notes
  - Audio device issues
- Add License section (if applicable)
- Keep the original motivation line about Focusee

---

Developer Humor

🎬 From pixels to MP4, a recording tale,\n> Desktop Duplication won't fail!\n> Cursor tracked at 120Hz speed,\n> FFmpeg encoding, yes indeed!\n> 60 FPS captured with care,\n> Your screen recorder's now quite rare! 🚀

---

Execution Information

Branch: main
Commit: 9b7326a

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.