docs: add screen recording pipeline guide and integration tests

[DaKev]

What

Adds a Screen Recording Pipeline section to the README documenting how to capture the screen with FFmpeg and hand the result to CutAgent for post-production. Includes an integration test module that validates the full pipeline against a synthetic recording.

Why

CutAgent is often used by AI agents that want to record and auto-edit screen sessions. Until now there was no guidance on how to wire the capture step to CutAgent's editing API. This closes the documentation gap and gives agents a tested reference workflow.

How

• README.md — new ## Screen Recording Pipeline section inserted between the EDL Format and Architecture sections. Covers:

  • Platform-specific FFmpeg screen capture commands (macOS avfoundation, Linux x11grab, Windows gdigrab)
  • CutAgent CLI walkthrough (probe → silence → trim → normalize)
  • Python API pipeline example using detect_silence + execute_edl to auto-detect and remove dead air
  • EDL JSON template for the common record → trim → normalize → text overlay workflow

• tests/test_screen_recording_pipeline.py — new integration test module with a module-scoped screen_recording fixture (synthetic 1280×720 video with 2s intro silence → 6s content → 2s outro silence). Tests:

  1. probe returns expected 1280×720 metadata
  2. detect_silence finds the intro and outro segments
  3. trim to the content window produces a shorter clip
  4. Full EDL (trim + normalize) succeeds and produces a shorter final file
  5. normalize_audio standalone produces a valid output

Checklist

• Tests added/updated for new functionality
• All tests pass (pytest — 236 passed, 28 skipped)
• JSON output contract maintained (no non-JSON stdout)
• No new runtime dependencies introduced

Made with Cursor