agentleFS
michael-palmesmichael-palmes/kookaburra-cut/.agents/skills/kookaburra-export-presets/SKILL.md

kookaburra-export-presets

Skill10 starsChanged 2 days agoApache-2.0View on GitHub

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. Also covers exporting stills ("export a PDF", "PDF handout", "PNG images", "kookaburra:run --action stills"), which are not presets.

The file

Files
SKILL.md

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)

FieldTypeNotes
version1required; newer versions are refused, never mangled
id / name / descriptionstringdescription = ONE Australian-English sentence for non-technical folk
platformstringthe 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
allowedAspectsaspect[] (optional)constrains the aspect row; absent = all four
maxFileSizeMBnumber (optional)the cap the estimate warns against (amber + Fit to cap)
notesstring (optional)shown in the detail pane
video.codeclibx264 | libx265 | h264_videotoolbox | hevc_videotoolbox | prores_ksVT lanes are "fast drafts" — excluded from Verify
video.scaleShortEdgeTonumber (optional)lanczos downscale, aspect preserved, even dims, never upscales; absent = native
video.fps30 | 60the 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 / levelstring (optional)e.g. "high" / "4.2"
video.gopSecondsnumber (optional)keyframe interval (-g = fps × gop)
video.bFramesnumber (optional)-bf
video.entropy"cabac" | "cavlc" (optional)x264 only
video.tenBitboolean (optional)x265 main10 (yuv420p10le)
video.faststartboolean+faststart moov-at-front for web playback
video.colourTagsbooleanbt709 tags AND the conversion at the same scale filter — tags never lie about pixels
audio.codec{aacKbps} OR {pcmBits: 16|24}PCM requires the .mov (ProRes) container
audio.loudnessTargetnumber (optional)integrated LUFS, gain-only (−14 social · −24 broadcast); warn-never-limit on true peak

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, "bufsizeKbps": 12000 },
    "profile": "high",
    "level": "4.2",
    "gopSeconds": 2,
    "faststart": true,
    "colourTags": true
  },
  "audio": { "codec": { "aacKbps": 128 }, "loudnessTarget": -14 }
}

The four flows

  1. 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.

  2. 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>
  3. 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": { "aacKbps": 128 } } }
    EOF
    pnpm kookaburra:run --action export --project showcase-tour --aspect 16:9 --encode-json /tmp/spec.json

    Note: --encode-json does NOT auto-measure loudness (there's no target field on a spec) — set audio.loudnessGainDb yourself if you need gain.

  4. Create/edit a preset for the app — write/edit the JSON under ~/Kookaburra Cut/export-presets/; the modal lists it under Your presets on next open (no restart needed — the list reloads per open). Bundled lineup changes are code changes: add the JSON to src/export/presets/, import it in presetRegistry.ts, and extend the LINEUP pin in presetSchema.test.ts.

Stills (PDF and PNG zip)

Stills are not export presets and carry no EncodeSpec: codec, bitrate, fps and loudness do not apply, and --preset, --encode-json and --codec are ignored. A stills export is a PDF handout or a zip of numbered PNGs, one page per still, captured through the deterministic export path at the native format and downscaled to a size chip. The modal's pinned Stills row (after Custom…) is not a preset row either, though it is remembered as the last choice like one.

pnpm kookaburra:run --action stills --project <p> --stills pdf|png --size 4k|1080p|720p
pnpm kookaburra:run --action stillsverify --project <p> --stills png   # two passes, compares page RGBA
  • --stills defaults to pdf and --size to 1080p (short edge 2160 / 1080 / 720, never upscaled); both exit 2 with any other action. The aspect defaults to 16:9.
  • Autoruns write reproducibly into the run dir; the result's pagesHash is the baseline (a PDF's file hash is advisory). App exports follow the video's destination rules as <project>-<aspect>.pdf or .zip, so they never collide with video names.
  • Which frames become pages is scene data (the sidecar stills block and "still": true camera keys), owned by kookaburra-scene-authoring; the contract is docs/stills.md.

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.