---
name: screen_recording
description: Record clean screen captures with OBS or ffmpeg — chooses the capture backend per OS, configures bitrate vs resolution for the use case, records separate audio tracks, and post-processes for delivery. Triggers on requests to record a screen, capture a demo/tutorial, record a screencast, set up OBS recording settings, or choose recording bitrates.
---

# Screen Recording

## Purpose
Produce clean, high-quality screen recordings. Picks the right capture tool for the platform (OBS for GUI work, ffmpeg/wf-recorder for scripted or headless-agent capture), records a resilient master file, and derives delivery copies at the right bitrate. Always aims for a *clean take*: no notifications, no cursor fumbling, no mushy text.

## Workflow

1. **Pick the lane.** Interactive human demo with multiple scenes/overlays → OBS. Scripted, unattended, or agent-driven capture → `bin/screenrecord` (ffmpeg backend). Wayland compositor without X11 → `wf-recorder` (see `references/wayland-capture.md`). Default to the highest quality the machine sustains; never silently drop to a blurry encode to "save space."

2. **Configure the master recording.** Record at native resolution, 30 or 60 fps, with a fast encoder setting during capture — quality comes from the *re-encode*, not the capture pass. Details: `references/obs-recording.md`, `references/ffmpeg-capture.md`.

3. **Separate audio.** System audio and voice go on separate tracks (OBS: Advanced Audio Properties → tracks 1/2; ffmpeg: two audio inputs mapped separately). Extract later with `-map`. Never bake voice and system audio into one track when both exist.

4. **Shoot the clean take.** Follow `references/clean-takes.md`: silence notifications, hide clutter, rehearse the click path, record 2s handles before/after, verify the file plays before declaring done.

5. **Verify and deliver.** Check the master (`ffprobe` duration/streams, spot-play the start). Remux or re-encode to the delivery target using the bitrate table in `references/bitrate-resolution.md`. Deliver the master path + the delivery file path.

## Output Contract
- One master recording (MKV or MOV with lossless/near-lossless settings) at native resolution with its audio tracks intact.
- One delivery file (MP4, yuv420p, AAC) sized to the target platform's recommended bitrate.
- A short note: backend used, resolution/fps/bitrate, which audio track holds what, and anything wrong with the take (dropped frames, glitches) the user should know about.

## Operating Rules
1. **Always record to MKV, never MP4, for the master.** An interrupted MP4 is unrecoverable; an MKV keeps everything up to the crash. Remux to MP4 for delivery.
2. **Never downscale for text-heavy screens.** Canvas = output = native resolution. Downscaling blurs code and terminal text; it is the most common screen-recording mistake.
3. **Capture with `ultrafast` + CRF 18 (near-lossless), re-encode later.** Real-time capture cannot afford slow presets; quality comes from the second pass.
4. **Verify claims against sources.** Bitrates, codec ranges, and backend options come from `references/` (researched from official docs) — do not invent numbers.
5. **Test the pipeline before the real take.** Run `bin/screenrecord --print-cmd` and a 5-second test encode; if the test fails, fix it before pressing record on the real thing.
6. **Headless machines have no display.** ffmpeg `x11grab` needs a real X server; without one, record the application's own framebuffer (headless browser `--enable-features`, virtual display) or document that live capture is impossible here.