@getexcited/chompers

@getexcited/chompers

High-performance native Node.js addon for Windows screen recording and window enumeration, built with Rust and napi-rs.

Features

🎥 Screen Recording

• High-performance recording using Windows Desktop Duplication API
• No yellow border during capture (unlike WGC API)
• Hardware-accelerated encoding (H.264, HEVC)
• Audio capture from desktop and microphone
• Replay buffer functionality (similar to ShadowPlay)
• Process-specific recording target specific applications
• Configurable quality settings and output formats

🪟 Window Management

• Window enumeration with detailed metadata
• Multi-monitor support with monitor information
• Process information including executable paths and arguments
• Focus detection and window state tracking
• Game detection capabilities

Installation

npm install @getexcited/chompers
# or
yarn add @getexcited/chompers

Quick Start

Screen Recording

import {
  Recorder,
  RecorderConfig,
  AudioSource,
  VideoEncoderType,
} from "@getexcited/chompers";

// Basic recording configuration
const config: RecorderConfig = {
  fpsNumerator: 30,
  fpsDenominator: 1,
  outputWidth: 1920,
  outputHeight: 1080,
  captureAudio: true,
  captureMicrophone: false,
  audioSource: AudioSource.Desktop,
  videoEncoderType: VideoEncoderType.H264,
  captureCursor: true,
  outputPath: "recording.mp4",
  debugMode: false,
  enableReplayBuffer: false,
};

// Create recorder and target a specific process
const recorder = new Recorder(config).withProcessName("notepad");

// Start recording
recorder.startRecording();

// Record for 10 seconds
setTimeout(() => {
  recorder.stopRecording();
  console.log("Recording completed!");
}, 10000);

Replay Buffer

import {
  Recorder,
  RecorderConfigBuilder,
  AudioSource,
} from "@getexcited/chompers";

// Create recorder with replay buffer
const config = new RecorderConfigBuilder()
  .fps(30, 1)
  .outputDimensions(1920, 1080)
  .captureAudio(true)
  .audioSource(AudioSource.Desktop)
  .enableReplayBuffer(true)
  .replayBufferSeconds(30) // Keep last 30 seconds
  .outputPath("main_recording.mp4")
  .build();

const recorder = new Recorder(config).withProcessName("game.exe");

// Start recording with buffer
recorder.startRecording();

// Save replay when something interesting happens
recorder.saveReplay("highlight.mp4");

// Continue recording or stop
recorder.stopRecording();

Window Enumeration

import { getAllWindows } from "@getexcited/chompers";

// Get all windows with detailed information
const windows = getAllWindows();

windows.forEach((window) => {
  console.log(`Title: ${window.title}`);
  console.log(`Process: ${window.executable}`);
  console.log(`PID: ${window.pid}`);
  console.log(`Focused: ${window.focused}`);
  console.log(
    `Monitor: ${window.monitorDimensions.width}x${window.monitorDimensions.height}`
  );
  console.log("---");
});

API Reference

Recording Classes

Recorder

Main recording class for capturing screen content.

class Recorder {
  constructor(config: RecorderConfig);
  withProcessName(processName: string): Recorder;
  startRecording(): void;
  stopRecording(): void;
  saveReplay(path: string): void;
}

RecorderConfigBuilder

Fluent builder for creating recorder configurations.

class RecorderConfigBuilder {
  fps(numerator: number, denominator: number): this;
  inputDimensions(width: number, height: number): this;
  outputDimensions(width: number, height: number): this;
  captureAudio(capture: boolean): this;
  captureMicrophone(capture: boolean): this;
  audioSource(source: AudioSource): this;
  microphoneVolume(volume: number): this;
  systemVolume(volume: number): this;
  microphoneDevice(deviceName?: string): this;
  videoEncoder(encoderType: VideoEncoderType): this;
  videoEncoderName(name: string): this;
  captureCursor(capture: boolean): this;
  outputPath(path: string): this;
  debugMode(debug: boolean): this;
  enableReplayBuffer(enable: boolean): this;
  replayBufferSeconds(seconds: number): this;
  build(): RecorderConfig;
}

Configuration Types

RecorderConfig

interface RecorderConfig {
  fpsNumerator: number; // Frame rate numerator
  fpsDenominator: number; // Frame rate denominator
  inputWidth?: number; // Input resolution width (auto-detected if not set)
  inputHeight?: number; // Input resolution height (auto-detected if not set)
  outputWidth: number; // Output resolution width
  outputHeight: number; // Output resolution height
  captureAudio: boolean; // Enable system audio capture
  captureMicrophone: boolean; // Enable microphone capture
  audioSource: AudioSource; // Desktop or ActiveWindow
  microphoneVolume?: number; // Microphone volume (0.0-1.0)
  systemVolume?: number; // System audio volume (0.0-1.0)
  microphoneDevice?: string; // Specific microphone device name
  videoEncoderType?: VideoEncoderType; // H264 or HEVC
  videoEncoderName?: string; // Specific encoder name
  captureCursor: boolean; // Include cursor in recording
  outputPath: string; // Output file path
  debugMode: boolean; // Enable debug logging
  enableReplayBuffer: boolean; // Enable replay buffer feature
  replayBufferSeconds?: number; // Replay buffer duration in seconds
}

WindowInfo

interface WindowInfo {
  className: string; // Window class name
  executable: string; // Executable name
  title: string; // Window title
  pid: number; // Process ID
  productName?: string; // Product name from executable
  hwnd: number; // Window handle
  fullExe: string; // Full executable path
  monitorDimensions: MonitorDimensions; // Monitor information
  intersectsMultiple: boolean; // Spans multiple monitors
  focused: boolean; // Currently focused window
  arguments: Array<string>; // Process arguments
}

Enums

AudioSource

enum AudioSource {
  Desktop = "Desktop", // Capture all system audio
  ActiveWindow = "ActiveWindow", // Capture audio from target window only
}

VideoEncoderType

enum VideoEncoderType {
  H264 = "H264", // H.264/AVC encoding
  HEVC = "HEVC", // H.265/HEVC encoding
}

Utility Functions

Audio Device Management

// Enumerate available audio input devices
function enumerateAudioInputDevices(): AudioInputDevice[];

// Get preferred video encoder by type
function getPreferredVideoEncoderByType(
  encoderType: VideoEncoderType
): VideoEncoder | null;

// Enumerate available video encoders
function enumerateVideoEncoders(): VideoEncoder[];

Window Management

// Get all windows with detailed information
function getAllWindows(): WindowInfo[];

Examples

The examples/ directory contains comprehensive TypeScript examples:

• basic_recording.ts - Basic screen recording setup
• replay_buffer.ts - Replay buffer functionality
• select_audio_device.ts - Audio device enumeration and selection
• select_video_encoder.ts - Video encoder enumeration and selection

Run examples with:

# Show available examples
yarn examples

# Run specific examples
yarn example:basic
yarn example:replay
yarn example:audio
yarn example:encoder

System Requirements

• Operating System: Windows 10/11 (x64)
• Node.js: 16.0.0 or higher
• Hardware: GPU with hardware encoding support (recommended)
• Drivers: Up-to-date GPU drivers for optimal performance

Performance Considerations

Optimal Settings

• Resolution: 1920x1080 or lower for best performance
• Frame Rate: 30 FPS provides good quality/performance balance
• Encoder: H.264 for compatibility, HEVC for better compression
• Audio: Disable microphone if not needed

Hardware Acceleration

The library automatically uses hardware-accelerated encoding when available:

• NVIDIA: NVENC (H.264/HEVC)
• AMD: VCE (H.264/HEVC)
• Intel: Quick Sync Video (H.264/HEVC)

Troubleshooting

Common Issues

• Recording fails to start

  • Ensure target process exists
  • Check output path permissions
  • Verify sufficient disk space

• No audio captured

  • Check Windows audio permissions
  • Verify target application produces audio
  • Try different audio sources

• Poor performance

  • Lower output resolution
  • Reduce frame rate
  • Update GPU drivers
  • Close unnecessary applications

• No video encoders found

  • Update GPU drivers
  • Install Windows Media Feature Pack
  • Try different encoder types

Debug Mode

Enable debug logging for troubleshooting:

const config: RecorderConfig = {
  // ... other options
  debugMode: true,
};

Building from Source

# Clone the repository
git clone https://github.com/GetExcitedApp/chompers.git
cd chompers

# Install dependencies
yarn install

# Build the native addon
yarn build

# Run tests
yarn test

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to the main repository.

License

This project is licensed under the GPL-3.0-only License. See the LICENSE file for details.

Acknowledgments

• Built with napi-rs for Node.js native addon development
• Uses windows-record for core recording functionality
• Powered by Windows Desktop Duplication API for efficient screen capture

Note: This library is Windows-only and requires Windows 10 or later. For cross-platform solutions, consider other recording libraries.