Puffin Ship Docs

broll_websource

Fills gaps in the broll level by searching copyright-free media providers (starting with Wikimedia Commons), using Claude to select the best match, downloading the file, and placing it in the gap.

When to use

Use broll_websource when you want to automatically fill broll gaps with free-licensed media from the web rather than generating new clips or using pre-downloaded footage. It runs a lightweight AI selection loop (no browser required, no screenshots) and is the fastest/cheapest way to add contextually relevant visual variety.

A good pipeline pattern is broll_place → broll_websource → broll_veo_generate: existing clips first, then web-sourced media for remaining gaps, then Veo 3 for anything left.

In the editor

Add it from the Library (B-Roll group), or with + add step and a search for broll_websource. It sits naturally between broll_place and broll_veo_generate: your own footage first, then free material from the web, then generated clips for whatever is still empty.

Under Inputs, add transcript as a step input, which is what the searches are built from. media_type chooses between video, stills, or both. min_gap_sec decides which gaps are worth filling and max_duration_sec how long anything stays up. max_clips caps the total. Leave review_clips on: it is what stops a diagram, a stock portrait or a wall of text from being dropped into your video. Leave auto_reframe on unless your project shape already matches the material.

providers picks where it looks. Leave it empty and it uses whatever your workspace has available, which is Wikimedia Commons unless you have added a Pexels key of your own under Variables & Service API Keys.

The chosen clips appear on the b-roll level in the run timeline, and the downloaded files are saved into your workspace's b-roll folder next to anything you uploaded, so you can see what it picked and reuse it later.

YAML Example

- id: web_broll
  processor: broll_websource
  input:
    - id: transcript
      step: generate_transcript
  params:
    backbone_step: ai_cut
    min_gap_sec: 5
    media_type: both
    providers: [wikimedia]
  output:
    timeline: broll
  cache: true

Providers

wikimedia (Wikimedia Commons) needs no key and is always available.

pexels needs your own Pexels API key, saved as PEXELS_API_KEY under Workspace Settings → Variables & Keys → Service API Keys. Pexels bills the account the key belongs to, so it works the same way as your HeyGen or ElevenLabs key.

Naming pexels in providers without that key set stops the run before it starts, and the app prompts you for the key. Leaving providers empty never asks for a key: it simply searches whichever providers your workspace has set up, which is Wikimedia Commons alone until you add a Pexels key.

Inputs

ID Source Required Description
transcript step no Transcript used to generate contextually relevant search queries and select the best result

Params

Param Type Default Description
gap_level string "broll" Timeline level to scan for gaps
media_type select: both, video, image "both" "video", "image", or "both"
min_gap_sec duration (s) 5 Ignore gaps shorter than this
min_duration_sec duration (s) 3 Minimum placed clip duration
max_duration_sec duration (s) 10 Maximum placed clip duration (clips are trimmed to fit)
max_clips number 0 Maximum edit decisions to output (0 = unlimited). With content_variants > 1, each gap produces N edit decisions; this cap applies to the total.
max_per_gap number 5 Max candidates fetched per provider per gap and shown to Claude
review_clips bool true Send each downloaded clip/image to Claude vision for review. Claude rejects diagrams, mugshots, dense text, solid-color frames, and content unrelated to the video topic. Set to false to skip review and accept all downloads.
auto_reframe bool true Scale each downloaded clip to fill the project canvas before placing it. Uses the same fill-height calculation as reframe: the clip is scaled so its height matches the output height, then centered horizontally. Set to false to place clips at native dimensions (useful when the source already matches your aspect ratio).
content_variants number 1 Number of alternative clips to place per gap. When > 1, all N clips are placed at the same timeline position; one is randomly enabled and the rest are disabled (greyed out in FCP). Toggle a disabled clip on to swap it in.
output_level string "broll" Timeline level to place clips on
backbone_step string none Step ID whose output defines total timeline duration (used to detect trailing gaps)
providers list none Provider names to use, e.g. ["wikimedia"] or ["wikimedia", "pexels"]. Leave empty for every provider available to your workspace

Output

EditDecisions: one edit decision per filled gap, with Source set to the downloaded file path, In=0, and Out=min(gap_duration, max_duration_sec).

Behavior

  1. Reads the transcript input if provided.
  2. Looks at everything already placed on gap_level and finds the uncovered stretches that are at least min_gap_sec long.
  3. For each gap:
    • If an LLM is available, generates a 3-5 word search query using transcript context.
    • Searches every enabled source at once.
    • Merges candidates, caps at max_per_gap.
    • If an LLM is available, asks Claude to pick the best match; otherwise uses the first result.
    • Downloads the chosen file to broll/ in the workspace.
    • If review_clips is true, sends the image (or a video frame) to Claude vision and skips the file if rejected.
    • If auto_reframe is true, scales the clip so it fills the height of your project's frame.
    • Places an edit decision spanning up to max_duration_sec.

Notes

  • Wikimedia Commons is free and requires no API key.
  • LLM calls are optional: the processor works without one but query quality and selection improve significantly with an LLM.
  • Downloaded clips land in your workspace's broll/ folder alongside any b-roll you uploaded yourself, so you can see and reuse them.
  • The step caches normally; clear the step cache to re-download fresh results.