Drawings Guide

Drawings are animated video clips (lists, text cards, logo displays, diagrams, and data visualizations) that Puffin Ship renders and places on a timeline level (usually broll).

Drawing types

Processor	What it creates
`drawing_list`	Animated bullet/numbered/checkmark list
`drawing_text`	Text headline + optional subtext
`drawing_logos`	Company logos with connectors
`drawing_diagram`	Flow diagram with nodes and edges
`drawing_remotion`	Remotion compositions (stats, chart, etc.)

In the editor

Every drawing type is a step you add from the Library, under Overlays, and configure in the Inspector. There are two ways to work.

Place them yourself. Add one step per drawing, fill in its content (the lines of a list, the text of a headline, the companies in a logo row), and set duration_sec. Leave position_sec empty and each clip drops into the next free gap; set it and the clip appears at that second exactly. This is the approach when you know what you want on screen and when.

Let it decide. Add a single drawings_ai_placer step with your transcript wired in, and it invents the overlays and their timing from what is being said. Cap it with max_generate, and tick Review gate so you see the result before the run carries on.

Either way the overlays arrive as their own clips on the level you chose, and you can preview, retime or delete them in the run timeline afterwards. Use the same brand_palette on every drawing step in a template, or the overlays will not look like they belong to the same video.

Manual placement

Add a drawing processor directly to your pipeline at a specific position:

- id: features
  processor: drawing_list
  params:
    title: "Key Features"
    items:
      - "Real-time streaming"
      - "Zero ops"
      - "Kafka API compatible"
    style: checkmark
    duration_sec: 5.0
    background: "solid:#1a1a2e"
    brand_palette: "e94560"
  output:
    timeline: broll

The clip is placed at the next available position on the broll level. To control timing precisely, use position_sec or set it via drawings_ai_placer.

AI placement

drawings_ai_placer reads your transcript and automatically decides what to create and where to place it:

- id: drawings
  processor: drawings_ai_placer
  input:
    - id: transcript
      step: transcribe_main
  params:
    max_generate: 6
    brand_palette: "1a1a2e,e94560,0f3460"
    safe_zone_bottom_pct: 20     # keep bottom 20% clear for captions
    backbone_step: ai_cut
  output:
    timeline: broll
  review: true
  cache: true

Use review: true to approve the placements before continuing.

Shared params (all drawing processors)

Param	Default	Description
`background`	`"auto"`	`"auto"` or `"solid:#rrggbb"`. `"auto"` picks from `brand_palette` or defaults to dark.
`brand_palette`	none	Comma-separated hex colors used for styling
`padding_pct`	`8`	Padding around content as % of frame width
`duration_sec`	`5.0`	Clip duration in seconds
`level`	`"broll"`	Output timeline level

Safe zones

If you're using captions, set safe_zone_bottom_pct in drawings_ai_placer to prevent drawing content from overlapping with caption text. A value of 20 keeps the bottom 20% of the frame clear.

Brand palette

Pass 2–4 hex colors as a comma-separated string:

brand_palette: "1a1a2e,e94560,0f3460,533483"

All drawing processors in the pipeline should use the same palette for visual consistency.