Skip to content
Back to search

b-roll-finder

Source accurate, on-brand b-roll for talking-head video — podcast & tutorial intros. Reads your transcript, routes each beat to the right footage, places it on the word.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/louisedesadeleer--b-roll-finder/badge.svg)](/listings/louisedesadeleer--b-roll-finder)

HTML

<a href="/listings/louisedesadeleer--b-roll-finder"><img src="/api/listings/louisedesadeleer--b-roll-finder/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

It's an **agent skill** — a methodology file your AI coding agent (e.g. [Claude Code](https://claude.com/claude-code)) reads and follows. There's no package to `npm install`; you register the skill and install the CLI tools it drives.

**1. Clone the repo**

git clone https://github.com/louisedesadeleer/b-roll-finder.git

**2. Register it with your agent.** For Claude Code, add a pointer in your `CLAUDE.md` (or drop `SKILL.md` in your skills directory):

#### /find-broll
Read: /path/to/b-roll-finder/SKILL.md
Source b-roll for a video edit — classify each moment, scope the search, return vetted candidates, place on the word.

**3. Install the tooling it drives** (macOS / Homebrew shown):

brew install yt-dlp ffmpeg imagemagick           # search/download, compositing, contact sheets
uv tool install mlx-whisper                       # GPU word-level transcription (Apple Silicon)
#   …or: pip install -U openai-whisper            # CPU fallback
npm create video@latest                           # Remotion, for concept motion-graphics (optional)

A Chrome/Chromium install is also used for headless screenshots of public pages. No API keys required.

**4. (Optional) make the taste yours.** The skill ships with a working taste profile — [TASTE.md](TASTE.md) — so it sources well from the first run. When you're ready, fork it: import your YouTube subscriptions, prune, and reveal your own fingerprint from your published videos (the file walks you through it).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 278 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: find-broll
  3. description: Source b-roll for a video edit — classify each moment, scope the search, return vetted candidates, place on the word. Use when the user says "find b-roll", "/find-broll", "source clips for this edit", or wants footage/memes/screenshots to lay over a talking-head video.
  4. ---
  5. # B-Roll Finder — skill methodology
  6. > A reusable methodology for sourcing and placing b-roll on talking-head video.
  7. > Genericized from a working agent skill. Adapt paths and brand tokens to your own setup.
  8. ## ⛔ USER OVERRIDES ARE LAW — and they persist
  9. When the user states a preference or ban mid-run ("no memes", "no text cards", "nothing political"), it applies IMMEDIATELY and for the rest of the session, AND gets written into the profile's Guardrails right then — not at the end. A banned category is never sourced again, never proposed again, never "just one candidate to check". Violating a stated ban is the worst failure this skill can make: it tells the user the agent doesn't listen.
  10. ## ⛔ STEP 0 — ONBOARDING GATE (run this check before ANYTHING else, every session)
  11. Open the profile (TASTE.md or the user's fork). **The ONLY thing that skips onboarding is a literal `Confirmed-by: <name> (<date>)` line at the top of the profile.** No line → ask the four onboarding questions (below) out loud, write the answers into the profile, add the line. This is NOT optional and NOT inferable:
  12. - Do **NOT** infer the answers from CLAUDE.md, memory, prior conversations, or this profile's prose — even if you are confident you know them. Asking IS the feature.
  13. - The shipped TASTE.md is an EXAMPLE, **even if the current user is its original author**. Author ≠ confirmed.
  14. - A CLAUDE.md pointer that says "load my taste profile" does not count as confirmation either — check for the line.
  15. - "redo my profile" re-triggers onboarding at any time.
  16. ## The one rule that governs everything
  17. **The agent NEVER picks the final b-roll. The user does.** The right clip is often a taste call. This skill's job is to **narrow the funnel** — classify each moment, scope the search to trusted/authoritative sources, score candidates, and hand back a tight contact sheet. The user makes the final pick.
  18. ## The taste profile — load it before sourcing anything
  19. Curation is half the skill. Every run starts by loading a **taste profile**: the b-roll fingerprint (which types, how fast to cut), the trusted-source list tagged by topic, and the guardrails. This repo ships with a working default — **[TASTE.md](TASTE.md)**, revealed from real published videos — so the skill has good taste out of the box. Use it as-is until the user builds their own (TASTE.md's "Make it yours" section covers the import-then-prune mechanism: pull their YouTube subscriptions via `yt-dlp --cookies-from-browser`, prune together, then reveal their fingerprint from their own published videos).
  20. ## Onboarding preferences (ask once, store in the profile)
  21. **When onboarding fires:** the shipped [TASTE.md](TASTE.md) is an EXAMPLE profile (the author's), not the user's. On first run, check the profile for a `Confirmed-by:` line naming the current user. Absent → run onboarding: ask the questions below, write the answers into the user's profile (their fork of TASTE.md), and add `Confirmed-by: <user> (<date>)` at the top. Present → skip onboarding and just load it. The user can re-trigger anytime with "redo my profile".
  22. Ask these on first run and write the answers into the taste profile (TASTE.md ships with one set of answers; confirm they fit):
  23. 1. **Audio** — does the user talk over b-roll (strip ALL audio: `ffmpeg -an`) or want the clip's sound?
  24. 2. **Stills motion** — static images get a **very subtle Ken Burns zoom-in by default** (~1.5%/sec, centered, capped ~2%/sec); offer opt-out to fully static. **Method matters more than the setting** — see "Stills motion" below.
  25. 3. **Source attribution** — credit each b-roll's source in small text bottom-right? Options: `off` · `white` · `black` · `auto` (contrast-pick per clip). The credit is the source's canonical name + platform ("Vinexposium / YouTube", "Decanter") — short, never a URL. If the footage already carries its own badge bottom-right, move the credit bottom-left for that clip. Note: an on-screen credit is etiquette, not a license — official/authoritative sources remain the real copyright posture.
  26. 4. **Concept motion graphics (Remotion)** — generate on-brand motion graphics for concept/stat/chart beats? If yes, ask for the path to an EXISTING Remotion project (+ brand tokens) and write it into the profile. Rendering a comp in an existing project is part of the lean path; **scaffolding a new project is a one-time setup step that needs explicit permission** (never mid-run). No project + no permission → concept beats use real authoritative footage or get flagged, never silently skipped.
  27. 5. **AI-generated b-roll** — off by default; opt-in only for beats with no real footage, via a quality model the user names. Never silently substitute cheap AI stock.
  28. ## 🔓 Standing authorization — invoking the skill IS the permission
  29. Do NOT ask conversational permission for access or searches while sourcing — running /find-broll already authorizes the skill to act on the user's behalf. Never ask "want me to search/look up/access X?" for:
  30. - Web searches, news/headline lookups, oEmbed/embed endpoints
  31. - `yt-dlp` metadata searches and downloads of public videos/channels
  32. - Headless-browser captures of public pages (incl. clicking through cookie/consent walls)
  33. - The user's logged-in browser or browser cookies **for sourcing/reading** (profiles, posts, walled pages)
  34. - Reading local files, transcripts, prior project folders, the user's asset library
  35. Just do it and show the result. The user's taste checkpoints stay: the **plan approval** before sourcing and the **final pick** on taste-route beats. The ONLY things that still warrant a question: publishing/posting anything outward, paid actions, deleting user files, and installing heavy dependencies. Ask-permission friction everywhere else is a bug, not politeness.
  36. ## ⚡ LEAN PATH IS THE DEFAULT — the funnel is for taste calls, not everything
  37. The skill earned trust through restraint; heavyweight process makes output WORSE, not better (tested 2026-06-11: a full-funnel run took ~10× longer and shipped worse composition than the lean run). Defaults:
  38. - **Plan approval IS the pick.** When the user approves the beat plan ("go for it"), source **ONE best candidate per beat** for objective routes (Entity/Receipts/Product) and place it. NO multi-candidate sourcing, NO contact sheets. (Contact sheets exist only when the user EXPLICITLY asks for options on a beat — and meme/cultural beats are never auto-sourced at all; see the routing table.)
  39. - **Research depth is bounded at plan time.** Verify referents enough to source accurately; do NOT exhaust every sourcing route before the plan. The escalation ladder fires only AFTER the user has agreed a beat and the easy routes failed — never speculatively.
  40. - **Per-beat time box:** if a single beat's sourcing exceeds ~5 minutes, place the best-available candidate or drop the beat and flag it. One stubborn artifact must not stall the edit.
  41. - **One verify pass + targeted fixes** beats endless polishing. Render → grid → fix the failures → re-verify only the fixed beats.
  42. - **NO RETRIES — first failure switches, second failure drops.** A method that fails once is NOT retried (not with tweaked flags, not "one more time") — switch to a different method immediately. If the second method also fails, DROP the beat, flag it in the plan, move on. A beat is never worth a third attempt; the edit ships without it. This applies to everything: captures, downloads, renders, browser actions. (Louise: "stop doing things that keep failing, just skip to save time.")
  43. - **Never auto-install heavy dependencies mid-run** (conda, aligners, etc.) — use the fallback, note it, offer the install after delivery.
  44. ### Source by SOURCE, not by beat (the big sourcing speed-up)
  45. After the plan is approved, **cluster beats by where their asset lives, then fetch each source ONCE**:
  46. - One full-page capture of the subject's website often covers 4–6 beats (history, team photo, map, packshots) — crop per beat from the same capture.
  47. - One official channel/film often covers several beats (an aerial, a close-up, a process shot) — download once, cut multiple windows.
  48. - Run all downloads as ONE batched background job (metadata-only search first, download only the chosen items); run captures as a second batch in parallel. Never fetch serially beat-by-beat.
  49. - Cache raw downloads next to the project (`assets/raw/`) so re-renders and v2s never re-fetch.
  50. ## Accuracy over volume
  51. Fewer, perfectly-accurate beats beat lots of mediocre ones. The habit to kill is keyword-matching to hit a quota.
  52. - **Every beat passes a per-citation interpretation** — write *"what is this line actually about?"* first, then source THAT. If you can't source something that accurately illustrates the real point, **drop the beat — don't pad.** No b-roll is better than wrong b-roll.
  53. - **Default cadence = front-loaded:** dense, punchy b-roll in the intro/hook, then sparse and precise through the body.
  54. - **But "skip" is the LAST resort, not the default.** Before proposing skip for a beat, walk the full palette out loud — receipt? headline? face? product UI? concept graphic? — and only skip when every lane genuinely fails. A rhetorical line with no proper noun is exactly when a *sentiment receipt* or a *concept graphic* shines.
  55. ## Understand the TOPIC first, then source the MEANING — not the keywords
  56. 1. Read the **whole transcript** and understand the thesis BEFORE sourcing anything. Context decides what illustrates each line.
  57. 2. **B-roll illustrates the POINT, not the words.** The proper noun in a sentence is often NOT the referent:
  58. - *"X from Company"* → the person and their work, not the company logo.
  59. - *"like Company did"* → the *thing* Company did.
  60. - *"what Person said"* → the said-thing (their quote/post/essay), not their face.
  61. 3. **Literal vs evocative:** concrete nouns (a product, a named person, an event) → show the actual thing. Actions & abstractions → show something that *conveys* it; don't reenact literally.
  62. 4. **Mandatory reference sweep — every beat:** *is there a REAL ARTIFACT behind this line?* A quote, a stat, "people are saying", a named company event, "I saw/read" — almost always means a tweet, headline, review, or post exists. That artifact is a default candidate; sourcing it is the skill's job, not an extra the user must request.
  63. ## Phrase-type → what to source (the judgment table)
  64. | When the narration is… | Source this |
  65. |---|---|
  66. | "people are saying" / discourse | tweets, headlines, posts, search-result screenshots |
  67. | a number / stat ("$24/mo", "750 sign-ups") | the figure ON SCREEN — pricing page, dashboard, chart, stat card |
  68. | growth / "went viral" | a graph going UP, or the viral post itself with its metrics |
  69. | decline / "tanking" | a graph going DOWN, error screens, the failing thing |
  70. | "research shows" / authority | the study/paper headline or the expert on camera |
  71. | a direct quote | the authentic post/blog screenshot (beats a synthetic quote-card), or them saying it |
  72. | an era / "back in the day" | archival/vintage footage of that period |
  73. | a place | establishing shots of that place |
  74. | comparison / "X vs Y" | sequential full-bleed singles — never an agent-built split-screen |
  75. | "how it works" / step-by-step | screen recording or motion graphics of the steps |
  76. | a story with actions ("every morning he'd…") | the PLACES & ACTIONS, evocatively — never a literal reenactment |
  77. | a metaphor ("like a rocket") | the metaphor object ONLY if it lands — metaphors default to SKIP |
  78. | an emotion / reaction beat | propose the moment + register; the user supplies the meme |
  79. | the creator's own content ("my video") | self-source their actual clip/post — not a search |
  80. ## Genre → coverage defaults (what type, how much)
  81. Genre predicts b-roll TYPE and density better than topic does (style + cadence answers from intake override these):
  82. - **Competitor / drama** → receipts dominant, heavy (~40–60% coverage)
  83. - **Opinion / explainer** → text/concept cards + receipt bursts (~20–30%)
  84. - **Storytelling / listicle** → people, archival, products (~40–60%)
  85. - **Podcast / webinar / interview** → light punctuation (~5–10%); b-roll marks references & claims, the talking head carries the rest
  86. ## Routing — three+ kinds of b-roll go to three+ sources
  87. Classify EVERY moment before searching:
  88. | Route | Trigger | Source |
  89. |---|---|---|
  90. | **Receipts** | Time-sensitive — drama, news, complaints, a current claim/stat | Tweets / article headlines / reviews, recency-sorted, captured as clean screenshots |
  91. | **Entity** | A **person**, a **physical product**, or a **historical moment** | The official / authoritative channel — the *canonical* clip, not a random upload |
  92. | **Concept** | An abstract idea you'd have to *draw* (a process, a mental model, a stat) | Custom motion-graphics (e.g. Remotion) in your brand style — the DEFAULT when the profile has a Remotion project path — or real footage from the authoritative source |
  93. **⛔ Cards never replace real footage of a literal thing.** If the beat names a concrete entity (grape varieties, a product, a place) and real footage exists, a generated text card is a FAIL — even if the user's fingerprint shows they like cards. Cards are for ideas with NO literal footage. (2026-06-11: a "three grapes" beat got a navy text card while the official film had the actual clusters — wrong.)
  94. | **Cultural / Meme** | A creator clip or joke where *taste* decides | **NEVER searched or fetched by the agent.** Propose the MOMENT + register ("punchline at 2:31, deadpan") in the plan; the user supplies the meme from their library — or strikes the beat. Agent-found memes have failed every time they've been tried. |
  95. **Litmus (in order):** *Happening now?* → Receipts. *A person / product / event?* → Entity (official source). *An abstract idea?* → Concept (motion-graphics). *A reaction beat?* → Meme (user's library).
  96. YouTube's sweet spot is the Entity route (people, products, historical moments). Don't force it onto abstract ideas — those are Concept jobs.
  97. ## Person clips — source the MOMENT, not the NAME
  98. A clip merely *containing* the person is NOT relevant b-roll (the #1 person-clip failure):
  99. 1. Write the **mention-context** first: what is the line saying ABOUT the person — the trait, the action, the claim, the event?
  100. 2. **Query = person + mention-context, never the bare name.** "Steve Jobs iPhone keynote 2007", not "Steve Jobs". Bare-name searches return generic press-junket clips.
  101. 3. **Verify before presenting:** for each candidate, fill in *"in this clip, X is <doing/saying what, where, when>"* from the title/date/auto-subs. Can't fill it in → not a candidate.
  102. 4. No context match found → say so; offer the canonical clip explicitly flagged "generic", or switch palette to their work/quote/headline (often better anyway).
  103. 5. **"The show/podcast" ≠ "this episode"** — a reference to a show sources the show's persistent branding, not one episode's guest art.
  104. ## The palette — MIX it, never default to website screenshots
  105. - **Faces (video)** — for a named person, a live clip of them talking (never a frozen headshot). Partial-frame / split-screen subjects → blurred-fill, never hard cover-crop. For a podcast/panel edit, the guests are ON CAMERA in the source recording — crop their tile as live video instead of hunting externally. **A headshot of someone the audience won't recognize is DEAD b-roll** — for niche people, show their WORK (their post, product, talk) instead of their face; famous faces should appear in context/action, not as static portraits. **⛔ And NEVER cut to a speaker's own tile as b-roll inside the same video they're speaking in** — the audience is already looking at them; it reads as a glitch. Tile-cropping is for using their face in OTHER videos.
  106. - **Product / UI** — the actual app UI or a real screen-recording (prefer own-recording > official channel > nothing; reject random third-party tutorials). **Demos must be the MOST RECENT available** — product UIs change fast; check upload dates, present them next to candidates.
  107. - **Receipts** — tweets, headlines, reviews, search results. For a named company, prefer a **news headline about a real event** (IPO, funding, milestone) over the homepage.
  108. - **Reference screenshots** — the real post/essay/page cited (an authentic screenshot beats a synthetic quote-card). **The subject's own website, captured full-page and cropped per viewport, is a goldmine** — history pages, team photos, maps, product pages.
  109. - **Concept motion-graphics** — for ideas, charts, stats. Build on-brand; never synthetic-looking stock.
  110. - **Real / evocative footage** — stock that conveys a story/action/mood. Eyeball every frame for watermarks, burned-in captions, and AI-slop.
  111. - **Memes / reactions** — from the user's curated library only; the agent proposes the moment, never the meme. If the profile or the user says no memes: the category does not exist.
  112. If a plan is >60% website screenshots, it's wrong.
  113. ## Cadence guardrails — restraint reads as taste
  114. - **Beats run ~2–4s.** Anything under ~1.2s is unreadable (no sub-second shots except inside ONE deliberate burst montage).
  115. - **Max ONE burst montage per intro** (3–4 quick stills on a list-beat). Two+ bursts = chaos.
  116. - **Max ONE long hold (>5s) per intro**, and only on a genuine explainer beat. An 8-second static map is dead air.
  117. - When in doubt: fewer, real, obvious. The strongest edits use one clearly-right asset per beat, not the most assets.
  118. ## Motion-first — video beats a static page
  119. When BOTH a moving and a static version of a source exist, take the moving one: the product's own demo video over its homepage; a real screen-recording of scrolling over a static capture; a live excerpt over a headshot. Stills stay right where READING is the point (a tweet, a headline, a review). Rubric tie-breaker: equal relevance → motion wins.
  120. ## Stills motion — sub-pixel subtle zoom only; ffmpeg `zoompan` is banned
  121. Hard-won distinction — **the ban is on the METHOD, not the effect**:
  122. - **ffmpeg `zoompan` / crop-pans / scroll-pans are BANNED, at any speed, with any supersampling.** They sample on integer pixel steps, so even a ~1%/sec zoom stutters. Tested exhaustively (4× lanczos supersample → zoompan → downscale): still shaky. Don't burn time re-attempting.
  123. - **Sub-pixel rendering is the legitimate path** and produces a smooth subtle zoom:
  124. - **PIL recipe (proven):** per-frame `img.resize((W,H), Image.LANCZOS, box=<float coords>)` — float box coordinates = sub-pixel sampling — piped as rawvideo into x264. ~30 lines of Python.
  125. - **Remotion** (CSS transform scale) is equally valid when a project is scaffolded.
  126. - Defaults: **zoom-IN only, centered, ~1.5%/sec, cap ~2%/sec, stills only** — no pans, no zoom-outs, never synthetic motion on top of real video. Per-profile opt-out → fully static.
  127. ## Eval rubric — score every candidate before showing it
  128. Score 1–5 and drop anything below the bar:
  129. 1. **Recency fit** — is the beat time-sensitive or evergreen? Time-sensitive + old clip = FAIL.
  130. 2. **Source authority** — primary/official/reputable vs random creator.
  131. 3. **Relevance** — depicts the exact named thing, not a loose association. Person clips: relevance = context-match.
  132. 4. **Recognizability / impact** — reads instantly, screenshots clean.
  133. 5. **Format fit** — silent-able, ~2–6s, full-bleed-able, ≥720p.
  134. Check **time-sensitivity first** — a dated tweet from this month beats a years-old YouTube clip for a current story.
  135. ## Search syntax — scoped beats open, always
  136. - **Channel-scoped YouTube search is the DEFAULT for Entity beats:** `yt-dlp "https://www.youtube.com/@<handle>/search?query=<q>" --flat-playlist --print "%(title).75s ||| %(duration_string)s ||| %(id)s"` — search INSIDE the official/trusted channel. `ytsearchN:<query>` is the fallback; fully open results get flagged "⚠️ outside trusted sources".
  137. - **Metadata first, download later:** `--flat-playlist --print` costs seconds; download only the chosen winners (`-f "bv*[height<=1080]+ba/b"`).
  138. - **Tweets without login:** `https://platform.twitter.com/embed/Tweet.html?id=<TWEET_ID>` renders a clean card headlessly, no auth (`&hideThread=true`; capture with `scripts/cdp_capture.py`). The tweet's real attached media resolves via `https://cdn.syndication.twimg.com/tweet-result?id=<ID>&token=a`. Verify what the attachment actually shows before shipping it.
  139. - **Generic evocative stock is YouTube's weak spot:** add "free to use / no copyright" qualifiers; REJECT watermarked stock-site previews and clips with burned-in captions; if YouTube only yields junk, recommend a real stock site (Pexels / Mixkit / Coverr) instead.
  140. ## Once a beat is agreed, sourcing it is the AGENT's job — the escalation ladder
  141. "Login-walled" is a claim you prove by attempting, not a label for punting. Exhaust ALL of these before handing a beat back to the user:
  142. 1. **Local artifacts** — grep the user's notes/downloads/prior sessions for the exact link or handle.
  143. 2. **Identity hunt** — web-search via mention-context (distinctive phrases beat bare names); resolve shortlinks; oEmbed endpoints identify authors without auth.
  144. 3. **Plain `yt-dlp`** — public profiles/videos usually need NO login.
  145. 4. **`yt-dlp --cookies-from-browser`** — the user's logged-in cookies beat most walls.
  146. 5. **Headless Chrome + CDP** — for captures behind consent walls: click "accept" in EVERY frame context (CMPs render in iframes), with overlay-removal as fallback; then VERIFY the capture by looking at it. Never deliver a screenshot you haven't visually inspected.
  147. 6. **The user's logged-in browser** (browser-automation MCP) when available.
  148. 7. Only if ALL genuinely fail → a precise you-source list, with a note of what was tried.
  149. ## Placement timing — land ON or just AFTER the word, never before
  150. - Anchor to when the keyword is **spoken**, then add a small lead (~+0.2s) so the cut lands as/just after it. B-roll *before* the word reads as a mistake.
  151. - **Timing source: Whisper word-level timestamps** (`--word-timestamps True`, one pass during transcription — no extra tooling). Find the keyword's word time and anchor +0.2–0.5s after it. Whisper word-ends run slightly early and embed pauses inside word durations, so **bias LATER when unsure** — late reads as intentional, early reads as a mistake.
  152. - _(MFA forced alignment was tried for ~10–20ms precision and REMOVED 2026-06-11 — the runtime cost wasn't worth it; whisper + later-bias is accurate enough in practice. Don't reintroduce it.)_
  153. - For punchlines, land on the beat *after* the punchline.
  154. - **Connect adjacent b-rolls:** if two cutaways sit closer than ~a half-sentence apart, extend the first to the second's start — a <2s flash of the speaker's face between them reads as an error. (Extend the earlier clip; never start the next one before its keyword.)
  155. ## Composition — full-bleed, no composites
  156. - **Cover-crop, never letterbox:** `scale=W:H:force_original_aspect_ratio=increase,crop=W:H`.
  157. - **No agent-built composites:** no split-screens, no 2-ups, no clever framing. Two referenced people → sequential full-bleed singles. The ONE allowed treatment beyond cover-crop is **blurred-fill** (enlarged blurred copy behind a fitted clip).
  158. - **Partial-source / split-screen subjects:** blurred-fill, never cover-crop (cover-cropping a half-frame zooms hard into a face).
  159. - Don't upscale a tiny source to full-bleed — find a higher-res source.
  160. ## Iteration discipline — the b-roll manifest
  161. Across re-renders the #1 failure is silently DROPPING beats the user already approved. Keep a **`BROLL-MANIFEST.md` next to the deliverable**: one row per beat (in/out · beat · asset · status incl. which version approved it) plus a "Removed (do not re-add)" list. Before EVERY re-render: read the manifest, verify every approved beat is in the new cut, add the new ones, update statuses. Approved b-roll never disappears without the user explicitly cutting it.
  162. ## Self-verification — look at every cut before the user does
  163. After every render, extract a frame at **every beat's midpoint AND every joint** (b-roll↔b-roll, b-roll↔face), tile them into a grid, and LOOK at it. Fix and re-verify. A render isn't done until the grid is clean.
  164. **Explicit AUTO-REJECT checklist — a frame containing ANY of these fails, no judgment call:**
  165. 1. Burned-in captions/subtitles from the source clip
  166. 2. Name-tags / lower-thirds identifying strangers
  167. 3. Watermarks or channel logo bugs (corner badges from official bodies are a flagged exception, not a free pass)
  168. 4. The speaker's own face/tile appearing as b-roll in their own video
  169. 5. A generated card where the beat names a literal, filmable thing
  170. 6. Template-looking composites (two portraits side by side, collage cards)
  171. 7. Letterboxing, tiny floating content, or visible blur-edge framing errors
  172. 8. A split-second sliver of talking head (<1s) between two cutaways — connect them: extend the first beat to the second's start (never start the second early)
  173. Grade the grid against this list line by line — "looks fine" without the list is how watermarked clips ship.
  174. ## Fetching & formatting (editor-friendly, silent, full-bleed)
  175. - **Proxy FIRST for big sources:** if the base video is 4K/HEVC/>500MB, transcode a 1080p working copy before anything (`ffmpeg -hwaccel videotoolbox -i src -vf scale=1920:-2 -c:v h264_videotoolbox -b:v 6M -c:a aac proxy.mp4`) — every later step (frame scans, renders) runs 5–10× faster against it.
  176. - Don't grab low-res pre-merged streams — select a real stream (`-f "bv*[height<=1080]+ba/b"`).
  177. - Don't let `--download-sections` be the final cut (variable framerate stutters) — download the short clip, then trim with a re-encode.
  178. - Standard format: constant fps, cover-crop full-bleed, audio stripped:
  179. ```
  180. ffmpeg -ss <in> -t <dur> -i full.mp4 \
  181. -vf "fps=30,scale=1920:1080:force_original_aspect_ratio=increase,crop=1920:1080,setsar=1" \
  182. -an -c:v libx264 -crf 18 -preset slow -pix_fmt yuv420p -movflags +faststart out.mp4
  183. ```
  184. - Attribution on → composite the small credit label (PIL-rendered PNG, ~70% opacity) via `overlay` during formatting (some ffmpeg builds lack `drawtext`).
  185. ## Workflow summary
  186. 1. **Load the taste profile / set topic** — [TASTE.md](TASTE.md) (or the user's fork): fingerprint, preferences, and trusted sources filtered to this video's topic tag.
  187. 2. **Ask style + cadence** — format (podcast / tutorial / fast-cut / heavy-intro) and density. These override genre defaults.
  188. 3. **Get the transcript** — paste, pull from the editor, or transcribe (GPU Whisper, word-level). Long-form (>~10 min): score segments for b-roll value and select the high-value ones first — don't uniformly b-roll an hour.
  189. 4. **Classify + propose (no fetching yet)** — annotate each beat with its interpretation, route, the reference sweep result, and the palette mix. **Present the plan and wait for the user to react** before sourcing.
  190. 5. **Constrained search** — scoped to trusted/official sources; score candidates; verify person clips against mention-context; drop the weak ones.
  191. 6. **Contact sheet → user picks.**
  192. 7. **(Optional) place & render** — cut full-bleed + silent, anchored on the word, adjacent beats connected, manifest updated, **self-verification grid before delivery**.
  193. ## Tools
  194. - **Transcription:** GPU Whisper for transcript text (large model — the transcript drives *understanding*, so text accuracy matters).
  195. - **Anchor timing:** Whisper word-level timestamps + later-bias (+0.2–0.5s past the keyword).
  196. - **Search / download:** `yt-dlp` (no API key); headless browser + CDP for public-page screenshots (consent walls: click accept in every frame context, verify visually).
  197. - **Motion-graphics:** Remotion (or similar), rendered full-bleed + silent.
  198. - **Stills zoom:** `scripts/zoom_still.py` (sub-pixel PIL float-box → x264; `--blurfill` for portrait/odd aspect; never `zoompan`).
  199. - **Consent-wall captures:** `scripts/cdp_capture.py` (headless Chrome via CDP — clicks "accept" in every frame context, CMP-iframe aware; `CDP_SCALE=2` for crisp receipts).
  200. - **Cutaway rendering:** `scripts/render_cutaways.py` (segment-concat template: base visual replaced per beat window, audio untouched).
  201. - **Compositing:** `ffmpeg`; `ImageMagick` for contact sheets.
README.md · README · 175 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 🎬 B-Roll Finder
  2. ![b-roll-finder](./banner.png)
  3. **An agent skill that sources accurate, on-brand b-roll for talking-head video — and places each cutaway on the exact word.**
  4. It reads your transcript, figures out what each line is *actually* about, routes every moment to the right kind of footage, and hands back a tight set of vetted candidates (you make the final pick). No keyword-matching, no random stock, no padding.
  5. ---
  6. ## ✅ What to use it for
  7. It's built for **reference-rich talking-head video**, where the speaker names concrete things or makes verifiable claims. That's where b-roll has a *correct* answer the agent can nail.
  8. **Best use cases:**
  9. - **🎙️ Podcast & interview intros** — "In today's episode I'm joined by *[guest]*, founder of *[company]*…" Every name, company, role, and credential becomes a precise cutaway: the guest's face, their product UI, a receipt proving the claim.
  10. - **📚 Tutorial & explainer intros** — "Today we're using *[tool]* to do *[thing]*." Product UIs, concept motion-graphics, and stat cards that make the setup land.
  11. - **Competitor / drama videos** — receipt-heavy (tweets, headlines, reviews).
  12. - **Storytelling / listicles** — people, products, historical moments, text cards.
  13. **Where it shines:** the more proper nouns and provable claims a script has, the better. *Name it or prove it → great. Feel it → it defers to you.*
  14. **Not for:** pure vibe/mood montages or non-verbal (music-only) videos — there b-roll is a taste call, and this skill hands the wheel back to you.
  15. ---
  16. ## 📥 Install
  17. It's an **agent skill** — a methodology file your AI coding agent (e.g. [Claude Code](https://claude.com/claude-code)) reads and follows. There's no package to `npm install`; you register the skill and install the CLI tools it drives.
  18. **1. Clone the repo**
  19. ```bash
  20. git clone https://github.com/louisedesadeleer/b-roll-finder.git
  21. ```
  22. **2. Register it with your agent.** For Claude Code, add a pointer in your `CLAUDE.md` (or drop `SKILL.md` in your skills directory):
  23. ```markdown
  24. #### /find-broll
  25. Read: /path/to/b-roll-finder/SKILL.md
  26. Source b-roll for a video edit — classify each moment, scope the search, return vetted candidates, place on the word.
  27. ```
  28. **3. Install the tooling it drives** (macOS / Homebrew shown):
  29. ```bash
  30. brew install yt-dlp ffmpeg imagemagick # search/download, compositing, contact sheets
  31. uv tool install mlx-whisper # GPU word-level transcription (Apple Silicon)
  32. # …or: pip install -U openai-whisper # CPU fallback
  33. npm create video@latest # Remotion, for concept motion-graphics (optional)
  34. ```
  35. A Chrome/Chromium install is also used for headless screenshots of public pages. No API keys required.
  36. **4. (Optional) make the taste yours.** The skill ships with a working taste profile — [TASTE.md](TASTE.md) — so it sources well from the first run. When you're ready, fork it: import your YouTube subscriptions, prune, and reveal your own fingerprint from your published videos (the file walks you through it).
  37. ---
  38. ## 👅 It ships with taste
  39. Sourcing is only half the job — the other half is **curation**, and that's where most b-roll automation falls flat. So this skill ships with a real taste profile, [TASTE.md](TASTE.md), instead of starting you from a blank interview:
  40. - **A revealed fingerprint** — extracted from actual published videos by scene-cut analysis (not from a questionnaire): which b-roll types get used and how often, real pacing numbers (~26–28 cuts/min, median shot under 2s, sub-second "receipt montages"), and coverage ranges per video style.
  41. - **A curated, topic-tagged source list** — the channels searches are scoped to, with a note on *why* each one earns b-roll (deadpan reaction gold ≠ credibility flex ≠ concept explainer). A tech video never gets scoped to someone's surf vlogs.
  42. - **Opinionated guardrails** — always-silent clips, sub-pixel-only stills motion, no random open search.
  43. It also encodes the insight that makes agent-sourced b-roll trustworthy at all: good fast-cut video leans on **objective** b-roll (receipts, official entity clips, your own graphics) — where there's a checkably *correct* answer — and almost never on vibe-picked creator clips. The profile keeps the agent in that lane.
  44. Use it as-is, or fork it — TASTE.md ends with the three-step "make it yours" recipe (import-then-prune your subscriptions, reveal your fingerprint from your own videos, set your guardrails).
  45. ---
  46. ## ▶️ How to use it
  47. Invoke the skill and hand it your video. It runs a **plan-first** loop — it asks a couple of setup questions, proposes a plan, and **waits for your go before sourcing anything.**
  48. ```
  49. you: /find-broll
  50. here's my podcast intro — <transcript or /path/to/intro.mp4>
  51. it: • asks: format/style? cadence? motion-graphics? any guests + handles?
  52. • proposes an annotated plan — per-beat interpretation + b-roll type + palette mix
  53. you: approve / cut / swap / add
  54. it: • sources a scored contact sheet of vetted candidates
  55. you: pick the ones you like
  56. it: • (optional) cuts them full-bleed + silent and places each on the word
  57. ```
  58. **What to give it:**
  59. - A **transcript** (paste it), **or** a **video/audio file path** (it transcribes with word-level timestamps), **or** a project from your editor.
  60. - Any **must-includes**, and **guest names/handles** for interviews.
  61. ### What kind of video works best
  62. - **Reference-rich talking-head** — a **podcast/interview intro** or a **tutorial/explainer intro** where the speaker names concrete things (people, products, companies, events) or makes verifiable claims. The more proper nouns and provable claims, the better the results.
  63. - **Short is ideal** (under ~10 min). For long videos, it scores and selects the high-value segments first instead of blanketing the whole runtime.
  64. - **Skip it for** pure vibe/mood or music-only video — there b-roll is a taste call it hands back to you.
  65. ---
  66. ## ⚙️ How it works
  67. ```
  68. transcript ─► interpret each beat ─► classify & route ─► source candidates ─► you pick ─► place on the word
  69. ```
  70. 1. **Understand the topic first.** It reads the *whole* transcript and states the thesis before sourcing anything. B-roll illustrates the **point**, not the nearest keyword. (A line like *"Zaria from Duolingo made their social pop off"* is about *the person and the account she built* — not the Duolingo logo.)
  71. 2. **Per-beat interpretation.** For every candidate moment it writes one sentence — *"what is this line actually about?"* — then sources *that*. If nothing accurately illustrates the real point, it **drops the beat**. No b-roll beats wrong b-roll.
  72. 3. **Classify & route.** Each moment goes to the source that has the *correct* answer for it (see the routing table below).
  73. 4. **Scope the search.** YouTube searches stay inside trusted/official sources — official channels for entities, authoritative sources for concepts — never random open-search.
  74. 5. **Score every candidate** on recency-fit, source authority, relevance, recognizability, and format-fit. Stale or off-topic candidates are dropped before you ever see them.
  75. 6. **Contact sheet → you pick.** It narrows the funnel and presents vetted candidates. **The agent never makes the final taste call — you do.**
  76. 7. **Place it precisely.** Picked clips are cut full-bleed and silent, then dropped on the exact spoken word (anchored with word-level timestamps, landing just *after* the word — never before). Adjacent cutaways are connected — no split-second face flashes between them.
  77. 8. **Verify its own render.** After placing, it extracts a frame at every beat's midpoint and every joint, tiles them into a grid, and *looks* — catching wrong shots, burned-in captions, and stray overlays before you ever see the video. Every edit keeps a **b-roll manifest** so approved beats never silently disappear between versions.
  78. **Cadence:** front-loaded by default — a dense, punchy hook, then sparse and precise through the body. Accuracy over volume, always.
  79. ---
  80. ## 🎨 What kind of b-roll it sources
  81. It deliberately **mixes the palette** — never leans on website screenshots for everything:
  82. | Type | When | Example |
  83. |---|---|---|
  84. | **Faces (video)** | A named person is introduced | A live interview clip of the guest talking (never a frozen headshot) |
  85. | **Product / UI** | A tool or company is named | The actual app UI / a real screen-recording of the product |
  86. | **Receipts** | Something happening *now* — news, claims, drama, "people are saying" | Tweets, article headlines, reviews, search results — captured as clean screenshots |
  87. | **Reference screenshots** | A specific thing is cited | The real post, essay, or page being referenced (not a synthetic card) |
  88. | **Concept motion-graphics** | An abstract idea, process, or stat with no literal footage | Custom on-brand animations (e.g. via Remotion) — voice-agent waveforms, growth charts, "$300M+" stat cards |
  89. | **Real / evocative footage** | A story, action, place, or mood | Stock that *conveys* the point (bakery, paperwork, an airport) — checked for watermarks and AI-slop |
  90. | **Historical / products** | A historical moment or physical product | Canonical archival footage; clean product shots |
  91. | **Memes / reactions** | A punchline or reaction beat | Curated from your own library (never auto-picked) |
  92. ---
  93. ## 🧭 The routing model
  94. Every moment is split by **what decides the right clip**:
  95. | Route | Trigger | Source |
  96. |---|---|---|
  97. | **Receipts** | Time-sensitive — drama, news, complaints, a current claim | Tweets / headlines / reviews, recency-sorted |
  98. | **Entity** | A person, a physical product, or a historical moment | Official / authoritative channel (the canonical clip) |
  99. | **Concept** | An abstract idea you'd have to *draw* | Custom motion-graphics — or real footage from the authoritative source |
  100. | **Cultural / Meme** | A creator clip or joke where *taste* decides | Your own library / exemplars — surfaced for you to pick, never blind-picked |
  101. **Litmus:** *Happening now?* → Receipts. *A person / product / event?* → Entity (official source). *An abstract idea?* → Concept (motion-graphics). *A reaction beat?* → Meme (your library).
  102. ---
  103. ## 🛠️ Under the hood
  104. - **Transcription & timing:** GPU Whisper with word-level timestamps — anchors land +0.2–0.5s after the keyword (biased late: late reads as intentional, early reads as a mistake).
  105. - **Search & download:** `yt-dlp` (no API key) for YouTube; headless browser for public-page screenshots (with consent-wall handling via CDP — it clicks "accept" in every frame context and visually verifies each capture).
  106. - **Motion-graphics:** Remotion, rendered full-bleed and silent in your brand style.
  107. - **Stills motion:** a very subtle Ken Burns zoom on static images by default — rendered **sub-pixel** (float-precision Lanczos per frame), never ffmpeg `zoompan` (integer-stepped = shaky). Opt out to fully static at onboarding.
  108. - **Compositing:** `ffmpeg` — full-bleed cover-crop (never letterboxed), blurred-fill for partial-frame subjects, no agent-built split-screens, audio stripped from every clip. Optional small source-credit label bottom-right (off/white/black/auto).
  109. ---
  110. ## 📐 Principles it follows
  111. - **The agent never picks the final b-roll — you do.** Its job is to narrow the funnel to vetted candidates.
  112. - **Accuracy over volume.** Fewer, perfectly-accurate beats beat lots of mediocre ones. Drop a beat before padding it.
  113. - **Full-bleed, always.** Every clip fills the frame edge-to-edge — never tiny, never letterboxed.
  114. - **Land on the word, never before.** B-roll that appears before the word is said reads as a mistake.
  115. - **Mix the palette.** If a plan is >60% website screenshots, it's wrong.
  116. - **Skip is the last resort.** Every beat gets the full palette walked before it's allowed to stay empty.
  117. - **Once a beat is agreed, sourcing it is the agent's job.** A seven-step escalation ladder (local artifacts → identity hunt → yt-dlp → browser cookies → headless CDP → logged-in browser) runs before anything is handed back to you.
  118. - **Approved b-roll never silently disappears.** The manifest is read before every re-render.
  119. ---
  120. ## License
  121. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.