Puffin Ship Docs

Getting Started

Puffin Ship is a web app that turns your raw material into a finished, on-brand video. You build a template (a pipeline of processing steps), then run it against your source files. Everything happens in the browser at app.puffinship.com; there's nothing to install.

This page walks through your first video end to end. For a tour of the visual editor itself, see Building in the editor.

1. Sign in and create a workspace

Sign in at app.puffinship.com. From the dashboard, click + New Workspace and give it a name.

A workspace holds your source files, your templates, and your run history. Most people keep one workspace per brand or project.

2. Upload your source material

Open the workspace and use Upload in the Files panel to add your footage, audio, or images. Steps in your template reference these files by name, so recognizable names help (speaker.mp4, logo.png). You can organize files into folders.

3. Add your service keys

Some processors call third-party services that are billed to you, so you provide those keys once per workspace:

Service key Used by Where to get it
OPENAI_API_KEY Transcription (generate_transcript, analyze_footage) platform.openai.com
GOOGLE_API_KEY AI video/image generation (Veo 3, Imagen) aistudio.google.com
HEYGEN_API_KEY AI avatar presenter (heygen_speaker) HeyGen settings
ELEVENLABS_API_KEY Text-to-speech voiceover (elevenlabs_tts) ElevenLabs settings
PEXELS_API_KEY Stock footage search (broll_websource with providers: [pexels]) Pexels API

Set them under Workspace Settings → Variables & Keys → Service API Keys. You only need the keys for the processors your template actually uses, and if you forget one, the app prompts you for it when you hit Run (see step 6). Keys are encrypted and can be overridden per template.

The media processor is not tied to one service: it needs the key for whichever service its preset or spec uses. For example, its veo preset needs GOOGLE_API_KEY.

4. Build a template

In the Templates panel, click New to open Build a Template. You have four ways to start:

  • Gallery: begin from a curated starter template and tweak it. Assemble Clips is the one to try first: it joins a few clips end to end and needs no service key at all.
  • Guided Wizard: answer a few questions (video type, add-ons like captions or music, aspect ratio) and get a working pipeline.
  • Chat + Steps: describe the video you want in plain language and let the AI assemble the steps.
  • Start empty: build from scratch in the editor.

Any of these drops you into the visual editor, where each step runs one processor. Add steps from the Library, configure them in the inspector, and wire one step's output into the next step's input. Browse every processor and its parameters in the processor reference.

Under the hood a template is just a YAML config. You can view and edit it directly with the YAML button in the editor; the full schema is in the Config Reference. Here's a minimal template that transcribes the footage, makes an AI content cut, and hands it back for review:

version: 1

project:
  name: "My First Edit"
  resolution: [1080, 1920]   # portrait; swap to [1920, 1080] for landscape
  fps: 30
  sample_rate: 48000

input:
  - id: speaker-footage
    select: "speaker.mp4"

timeline:
  levels:
    - name: main
      order: 1
      type: any
      backbone: true

pipeline:
  # Step 1: transcribe the footage
  - id: transcribe
    processor: generate_transcript
    input:
      - id: source
        file: speaker-footage
    params:
      language: "en"
    cache: true

  # Step 2: AI content cut. Claude reads the transcript and removes filler/dead air
  - id: ai_cut
    processor: ai_agent
    input:
      - id: transcript
        step: transcribe
      - id: speaker
        file: speaker-footage
    prompt: |
      You are an editor making a content cut. The transcript and silence intervals are
      already provided in the context block above. Call get_input("speaker") to get the
      source filename, then call create_edit_decision for each segment to keep.
      Use source=files[0], type="video", level="main". Snap in/out to silence boundaries.
      Remove: filler words, long pauses, false starts. Keep: complete sentences.
    output:
      timeline: main
    review: true
    cache: true

5. Run it

Open the Runs panel and click ▶ Run. Give the run a name; the template is saved and the pipeline starts. Each step runs in order, and you can watch live progress (pending, running, done, cached, or failed) for every step.

Two things are worth knowing before your second run:

  • Every run belongs to a run group. Clicking ▶ Run on the template starts a new group and runs everything from scratch; to make another attempt at the same video and reuse the work already done, run from inside the group instead. See Reusing work between runs.
  • There is a daily cap on how many runs you can start. See Daily run limits.

6. Missing keys, and review gates

  • If your template uses a processor whose service key isn't set, the run is held and an API keys required dialog lists exactly what's missing. Paste the key, choose whether to save it to the whole workspace or just this template, and the run continues.
  • The ai_cut step above has review: true, so the run pauses at a review gate and shows you what the AI decided. Approve it, approve with edits, reject it, or ask it to regenerate. See Review Gates.

7. Export

When the run finishes, open the run's timeline to preview the edit, fine-tune clip timing, and export:

  • FCPXML: a Final Cut Pro bundle you can open and finish in FCP.
  • SRT: subtitles.
  • MP4: a rendered video, generated on demand.

For details on fine-tuning clips and captions on the timeline before you export, and re-exporting after you make changes, see Editing and exporting a finished run.

Next steps