screen_recording v1.0.0

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."

1. 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.

1. 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.

1. 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.

1. 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.