| name | kookaburra-export-presets |
| description | Kookaburra Cut export presets — the preset JSON schema, exporting through a preset or a custom EncodeSpec from the terminal, and creating/editing user presets at ~/Kookaburra Cut/export-presets/. Use when asked to "export for <platform>", "make an export preset", "change export quality/bitrate", "export smaller/for the web", "two-pass export", "H.265/HEVC export", "loudness target", or anything touching src/export/presets/, ~/Kookaburra Cut/export-presets/, or kookaburra:run --preset/--encode-json. |
kookaburra-export-presets
How Kookaburra Cut's export presets work and how to drive them from the terminal (v11 · M7–M8).
The architecture in one paragraph
A preset is a data-only JSON document. The frontend resolves it into a fully-resolved
EncodeSpec and Rust builds the ffmpeg argv from that spec only. THE FROZEN-PATH
RULE: an export carrying NO spec runs today's byte-pinned legacy argv (libx264 -preset medium -crf 18, native res, 60 fps) — presets are a separate argv family that
the standing baselines and Verify ×2 never see. The modal's "Kookaburra Cut Standard" row and
any kookaburra:run call without --preset/--encode-json take the frozen path.
- Bundled presets:
src/export/presets/*.json + the lineup in src/export/presetRegistry.ts
(explicit imports; a structure pin asserts every doc parses — extend the test when adding one).
- User presets:
~/Kookaburra Cut/export-presets/<slug>.json, listed as ws:<slug>
(export-presets is a reserved project slug). Write them directly as files or via the
app's Save-as-preset.
- Output naming: preset/custom exports write
<project>-<aspect>-<preset-id>.<ext>
(-custom for ad-hoc specs); the frozen path keeps the plain <project>-<aspect>.<ext>.
The preset document schema (version 1)
| Field | Type | Notes |
|---|
version | 1 | required; newer versions are refused, never mangled |
id / name / description | string | description = ONE Australian-English sentence for non-technical folk |
platform | string | the modal's grouping key ("Meta", "YouTube", …) |
favouredAspect | "16:9" | "9:16" | "1:1" | "4:5" | "5:4" | "3:2" | "2:3" | "phone" | "phone-landscape" | seeds the modal aspect row; --preset without --aspect exports this |
allowedAspects | aspect[] (optional) | constrains the aspect row; absent = all four |
maxFileSizeMB | number (optional) | the cap the estimate warns against (amber + Fit to cap) |
notes | string (optional) | shown in the detail pane |
video.codec | libx264 | libx265 | h264_videotoolbox | hevc_videotoolbox | prores_ks | VT lanes are "fast drafts" — excluded from Verify |
video.scaleShortEdgeTo | number (optional) | lanczos downscale, aspect preserved, even dims, never upscales; absent = native |
video.fps | 30 | 60 | the render clock steps AT this rate (v12 · M3) — 30fps lanes render half the frames in half the time, same pixels as the old decimation |
video.rate | {crf} OR {targetKbps, maxKbps, bufsizeKbps, twoPass?} | VT is bitrate-only and cannot two-pass; ProRes ignores rate (fixed 422 HQ) |
video.profile / level | string (optional) | e.g. "high" / "4.2" |
video.gopSeconds | number (optional) | keyframe interval ( = fps × gop) |
Worked example (~/Kookaburra Cut/export-presets/client-review.json):
{
"version": 1,
"id": "ws:client-review",
"name": "Client review",
"description": "A lean 1080p file that uploads fast and starts playing straight away.",
"platform": "Custom",
"favouredAspect": "16:9",
"allowedAspects": ["16:9", "9:16"],
"video": {
"codec": "libx264",
"scaleShortEdgeTo": 1080,
"fps": 30,
"rate": { "targetKbps": 6000, "maxKbps": 8000
The four flows
-
Export through a bundled preset (AFK-safe; auto-runs a fresh pnpm tauri dev):
pnpm kookaburra:run --action export --project showcase-tour --preset meta-reels
Without --aspect the preset's favouredAspect is used (here 9:16). Loudness is
measured automatically when the preset carries a target. Output:
~/Kookaburra Cut/showcase-tour/showcase-tour-9x16-meta-reels.mp4 (ws projects:
~/Kookaburra Cut/<slug>/exports/). Bundled ids: kookaburra-master, meta-reels, meta-feed,
tiktok, youtube, youtube-shorts, linkedin-ads, linkedin-organic, x,
reddit, telegram, ctv, web.
-
Export through a USER preset — write the JSON (schema above) to
~/Kookaburra Cut/export-presets/<slug>.json, then:
pnpm kookaburra:run --action export --project ws:my-project --preset ws:<slug>
-
Custom one-off encode — write a fully-resolved EncodeSpec JSON (camelCase,
the video block's fields + optional audio {codec, loudnessGainDb} flattened to
the top level) and pass its path; it travels inline in the env (no fs scopes):
cat > /tmp/spec.json << 'EOF'
{ "codec": "libx265", "fps": 30, "scaleShortEdgeTo": 1080,
"rate": { "crf": 24 }, "tenBit": true, "faststart": true, "colourTags": true,
"audio": { "codec": { : 128 } } }
EOF
pnpm kookaburra:run --action --project showcase-tour --aspect 16:9 --encode-json /tmp/spec.json
Gotchas
--aspect all = the STANDING three (16:9 · 9:16 · 1:1), not four. 4:5 is
first-class but must be asked for explicitly (--aspect 4:5).- VideoToolbox lanes are fast drafts — hardware-encoded, not byte-reproducible,
excluded from Verify by policy. Never use them for baseline work.
- Two-pass renders ONCE to an FFV1 mezzanine (
$APPDATA/cache/export-mezz/,
swept next run) — it needs disk (~2 bytes/pixel/frame at the OUTPUT size + 2 GB
margin) and a pre-flight guard blocks if short. Two-pass needs libx264/libx265.
- Loudness is gain-only — one
volume= slot; a projected true peak above
−1.5 dBTP warns but never limits. The measurement is cached (content+graph keyed).
- Software bitrate (VBV) lanes pin
-threads 1 (x264 VBV under threads is
non-deterministic — frames identical, bytes differing). CRF lanes are unaffected.
- Verify ×2 always runs the frozen path — presets don't change the standing gate.
Preset-lane Verify hashes are LANE proofs that re-record when the preset's knobs
change; they are not standing baselines.
- PCM audio only in .mov (ProRes); AAC everywhere else. 48 kHz fixed.
colourTags: true is the platform-correct choice — the frozen path writes no
tags (a v0-era decision baselines depend on); every bundled platform preset tags.
