Puffin Ship Docs

Captions Guide

Puffin Ship generates per-word highlighted captions; each word lights up in highlight_color when it's being spoken.

In the editor

Add a captions step from the Library, under Overlays, at the end of your template. Under Inputs, wire transcript to your transcript step and backbone to the step that made the cut, both as step inputs. Set Output Level to your captions level.

The settings worth trying first are max_words (fewer words on screen reads better on a phone), position_y (negative numbers sit the captions lower in the frame) and highlight_color (the word currently being spoken). If a name or a term keeps coming through wrong, put it in word_corrections rather than fixing it clip by clip.

Order matters here more than for most steps: captions are timed against the cut, so build them once the cut is settled. If you change the cut afterwards, run the captions step again.

Setup

You need a finalized transcript and a backbone cut. Run captions after your edit is stable (changing the cut after generating captions requires re-running captions).

- id: captions
  processor: captions
  input:
    - id: transcript
      step: correct_transcript   # use the corrected transcript
    - id: backbone
      step: ai_cut               # maps source timestamps to timeline positions
  params:
    max_words: 5
    font_size: 72
    position_y: -480
    highlight_color: "red"
  output:
    timeline: captions
  cache: true

How captions are stored

On the first run, captions computes a set of caption groups from the transcript. Each group is the words shown together on screen as one rendered clip, e.g.:

- start: 0.12
  end: 0.82
  text: "Hello world"
- start: 1.10
  end: 1.80
  text: "this is a caption"

These groups are saved with the run group, so a run started from inside that group, or a re-run from a later step, reuses them instead of recomputing. A fresh run from the template computes them again. See Reusing work between runs.

Fixing captions

You have three ways to correct captions, in increasing scope:

  • Edit a single caption's text: open the finished run's timeline and select a caption clip; its text is editable inline, then re-render.
  • Fix recurring mishears before grouping: use the word_corrections param (below), which rewrites words as the transcript is grouped, preserving timing.
  • Regenerate from scratch: ask the AI Assistant to clear the captions step's saved work, or re-run from that step with the per-step control on the run page; a fresh set of caption groups is computed from the transcript.

word_corrections

Use word_corrections to fix common TTS mishears before grouping. These are applied before the manifest is generated:

params:
  word_corrections:
    "ninety nine percent": "99%"
    "red panda": "Redpanda"
    "cue ell": "SQL"

Multi-word corrections merge the matched words into a single manifest entry with redistributed timestamps, so the correction doesn't break timing.

Positioning

position_y is in FCP pixels from center. Negative values are below center:

  • -480: near the bottom of a 1080×1920 frame (good default for portrait)
  • -200: lower-third area
  • 0: center of frame

scale adjusts the overall size of the caption group relative to font_size.