Puffin Ship Docs

Building in the editor

Puffin Ship templates are built visually. You don't have to write YAML: you add steps, pick processors, and fill in parameters through the editor, and the config is kept in sync for you. If you'd rather type, the same template is editable as YAML in a full code editor, and the two views stay in step. This guide covers the editor's layout and the main things you'll do in it.

Starting a template

From a workspace, the Templates → New button opens Build a Template, which offers four starting points:

  • Gallery: start from a curated starter template.
  • Guided Wizard: answer a few questions (video type, add-ons such as captions or background music, aspect ratio, which AI features to use) and get a working pipeline assembled for you.
  • Chat + Steps: describe the video in plain language; the AI proposes a set of steps you can open in the editor.
  • Start empty: a blank template.

All four land you in the visual editor.

The editor layout

The editor has three regions:

  • Left panel: tabbed between:
    • Steps: the ordered list of steps in your pipeline.
    • Library: every processor, grouped by category, searchable, with any published Blocks listed at the top. See Adding a block.
    • Graph: a dependency view showing how steps feed each other.
  • Center: tabbed between:
    • Inspector: configures whichever step you've selected (or shows processor details when you're browsing the Library).
    • YAML: the template's config as text, in a full code editor. See Editing the YAML directly.
  • Right (the Runs panel): where you start runs and see run history. It collapses to a strip on narrow screens.

The header has the template name, Undo/Redo, a button that switches the center between Inspector and YAML, the Settings, tour, and more menu, and Save. That menu holds Settings, Take a tour (replay the guided tour that runs on your first visit), and Feedback & bug reports.

Adding and arranging steps

Each step runs one processor. To add a step:

  • In the Steps tab, click + add step (at the top, or between any two steps). A command palette opens; search for a processor and pick it.
  • Or, in the Library tab, select a processor to see its details, then click + Add to template.

New steps get an automatic ID (step_1, step_2, …) you can rename. Reorder with the ↑ / ↓ controls (or ⌘↑ / ⌘↓), duplicate with ⊕ (⌘D), and remove with × (Delete). A colored dot on each step flags problems: red for a missing required parameter, yellow for a broken input reference.

Configuring a step

Select a step to open it in the inspector:

  • Step ID: a unique name; other steps reference it.

  • Output Level: which timeline level this step writes to (e.g. main, broll, captions). See Timeline & Levels.

  • Prompt / Description: for AI processors, the instruction that drives the step.

  • Parameters: rendered from the processor's schema. Each parameter shows its label, a red * if it's required, and an i tooltip explaining it. Rarely used options are tucked behind Show advanced. The control matches the parameter type:

    Parameter type Control
    boolean checkbox
    select dropdown (with a "default" option when optional)
    number / duration numeric input, with min/max and a unit suffix
    color color swatch + #rrggbb field
    text multi-line text area
    list comma-separated text field
    string / level / file single-line text field

    Every processor's parameters are also documented in the processor reference.

  • Review gate: a checkbox that pauses the run at this step for your approval. See Review Gates.

Adding a block

A block is a reusable set of steps someone has shared: trim, caption and add sound effects as one thing you insert once. Blocks appear at the top of the Library tab, marked with who wrote them.

Picking one opens a dialog that does four things before anything is written:

  • Placement. Where the block's steps go: after a step you choose, or at the end of the template.
  • Wiring. Each input the block declares gets a dropdown of the steps already in your template. Required inputs have to be filled in before it will go any further.
  • Settings. The block's own options, rendered the same way a processor's parameters are.
  • The expansion. The steps it will add, by name, plus any service keys you will need and anything that does not fit your template. Insert stays unavailable until that last part is clean.

Inserting adds the steps to your template, prefixed with a name of your choosing so they cannot collide with your own or with a second copy of the same block. From then on they are ordinary steps: edit them, delete them, or run them.

Two things worth knowing. Inserting rewrites the file, so comments below the header are lost, and the dialog says how many before you commit. And a block you install does not update when its author publishes a change; install the newer version if you want it.

Wiring inputs between steps

Under Inputs, each input is a named slot fed by either a file or an earlier step. To add one, give the input an id, choose step or file, then:

  • step: pick an upstream step from the dropdown (only steps earlier in the pipeline appear). This is how one step consumes another's output.
  • file: type the name of a file you uploaded to the workspace.

Input IDs are conventional (source, transcript, backbone, …); each processor's page lists the inputs it expects.

Editing the YAML directly

The YAML tab in the center of the editor shows the whole template as text. It is a full code editor, not a text box, and anything you can express in the config reference you can write here, including options the Inspector has no control for.

Reading it. The document is syntax-highlighted using the same colors the Inspector uses for the same kinds of value (strings green, numbers blue, booleans amber), with line numbers down the side and matching brackets and quotes highlighted as you move through them.

Hover for help. Point at anything in the document and the editor explains it:

  • A processor name shows what that processor does, its category, the timeline level it writes to, whether it uses an AI model, and its settings (required ones first) with each setting's type, units, range and default.
  • A setting name under params: shows that setting's description, read from the schema of the processor that step actually runs. Two steps using different processors get different help for the same setting name.
  • A structural key shows what it means in the place it appears. id on a step is the name other steps refer to; id on one of that step's inputs is the input slot being filled.

This is the same information the Inspector shows in its parameter tooltips and the processor reference publishes, so it is always current.

Typing in it.

Key What it does
Tab With text selected, or with the cursor in a line's leading spaces, indents the whole line. Mid-line, inserts spaces to the next indent stop. It never inserts a tab character, which YAML does not allow.
Shift+Tab Removes one level of indentation.
Enter Keeps the current indentation, and indents one level deeper after a line ending in : or a bare -.
Cmd/Ctrl+F Search the document.
Cmd/Ctrl+Z Undo, including undoing back past mistakes made in the Inspector.

Opening brackets and quotes close themselves as you type.

Mistakes are visible, not silent. If the document stops parsing, the offending text is underlined, the tab shows a dot, and the line number and reason appear above the editor. Your text stays exactly as you typed it so you can fix it, but Save, Run and Save as template are unavailable until it parses, so a broken pipeline can't be saved over a working one or turned into a run.

Comments are kept. Editing here changes the text and nothing else, so your comments, blank lines, key order and quoting style survive exactly as written. Changing a step in the Inspector is different: it rewrites the file from the pipeline it describes, and only the comment block at the very top survives. When your document has comments further down, the YAML tab tells you how many would be lost that way. If comments matter to you, make that edit in the YAML tab.

A few options, such as cache_deps, have no Inspector control and are only set here.

Project and timeline settings

The editor's Settings slide-over (from the header menu) covers the project-level config: resolution (with 9:16 / 16:9 / 1:1 presets), FPS, the workspace's Variables & Service API Keys, and template actions like Duplicate and Delete. Timeline levels (the stacked tracks your steps write to) and their order are part of the config; see Timeline & Levels.

Custom variables you define here are used in the config as {{key}}, and encrypted custom secrets as {{secret:KEY}}. See Variables and secrets for the full picture, including how workspace, template, run group, and run values combine.

The AI Assistant

The floating AI Assistant (💬) is available throughout the app. In the editor it can edit your template for you: ask for a change ("add captions", "make the b-roll longer") and it proposes a config edit you can review as a diff and Apply to editor. It can also answer questions and, when you ask it to, perform actions like creating templates or starting runs (destructive actions ask for confirmation first). It's covered in depth in The AI Assistant guide.

Running and reviewing

Start a run from the Runs panel with ▶ Run. The template is saved and the Run dialog suggests a two-word name for the run (with a regenerate control if you want a different one) and shows a cost estimate based on your previous runs. If a required service key is missing, you're prompted for it before the run proceeds. Once it starts, you're taken to the run view, where each step reports progress (pending, running, done, cached, failed).

When a step has a review gate, the run pauses and shows you what it produced, whether that is a set of concept ideas, a script, or a segment plan, to approve, approve with edits, reject, or regenerate. When the run finishes, open its timeline to preview, adjust clip timing, and export to FCPXML, SRT, or MP4.

Editing a run group

Opening a run group from the Runs panel puts you in the same editor, scoped to that one group. Steps inherited from the template appear dimmed with an inherited tag. Restore to template (in the header) replaces the group's config with the template's current config. Save as template, a button in the group editor's Runs panel, turns the group's config into a template. See Run groups and variants.

Next steps