ffmpeg-screencast

---
name: ffmpeg-screencast
description: "Start and stop fullscreen screen recordings using ffmpeg x11grab with clean lifecycle management. Use when the user says 'record screen', 'screencast', 'ffmpeg record', 'capture fullscreen', 'start recording', 'record my session', or when another skill needs to capture screen activity during a workflow. Handles PID tracking, resolution detection, graceful stop, and post-recording validation."
---

# FFmpeg Screencast — Clean Screen Recording Lifecycle

Record the full screen using ffmpeg with proper start/stop/validate lifecycle. No orphaned processes, no corrupt files.

## When to Use

- User asks to record the screen or capture a session
- Another skill needs background screen recording during a workflow
- Capturing a demo, test run, or debugging session

## Step 1: Detect Display and Resolution

```bash
echo "DISPLAY=$DISPLAY"
xdpyinfo -display ${DISPLAY:-:1} 2>/dev/null | grep dimensions
```

If no display is available, tell the user and abort.

## Step 2: Start Recording

Use this exact pattern — it handles PID tracking:

```bash
RECORD_FILE="/path/to/output.mp4"
RECORD_PID_FILE="/tmp/ffmpeg-screencast-$$.pid"

ffmpeg -f x11grab -framerate 15 -video_size ${WIDTH}x${HEIGHT} -i ${DISPLAY:-:1} \
  -c:v libx264 -preset ultrafast -crf 23 -pix_fmt yuv420p \
  "$RECORD_FILE" &
FFMPEG_PID=$!
echo $FFMPEG_PID > "$RECORD_PID_FILE"
echo "Recording started: PID=$FFMPEG_PID → $RECORD_FILE"
```

Run the ffmpeg command in the background using `run_in_background: true` on the Bash tool. Save the PID file path for later.

Key settings:
- `-framerate 15` — smooth enough, small files
- `-preset ultrafast` — low CPU during recording
- `-crf 23` — good quality/size balance
- `-pix_fmt yuv420p` — universal compatibility

## Step 3: Do Your Work

The recording captures everything on screen. Proceed with browser automation, terminal work, whatever needs recording.

## Step 4: Stop Recording

Kill ffmpeg gracefully with SIGINT (not SIGKILL) so it finalizes the MP4 container:

```bash
# Find and kill ffmpeg by the output filename
pkill -INT -f "ffmpeg.*output_filename"
sleep 2
```

If `pkill` doesn't work (process already gone), that's fine — check if the file exists.

## Step 5: Validate Output

Always verify the recording is valid:

```bash
ffprobe -v error -show_entries format=duration,size -of default=noprint_wrappers=1 "$RECORD_FILE"
ffprobe -v error -show_entries stream=width,height,codec_name -of default=noprint_wrappers=1 "$RECORD_FILE"
```

Report: duration, file size, resolution, codec. If `ffprobe` fails, the file is corrupt — warn the user.

## Common Issues

- **"Address already in use" or stale ffmpeg**: Run `pgrep -af ffmpeg` to find orphans, kill them
- **File exists but 0 bytes**: ffmpeg was killed with SIGKILL instead of SIGINT — container wasn't finalized
- **Display :0 vs :1**: Check `echo $DISPLAY` — Wayland users may need XWayland