Puffin Ship Docs

edit

Applies an ordered chain of edit operations to your clips in a single step.

When to use

Use edit when you want to adjust how footage looks or sounds: zoom or reposition a clip, crop or rotate it, grade its color, sharpen it, change its volume, add a fade, or clean up background noise, and especially when you want to combine several of those changes at once. Operations run in the order you list them.

Some operations are lightweight and change only how a clip is framed (scale, position, volume, reframe): these are applied instantly as adjustments, with no re-processing of the footage. Others change the picture or audio itself (color, crop, rotate, sharpen, fades, noise reduction, overlay): for these, the clip is re-processed. To keep that fast, only the parts of each source that actually appear in your edit are processed, unless you ask for the whole file. A few operations generate a brand-new clip instead of adjusting an existing one (title cards): because there's no existing clip to adjust, a generated operation must be the only entry in its step's operations list.

In the editor

Add it from the Library (Transforms group), or with + add step and a search for edit.

Point its source input at your footage (a file) or at an earlier step that produced edit decisions. Then build the operations list: each entry has a type and that operation's own settings. Use the segments control to choose whether it works only on the portions of a source that appear in the edit (the default) or on the entire source file.

YAML Example

- id: polish
  processor: edit
  input:
    - id: source
      step: assemble          # an earlier step's edit decisions
  params:
    operations:
      - type: color           # re-processes the picture
        contrast: 1.1
        saturation: 1.05
      - type: scale           # applied as an adjustment, no re-processing
        factor: 1.15

Inputs

ID Source Description
source file or step Source footage, or an earlier step's edit decisions referencing a source

Params

Param Type Default Description
segments select: auto, used, full "auto" Which parts of the source to process.
operations text none Ordered list of edit operations to apply. Each entry has a type and its settings.

Output

Varies by chain. A chain of lightweight adjustments produces TransformPatches (applied without re-processing footage); a chain that changes the picture or audio produces re-processed sources that downstream steps and the export use automatically.

Notes

  • You can freely combine lightweight adjustments and re-processing operations in one step. When any re-processing operation is present, the lightweight adjustments are applied within the same single pass, so there is no extra quality loss from combining them.
  • segments defaults to auto, which processes only the portions of a source used in the edit. Set it to full to process the entire source file.

Available operations

Each entry in operations needs a type from the list below, plus that operation's own settings.

Framing, lightweight (applied instantly as an adjustment, no re-processing):

Type What it does Params (default)
scale Resizes the clip. factor (required)
position Moves or repositions the clip within the frame. x (0), y (0)
reframe Scales the clip to fill the project's frame (e.g. landscape footage into a vertical video) and can pan horizontally to keep the subject centered. center_fraction (0.5, range 0–1), fill (true)

Framing, re-processing:

Type What it does Params (default)
crop Cuts the frame down to a smaller region. width (required), height (required), x (0), y (0)
pad Adds a border or letterboxing around the frame. width (required), height (required), x (0), y (0), color ("black")
rotate Rotates the clip. degrees (required; 90, 180, or 270)
flip Mirrors the clip horizontally or vertically. direction ("horizontal"; horizontal or vertical)

Look (re-processing):

Type What it does Params (default)
remove_background Removes the background behind the subject. color ("00ff00"; a hex color, with or without a # or 0x prefix), similarity (0.10), blend (0.05)
color Adjusts color, contrast, brightness, and saturation. contrast (1), brightness (0), saturation (1), gamma (1)
sharpen Sharpens picture detail. amount (1.0)
denoise_video Reduces visual grain and noise. strength (4)
deband Smooths out banding in the picture. strength (0.02)
stabilize Reduces shake and jitter in handheld footage. none

Audio (volume is a lightweight adjustment; the rest re-process):

Type What it does Params (default)
volume Raises or lowers the audio level. gain_db (required)
fade Fades audio in or out. direction ("in"; in or out), start (0), duration (1)
reduce_noise Reduces background noise in the audio. amount_db (10), floor_dbfs (-25)
loudnorm Normalizes loudness to a consistent level. target_lufs (-16)
tempo Speeds up or slows down audio playback. factor (1.0; must be between 0.5 and 2.0)
resample Changes the audio's sample rate. rate (48000)

Captions (re-processing):

Type What it does Params (default)
caption_burn Burns captions permanently into the picture. text (required), size (48), color ("white"), x (centered), y (centered)

Overlays (re-processing):

Type What it does Params (default)
overlay Composites an image (e.g. a logo or watermark) on top of the video. image (required, a project file path), x (0), y (0)

Generated (produces a standalone clip; must be the only operation in its step):

Type What it does Params (default)
title_card Generates a title clip (text on a transparent background) and places it on the timeline. Can't be combined with other operations in the same step. text (required), duration_sec (2.5), at_sec (0), level ("titles"), font_size (72), color ("white"), fade_sec (0.25)

Advanced:

Type What it does Params (default)
advanced_filter An expert-only option for settings not exposed elsewhere. Its settings are specific to the current processing engine and may change between versions, so most authors won't need it. video (optional text), audio (optional text), at least one is required