`broll_place`

AI agent that places existing video clips from your project into gaps on the broll timeline level, matching clip content to what the speaker is saying.

When to use

Use when you have a folder of broll clips and want AI to select and place them based on transcript content. Run before broll_veo_generate so existing clips get first pick of gaps. See the Broll guide for the full workflow.

In the editor

Add it from the Library (B-Roll group), or with + add step and a search for broll_place, after your transcript and your main cut.

Under Inputs, add transcript as a step input, clips as a file input naming the folder of footage you want it to choose from, and backbone as a step input pointing at your cut so that changing the cut makes it think again. The step's Prompt is where you say how it should choose, and eval_prompt is the bar a clip has to clear to be used at all. min_gap_sec and max_duration_sec control the rhythm: how far apart placements sit and how much of any one clip is used. Turn on full_coverage if you want no gaps left anywhere.

Tick Review gate so the run stops and shows you the choices before anything else is built on them.

The chosen clips appear on the b-roll level in the run timeline, over the gaps where you are not the focus, and you can preview, retime or remove any of them there. Run this before any generating step: it costs nothing to use footage you already have, so give it first pick of the gaps.

YAML Example

- id: broll
  processor: broll_place
  input:
    - id: transcript
      step: transcribe_main
    - id: clips
      file: broll-clips
    - id: backbone
      step: ai_cut
  params:
    min_gap_sec: 8
    max_gap_sec: 20
    max_duration_sec: 8
    backbone_step: ai_cut
    eval_prompt: >
      Accept: direct visual match to spoken content.
      Reject: vague topic overlap, people facing away, blurry footage.
  output:
    timeline: broll
  prompt: |
    Analyze every unanalyzed clip first (free, mandatory).
    Then fill backbone timeline gaps using approved clips where the content
    directly matches what the speaker is saying.
    Each clip should be placed at most once.
    Leave unfilled gaps blank; a broll_veo_generate step will handle those.
  review: true
  cache: true

Inputs

ID	Source	Description
`transcript`	step	Word-level timestamps from `generate_transcript`
`clips`	file (glob)	Broll clips folder
`segment_plan`	step (optional)	A `SegmentPlan` (e.g. from `video_director`) constraining where b-roll may go
`backbone`	step (optional)	Backbone timeline (used as a cache dep: re-run when the cut changes)

Params

Param	Type	Default	Description
`eval_prompt`	text	none	Accept/reject criteria for clip analysis. Drives what qualifies as a good match.
`context`	text	none	Background context injected into the system prompt. Supports `text:`, `file:`, `dir:`, `files:`.
`min_gap_sec`	duration (s)	`5`	Minimum spacing between placed clips
`max_gap_sec`	duration (s)	`0`	Gaps longer than this need coverage (0 = AI decides)
`max_duration_sec`	duration (s)	`8`	Max seconds to use from any single clip
`min_clip_sec`	duration (s)	`2`	Shortest b-roll clip allowed after trimming.
`min_use_sec`	duration (s)	`0`	Minimum clip use duration. Placements shorter than this are rejected.
`target_clip_sec`	duration (s)	`4`	Ideal b-roll clip length.
`trim_style`	select: `conservative`, `balanced`, `aggressive`	`"aggressive"`	How aggressively to trim clips to their most impactful moment.
`full_coverage`	bool	`false`	Require every second of the backbone to be covered: no gaps allowed
`required_clips`	list	none	Filenames that must be placed. The agent retries until all are placed.
`no_clip_reuse`	bool	`false`	Reject placements that reuse overlapping in/out ranges from the same source file
`max_generate`	number	`0`	Maximum number of clips to place. 0 = no limit.
`backbone_step`	string	none	Step ID to read backbone timeline from (optional: enables backbone-aware placement)

Output

EditDecisions on the broll level.

Notes

Uses Puffin Ship's built-in AI: no API key required.
Clip analysis is cached in broll/manifest.json. Ask the AI Assistant to clear the step's saved work, or re-run from that step with the per-step control on the run page, to force re-analysis.
Matching is strict by design: clips are only placed where they directly illustrate the spoken content.
This processor sees all broll clips placed by all previous pipeline steps, so two broll_place steps with different clip sources won't overlap.