Skip to content

puntorigen/avatar-skills / broll-finder

broll-finder

Verified

Find real public YouTube footage about a topic or person (e.g. Anthony Bourdain) and turn the relevant moments into clean 9:16, silent B-roll clips for an avatar reel. The found-footage counterpart of broll-generator — instead of synthesizing B-roll with AI, it searches YouTube, fetches timecoded transcripts so the agent can pick the relevant windows WITHOUT downloading whole videos, downloads only those segments, and normalizes them into a broll/-compatible manifest (with source + license metadata) that avatar-reel-composer can drop in via a broll scene. Use when the user wants real/archival B-roll, complementary footage about a subject or person, "find clips of X on YouTube to use in the reel", or footage inserts to lay under an avatar voice-over.

FileKindSize
SKILL.mdskill md10.0 KB
examples.mdmarkdown3.3 KB
scripts/_common.pyscript23.6 KB
scripts/cut_segment.pyscript7.8 KB
scripts/find_broll.pyscript10.4 KB
scripts/requirements.txtmanifest345 B
scripts/search.pyscript3.7 KB
scripts/transcripts.pyscript6.1 KB

examples.md

View on GitHub
# broll-finder — examples

## 1. Find Anthony Bourdain street-food footage for a `lolo` reel

```bash
# Stage 1+2: search + transcripts, then stops at the checkpoint
python3 .cursor/skills/broll-finder/scripts/find_broll.py \
    --query "anthony bourdain street food vietnam" \
    --avatar-dir lolo --max-candidates 8 --lang en --creative-commons --frames
```

Console (truncated):

```
=== [1/3] search.py ===
=== [2/3] transcripts.py ===
========================================================================
CHECKPOINT — agent action required:
  1. Skim found-broll/anthony-bourdain-street-food-vietnam/candidates.md
     and .../transcripts/*.md
  2. Copy selection.template.json -> selection.json and edit it
  3. Re-run the same command to cut the clips.
========================================================================
```

Now the **agent** reads the transcripts (each line is a `[mm:ss]` block), e.g.:

```
[02:10] this is the best pho I have had in my entire life, right here on a
        plastic stool on the sidewalk in Hanoi
[02:18] the broth, the herbs, everything about this is perfect
```

…and writes `found-broll/anthony-bourdain-street-food-vietnam/selection.json`:

```json
{
  "segments": [
    { "url": "https://youtu.be/VIDEOID", "start": 130, "end": 136,
      "description": "Bourdain comiendo pho en un puesto callejero de Hanoi", "fit": "crop" },
    { "url": "https://youtu.be/VIDEOID", "start": 152, "end": 158,
      "description": "primer plano del caldo de pho humeante con hierbas", "fit": "blur" }
  ]
}
```

Re-run the same command → stage 3 downloads only those windows and writes:

```
lolo/broll/found/001_bourdain-comiendo-pho-en-un-puesto-callejero.mp4
lolo/broll/found/002_primer-plano-del-caldo-de-pho-humeante.mp4
lolo/broll/found/manifest.json     # source_url, channel, license, segment, rights_note
lolo/broll/found/001_*.jpg         # review frames (--frames)
```

## 2. One clip directly (no orchestrator)

```bash
python3 .cursor/skills/broll-finder/scripts/cut_segment.py \
    --url "https://youtu.be/VIDEOID" --start 41.5 --end 47 \
    --description "mercado nocturno, vapor de los puestos, multitud" \
    --avatar-dir lolo --fit blur --frame
```

## 3. Use a found clip in a storyboard

```json
{
  "avatar_dir": "lolo",
  "slug": "viajar-cambia",
  "scenes": [
    { "id": "s1", "type": "talking_head", "text": "déjame contarte algo sobre viajar.", "angle": "eye_level" },
    { "id": "s2", "type": "broll", "broll_source": "existing",
      "broll_clip": "lolo/broll/found/001_bourdain-comiendo-pho-en-un-puesto-callejero.mp4",
      "text": "a veces una comida en la calle te enseña más que un libro." }
  ]
}
```

```bash
python3 ~/.cursor/skills/avatar-reel-composer/scripts/compose_reel.py viajar-cambia.storyboard.json --language es
```

## 4. Standalone search / transcripts (debugging)

```bash
python3 .cursor/skills/broll-finder/scripts/search.py \
    --query "ocean waves drone" --creative-commons --sort views -o ./work

python3 .cursor/skills/broll-finder/scripts/transcripts.py \
    --candidates ./work/candidates.json --max 5 --lang en -o ./work
```

## Notes

- Add `found-broll/` and `**/broll/found/` to `.gitignore` (research + third-party media).
- For videos with no captions, add `--whisper` (downloads audio + faster-whisper; slower).
- Bot-gated videos: add `--cookies-from-browser firefox`.
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall