b-roll-suggester

Files (1)

• SKILL.md

SKILL.md (first lines)

# B-roll suggester

You are placing visual cutaways for spoken content using cutaway
footage that **already exists in the project** as a separate asset
(drone shots, B-cam, room shots, demo footage, an imported cutaway
library — anything in `raw/` other than the speaker's primary
recording).

B-roll is a retention tool, not decoration. Each cutaway must do at
least one of: **visualize** (show what the speaker references),
**clarify** (make an abstract point concrete), **reset attention**
(break up a long talking-head stretch), or **cover an edit** (hide a
removed silence / filler / jump cut). Random "person typing on
laptop" is filler — it hurts retention. Every insert must be tied to
the sentence being spoken.

## Precondition: this skill needs a real B-roll library

**Do not run this skill if the project's only asset is the primary
recording.** "No-face shots" in a single-asset talking-head project
are NOT cutaways — they are moments the speaker is briefly off-camera,
the camera was pointed at empty studio, or a wide multi-cam frame the
face detector missed. Treating those as B-roll inserts the speaker's
own footage as "B-roll", which is just a jump cut to the same person.

Check first via `view_episode` or by inspecting `raw/`:

- `raw/` contains ONLY the primary recording (one asset, or one
  primary plus transcript/audio sidecars): this skill does NOT apply.
  Route via the addendum's 4-step pipeline to `stock-broll`,
  `yt-broll`, or AI generation depending on what the transcript asks
  for. Tell the user honestly that the project has no cutaway library
  to draw from.
- `raw/` contains separate cutaway material (`b-roll/`, `broll/`,
  `cutaways/`, `drone-shots/`, `demos/`, `screen-recordings/`, etc.):
  proceed below.

## Trigger taxonomy — when to insert at all

Do not ask "can I add B-roll here?" Ask "does this sentence create a
visual need?" Score each candidate moment from the transcript:

**HIGH-confidence (insert):**
- Named entities (people, companies, products, places, tools)
- Visual nouns (data center, classroom, drone, chart, website, app)
- Numbers / statistics (revenue, percent, growth, market size)
- Processes ("first… then… after that…")
- Comparisons ("before vs after", "old way vs new way")
- Historical references ("In 2008", "during COVID", "when X launched")
- Abstract concepts that need simplification (algorithm,
  attention economy, data pipelines, inflation)
- Editing problem areas (long pause, filler-word cluster, off-topic
  cut, jump-cut cover)

**LOW-confidence (use punch-in / angle switch / text overlay
instead, NOT a full-frame cutaway):**
- Generic statements with no concrete subject
- Connector phrases ("anyway", "so", "and then")
- Low-energy filler that doesn't move the conversation

**NEVER auto-B-roll:**
- Laughter
- Emotional confession
- Heated debate
- Punchline
- The guest's strongest quote
- Host directly addressing the audience
- Moments with strong facial expression (anger, surprise,
  vulnerability)
- Moments where the visual accuracy is uncertain — if you'd be
  guessing whether a cutaway is right, don't insert

These are parasocial / emotional / proof-of-presence beats. The face
IS the value. Covering them kills the moment. Insert B-roll BEFORE or
AFTER these lines, not during.

## The 4-step playbook

### 1. Read the visual structure of the cutaway library

```
view_episode    # confirm vision indexers ran on the cutaway asset(s)
shot_summary    # what's the visual texture of the cutaway library?
```

Run `shot_summary` against the **cutaway-library asset(s), not the
primary recording**. If the cutaway library is thin or absent (<20%
no-face shots there), the project doesn't have meaningful B-roll
material to draw from — tell the user honestly and route to
stock-broll / yt-broll / AI generation as above.

### 2. For each spoken passage, find the best cutaway

```
inspect_moment(moment_id=...)   # what concept does this sentence carry?
find_speaker_oncam(at_s=...)    # is the speaker visibly demoing/holding
                                 # something? if YES skip — their footage
                                 # IS the content
broll_candidates(
    asset_id="<cutaway-asset>",  # MUST point at a separate cutaway asset
    min_duration_s=2.0,
    types=["no-face", "wide"]
)
clip_search(query="<concept>", min_score=0.20)
```

The intersection of `broll_candidates` (good cutaways) and
`clip_search` (semantically matching the audio) is your suggestion
list. Rank by `clip_search` score.

### 3. Suggest, don't auto-commit

Present 3-5 candidates per passage with score, duration, type, and a
one-line "why":

```
For "talking about Samsung's battery problems" at 744s-751s:

  Cutaway A: frame at 1996s (Reddit screenshot - phone exploded)

From explicit09/montage, Apache-2.0.

More from explicit09/montage