`video_director`

AI agent that reads a transcript and produces a SegmentPlan: time range assignments of content types (speaker, drawings, broll, empty) that downstream processors use to know what kind of content to place where.

When to use

Use after you have a transcript, before running drawings_ai_placer, broll_place, or broll_imagen_generate. The segment plan constrains those processors so they only fill the time ranges assigned to their content type.

In the editor

Add it from the Library (AI group), or with + add step and a search for video_director, after your transcript step and before the steps that fill the video with b-roll or overlays.

Under Inputs, add transcript as a step input pointing at any transcript step. Set backbone_step to the ID of the step that establishes how long the video is, usually your main cut. min_segment_sec stops it from proposing sections too short to be worth cutting to. content_types is where you tell it what kinds of section exist in your video and what each means; the default set covers a presenter, animated overlays, b-roll, and gaps.

Nothing lands on the timeline. What you get is a plan: this stretch is the presenter, this one wants b-roll, this one wants a diagram. Steps that place content read that plan through their own segment_plan input, so wire this step into each of them. Without that wiring they will still run, but they will decide placement on their own rather than following the plan.

YAML Example

- id: direct
  processor: video_director
  input:
    - id: transcript
      step: transcript
  params:
    backbone_step: assemble
    min_segment_sec: 3.0
    content_types:
      - name: speaker
        description: "Talking head / on-camera presenter"
      - name: drawings
        description: "Animated data viz or diagrams"
      - name: broll
        description: "Background footage"
      - name: empty
        description: "Gap, no overlay needed"
  cache: true

Inputs

ID	Source	Description
`transcript`	step	Any transcript step output

Params

Param	Type	Default	Description
`backbone_step`	string	none	Step ID to derive total timeline duration from
`min_segment_sec`	duration (s)	`2`	Minimum segment length: shorter proposed segments are merged
`system_prompt`	text	none	Optional extra context appended to the system prompt
`content_types`	text	none	Custom content type definitions. Each item: `{name, description}`

Output

SegmentPlan: an ordered list of time ranges with assigned content type labels and optional notes.

Notes

Uses Puffin Ship's built-in AI: no API key required.
Downstream processors that respect the segment plan: broll_place, drawings_ai_placer, broll_screenshot_websource, broll_imagen_generate.
The segment plan is accessed by those processors via a segment_plan input wired to this step. (backbone_step is only used to compute total timeline duration, not to read the plan.)