---
name: screen-capture
description: Record the macOS screen to MP4 with one command. Full screen, custom region, or any connected display. Optional system audio + microphone, click/keystroke highlights, hold-for-N-seconds mode, or run-until-Ctrl-C. Pure ffmpeg + AVFoundation, no GUI app, no driver install. Outputs ready-to-share MP4 — drop straight into Telegram, vid-rip, clip-trim, or whisper-srt. Use when the user asks to "record my screen", "screen capture", "make a screencast", "record a tutorial", "capture this app", or wants a video of something happening on their Mac.
---


# screen-capture

macOS screen → MP4. Pure ffmpeg AVFoundation device.

## Quick recording (10 seconds)

```bash
python3 ~/.claude/skills/screen-capture/scripts/capture.py --duration 10
# → screen_<timestamp>.mp4 in cwd
```

## Run until Ctrl-C

```bash
python3 ~/.claude/skills/screen-capture/scripts/capture.py
# Ctrl-C cleanly stops + finalizes the MP4
```

## Specific region

```bash
python3 ~/.claude/skills/screen-capture/scripts/capture.py \
  --region 100,200,1280,720 --duration 30
# x,y,width,height — top-left origin
```

## With microphone audio

```bash
python3 ~/.claude/skills/screen-capture/scripts/capture.py --audio mic
```

## With system audio (requires BlackHole / SoundflowerBed)

```bash
python3 ~/.claude/skills/screen-capture/scripts/capture.py --audio system
# install BlackHole first: brew install blackhole-2ch
```

## List available capture devices

```bash
python3 ~/.claude/skills/screen-capture/scripts/capture.py --list
# shows display index + audio device index from ffmpeg
```

## Pick a different display

```bash
python3 ~/.claude/skills/screen-capture/scripts/capture.py --display 2
# default 1 (main display)
```

## Custom framerate / quality

```bash
python3 ~/.claude/skills/screen-capture/scripts/capture.py --fps 60 --crf 18
# crf lower = higher quality (default 22). 18 is visually-lossless, 28 is small file
```

## Custom output path

```bash
python3 ~/.claude/skills/screen-capture/scripts/capture.py --output ~/Desktop/demo.mp4
```

## Auto-trim leading/trailing seconds

```bash
python3 ~/.claude/skills/screen-capture/scripts/capture.py --duration 30 --trim 1.5
# trim 1.5s from start AND end (skips your hand reaching for ⌘C)
```

## Flags

- `--duration` — seconds to record (omit for run-until-Ctrl-C)
- `--region` — `x,y,w,h` (default: full screen)
- `--display` — display index (default 1)
- `--audio` — `none` (default), `mic`, `system`
- `--audio-device` — explicit AVFoundation audio device index (overrides --audio)
- `--output` — output path (default `screen_<ISO timestamp>.mp4`)
- `--fps` — capture framerate (default 30)
- `--crf` — H.264 quality (default 22)
- `--trim` — seconds to trim from BOTH ends after capture (default 0)
- `--list` — print available AVFoundation devices and exit

## How it works

ffmpeg's `avfoundation` input device captures both screen and audio on macOS. We use `-i "<display>:<audio>"` to combine them and `libx264` with `pix_fmt yuv420p` for compatibility everywhere.

## Permission

First run on macOS prompts for **Screen Recording** permission in System Settings → Privacy & Security. Approve it and re-run.

## Pairs well with

- `clip-trim` — tighten the recording further
- `whisper-srt` — auto-caption your tutorial
- `face-blur` — anonymize anything sensitive on screen
- `telegram-sender` — send the recording straight to TG