recap

Cross-platform headless screen and audio capture library and CLI.

Features

• Cross-platform: Windows, macOS, and Linux
• Record an entire monitor or a single window
• Record system audio (loopback capture)
• Per-application audio capture (Windows only via WASAPI process loopback)
• Video-only, audio-only, or audio+video modes
• Crop support with configurable size and anchor position
• CLI tool (recap) and importable Python library
• Uses FFmpeg for encoding/muxing only

Platform Support

macOS Notes

• Screen Recording permission must be granted in System Settings → Privacy & Security → Screen Recording.
• System audio capture requires a virtual audio loopback device such as BlackHole. Install BlackHole, then set it as your system output (or use a Multi-Output Device to hear audio simultaneously). Recap auto-detects BlackHole/Soundflower when available.
• Per-application audio capture is not supported; system-wide audio is captured instead.

Linux Notes

• Video capture requires X11 (XWayland is acceptable). Native Wayland capture is not yet supported. If running under Wayland, ensure DISPLAY is set for XWayland.
• Discovery commands support selecting an explicit X11 display with --display (for example recap windows --display :99).
• Audio capture uses PulseAudio/PipeWire loopback (default.monitor). Ensure pactl is available (pulseaudio-utils or pipewire-pulse).
• Per-application audio capture is not directly supported; system-wide audio is captured instead.

Requirements

• Python 3.10–3.13
• FFmpeg on PATH or specified via --ffmpeg

Platform-specific requirements

• Windows: Windows 10 version 2004+ for per-app audio capture
• macOS: macOS 11+ recommended; Screen Recording permission required
• Linux: X11 or XWayland; PulseAudio or PipeWire; xrandr for multi-monitor detection

Installation

From PyPI (prebuilt wheels)

pip install recap-capture

From source (editable)

git clone https://github.com/Lexian-droid/recap.git
cd recap
pip install -e .

Architecture

The project uses a Python package with a platform abstraction layer:

recap/              Python package (CLI, config, orchestration)
  __init__.py       Public API and version
  cli.py            CLI entry point
  config.py         RecordingConfig dataclass
  recorder.py       Orchestrates capture threads + FFmpeg
  video.py          Platform-dispatching video capture
  audio.py          Platform-dispatching audio capture
  discovery.py      Platform-dispatching monitor/window/device enumeration
  ffmpeg.py         FFmpeg discovery and process wiring
  exceptions.py     Exception hierarchy
  platforms/        Platform abstraction layer
    __init__.py     Platform detection utilities
    macos/          macOS backends (CoreGraphics + FFmpeg avfoundation)
    linux/          Linux backends (X11 + FFmpeg pulse/alsa)

Platform dispatch

The video.py, audio.py, and discovery.py modules contain the Windows implementation at the top level. On macOS or Linux, platform-specific implementations are imported from recap/platforms/ and replace the module-level names. This means the public API (from recap import VideoCapture) works identically regardless of platform.

Window-specific recording

When a window is targeted via --window-title or --window-handle:

• Video is captured using the platform's native window capture API
• Audio on Windows uses WASAPI process loopback to isolate audio from that process. On macOS/Linux, system-wide audio is captured instead (with a warning).

Releasing

GitHub Actions will publish the package to PyPI when you push a tag that starts with v (e.g. v0.5.0). Wheels are built for Python 3.10–3.13.

For local validation and manual publishing, use the built-in helper command:

# install editable package (one-time per env)
pip install -e .

# smoke-test local install
recap-release test-local

# build wheel + sdist
recap-release build

# validate metadata before upload
recap-release check-dist

# upload manually
recap-release publish-testpypi
# or
recap-release publish-pypi

Notes:

• publish-* runs twine check automatically unless --skip-check is used.
• test-local runs recap version, recap doctor, recap monitors, and recap devices.

CLI Usage

# Check environment
recap doctor

# List available capture targets
recap monitors
recap windows
recap devices

# List targets on a virtual X11 display
recap monitors --display :99
recap windows --display :99

# Record primary monitor with audio
recap record --output recording.mp4

# Record a specific window (video + window-specific audio on Windows)
recap record --window-title "Notepad" --output notepad.mp4

# Record from a window on a virtual X11 display
recap record --window-title "Videos - WeAnimate" --display :99 --output weanimate.mp4

# Record video only
recap record --video-only --output silent.mp4

# Record a 1280x720 crop from the top-left of the selected source
recap record --crop-size 1280x720 --crop-position top-left --output cropped.mp4

# Record a centered 1280x720 crop from a specific window
recap record --window-title "Notepad" --crop-size 1280x720 --crop-position middle --output notepad-cropped.mp4

# Record audio only
recap record --audio-only --output audio.wav

# Record for 30 seconds
recap record --duration 30 --output clip.mp4

Crop positions

--crop-position supports:

• top-left, top-middle, top-right
• middle-left, middle, middle-right
• bottom-left, bottom-middle, bottom-right

Center aliases are also accepted (center, top-center, middle-center, etc.).

Library Usage

from recap import Recorder, RecordingConfig

config = RecordingConfig(output="recording.mp4")
recorder = Recorder(config)
recorder.start()
# ... do work ...
recorder.stop()
recorder.wait()

Library usage with virtual displays (Linux)

from recap import Recorder, RecordingConfig, list_windows

# Discover windows on a virtual X11 display.
windows = list_windows(display=":99")

config = RecordingConfig(
  output="weanimate.mp4",
  window_title="Videos - WeAnimate",
  display=":99",
  duration=10,
)
recorder = Recorder(config)
recorder.start()
recorder.wait()

Window-specific recording

from recap import Recorder, RecordingConfig

config = RecordingConfig(
    output="discord.mp4",
    window_title="Discord",
)
recorder = Recorder(config)
recorder.start()
# captures the Discord window's video (and per-app audio on Windows)
recorder.stop()
recorder.wait()

License

MIT