English | 中文 | 日本語 | 한국어 | Deutsch | Français | Español

A cross-platform CLI screen recorder powered by ffmpeg — record your screen with a single command.

• 🎥 Screen + Audio Recording — Captures desktop video with system audio and microphone mixed together
• 📁 Flexible Output Path — Set a persistent default output directory or specify one per recording
• 🔍 ffmpeg Auto-Detection — Checks for ffmpeg at install time and at runtime; guides you if it's missing
• 🖥️ Cross-Platform — Windows (gdigrab), macOS (avfoundation), Linux (x11grab)
• ⚡ Simple Commands — Start, stop, configure with one command
• 🎛️ Configurable — Custom frame rate, audio toggle, output directory

• Node.js >= 18.0.0
• npm >= 6.0.0
• ffmpeg (must be installed separately and available in your PATH)

Windows audio note: To record system audio, install VB-Audio Virtual Cable first.

Option 1: Install via npm (recommended)

npm install -g screenrecorder-cli

Option 2: Clone from GitHub (for developers)

git clone https://github.com/gdjdkid/ScreenRecorder-cli.git
cd ScreenRecorder-cli
npm install
npm install -g .

Verify installation:

screenrec -v

Start recording (uses saved or default output directory):

screenrec start

Start recording to a specific folder:

screenrec start -o D:\MyRecordings

Record without audio:

screenrec start --no-audio

Set a persistent default output directory:

screenrec set-output D:\MyRecordings
# or interactive mode:
screenrec set-output

Show current configuration:

screenrec show-config

List audio devices (Windows only):

screenrec devices

Stop recording: Press Ctrl+C — the file saves automatically.

Usage: screenrec [command] [options]

Commands:
  start          Start screen recording (default)
  set-output     Set default output directory
  show-config    Show current configuration
  devices        List available audio input devices

Options for start:
  -o, --output <dir>    Output directory (overrides saved config)
  -r, --framerate <fps> Frame rate (default: 30)
  --no-audio            Disable audio recording
  --mic <name>          Microphone device name (Windows)
  --system <name>       System audio device name (Windows)
  -v, --version         Print version number
  -h, --help            Show help

-o flag (per-recording)
  ↓ not set
Saved config (screenrec set-output)
  ↓ not set
Default: ~/Videos/ScreenRecords

Config is saved to ~/.config/screenrec/config.json and persists across sessions.

{
  "outputDir": "D:\\MyRecordings"
}

Q: I get "ffmpeg not found" after installing? A: ffmpeg must be installed separately. See the Requirements section above.

Q: No system audio on Windows? A: Install VB-Audio Virtual Cable and use virtual-audio-capturer as the system audio device.

Q: How do I stop recording? A: Press Ctrl+C. The output file is saved automatically.

Q: Where is the output file? A: Run screenrec show-config to see your current output directory.

This project is open source under the MIT License.

PRs and Issues are welcome!

1. Fork this repository
2. Create your branch: git checkout -b feat/your-feature
3. Commit your changes: git commit -m "feat: describe your change"
4. Push the branch: git push origin feat/your-feature
5. Open a Pull Request

Commit message conventions:

• feat: — new feature
• fix: — bug fix
• docs: — documentation update
• chore: — maintenance

• v1.0.0 — Initial release