video-add-b-roll

Video Add B-Roll

Add a small number of evidence-backed visual cutaways to an understood canonical Project Protocol sequence. Read broll-rules.md before planning or acquiring any media. Use example-broll-plan.json as the plan-shape reference.

Non-Negotiable Contract

Follow every editorial, provenance, still, review, recovery, and delivery rule in broll-rules.md. Operationally:

• Use the provided scripts for acquisition, validation, normalization, receipt application, and verification. Never use a raw download path or substitute another stock source.
• Never fabricate human authority. Agent review requires explicit delegation and a truthful Agent receipt.
• Missing, weak, or downloader-rejected media becomes skipped; never use random or still fallback media.

Requirements And Inputs

Require Python, ffmpeg, ffprobe, and Pillow. For Pexels, first use PEXELS_API_KEY from the environment, then look for it in skills/video-add-b-roll/.env. If both are missing or blank, stop and ask the user to add PEXELS_API_KEY=<key> to that file, then retry after they confirm. Ask them to provide the key through the local .env file, never through chat. Never place or print it in a command argument, plan, URL, log, review artifact, or response.

/video-understand is a prerequisite. Run it first so B-roll use the validated word-level transcript and canonical timeline. Before starting, verify that it is installed. If it is not, warn the user that this prerequisite is missing and stop before processing media.

Run from the repository root and resolve the separate project root:

$RepoRoot = (Resolve-Path '.').Path
$ProjectRoot = (Resolve-Path 'path/to/video-project').Path
$BrollEnv = Join-Path $RepoRoot 'skills/video-add-b-roll/.env'
if ([string]::IsNullOrWhiteSpace($env:PEXELS_API_KEY) -and (Test-Path -LiteralPath $BrollEnv)) {
  $PexelsKeyLine = Get-Content -LiteralPath $BrollEnv | Where-Object { $_ -match '^\s*PEXELS_API_KEY\s*=' } | Select-Object -Last 1
  if ($PexelsKeyLine) { $env:PEXELS_API_KEY = ($PexelsKeyLine -split '=', 2)[1].Trim().Trim('"').Trim("'") }
}
$BrollScripts = Join-Path $RepoRoot 'skills/video-add-b-roll/scripts'
$ProjectLib = Join-Path $RepoRoot 'skills/video-understand/scripts'
$ReviewVideo = & python -c "import sys; from pathlib import Path; sys.path.insert(0,sys.argv[2]); import projectlib; root=Path(sys.argv[1]); project=projectlib.load_json(root/'work/project.json'); assert project.get('render',{}).get('status') == 'verified', 'current upstream delivery is not verified'; path=projectlib.resolve_project_path(root,project['render']['output']); assert path.is_file(), 'current upstream delivery is missing'; print(path)" $ProjectRoot $ProjectLib
if ($LASTEXITCODE -ne 0) { throw 'Complete the active upstream delivery before B-roll review.' }
$ReviewVideo = (Resolve-Path -LiteralPath $ReviewVideo).Path