Metadata-Version: 2.4
Name: recap-capture
Version: 0.6.1
Summary: Cross-platform headless screen and audio capture library and CLI
License: MIT
Keywords: screen-capture,audio-capture,cross-platform,windows,macos,linux,ffmpeg
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Capture/Recording
Classifier: Topic :: Multimedia :: Video :: Capture
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: comtypes>=1.4; sys_platform == "win32"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"

# 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

| Feature | Windows | macOS | Linux |
|---|---|---|---|
| Monitor capture | ✓ GDI BitBlt | ✓ CoreGraphics | ✓ X11 XGetImage |
| Window capture | ✓ PrintWindow | ✓ CGWindowListCreateImage | ✓ X11 XGetImage |
| System audio | ✓ WASAPI loopback | ⚠ Requires BlackHole/Soundflower | ✓ PulseAudio monitor |
| Per-app audio | ✓ WASAPI process loopback | ✗ Not supported | ✗ Not supported |
| HW encoding | NVENC / QSV / AMF | VideoToolbox / NVENC | NVENC / VAAPI / QSV |

### 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](https://github.com/ExistentialAudio/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.
- 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)

```bash
pip install recap-capture
```

### From source (editable)

```bash
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.

## CLI Usage

```bash
# Check environment
recap doctor

# List available capture targets
recap monitors
recap windows
recap devices

# 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 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

```python
from recap import Recorder, RecordingConfig

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

### Window-specific recording

```python
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
