`footage_assembler`

AI agent that reviews footage analysis and assembles an initial timeline, choosing which clips go on the backbone (speaker cuts) and which become broll, based on content and quality.

When to use

Use after analyze_footage as part of an auto-assembly pipeline. See Footage Director guide.

In the editor

Add it from the Library (AI group), or with + add step and a search for footage_assembler, straight after your analyze_footage step.

Under Inputs, add analysis as a step input pointing at that analysis step. style is a dropdown for the shape of the edit (documentary, explainer, highlight reel, interview). target_duration_sec is how long you want the result to be, and leaving it empty means it uses everything worth using. max_speaker_ratio caps how much of the video is a talking head, so the rest becomes b-roll. backbone_level and broll_level name the levels the two kinds of clip go on.

Tick Review gate on this step. It is the one that decides the shape of your video, and the gate stops the run to show you the assembly so you can approve it, edit it, or send it back for another pass before anything downstream is built on top of it.

After it runs, the timeline is populated: your main clips on the backbone level, supporting clips on the b-roll level, ready to preview and adjust.

YAML Example

- id: assemble
  processor: footage_assembler
  input:
    - id: analysis
      step: analyze_raw
  params:
    style: documentary
    prefer_original_audio: true
    max_speaker_ratio: 0.4
    target_duration_sec: 120
    backbone_level: main
    broll_level: broll
  output:
    timeline: main
  review: true
  cache: true

Inputs

ID	Source	Description
`analysis`	step	Output from `analyze_footage`

Params

Param	Type	Default	Description
`style`	select: `documentary`, `explainer`, `highlight_reel`, `interview`	`"documentary"`	Assembly style: `"documentary"`, `"explainer"`, `"highlight_reel"`, `"interview"`
`target_duration_sec`	duration (s)	`0`	Target total runtime in seconds. Empty = use all available content.
`min_clip_sec`	duration (s)	`2`	Minimum clip duration
`prefer_original_audio`	bool	`true`	Prefer clips with original audio for the backbone
`max_speaker_ratio`	number	`0.4`	Max fraction of total timeline as talking-head. Remainder is broll.
`backbone_level`	level	`"main"`	Timeline level for speaker clips
`broll_level`	level	`"broll"`	Timeline level for broll clips

Output

EditDecisions for both backbone and broll levels, plus an optional SegmentPlan indicating content type assignments, and an optional script file path in Paths.

Notes

Uses Puffin Ship's built-in AI: no API key required.
review: true is strongly recommended: always verify the assembly before continuing.
The generated SegmentPlan is used by downstream processors (heygen_speaker, drawings_ai_placer) to know which time ranges should have which content type.