Higgsfield trailer finishing

Trailer Finishing

The finishing stages for AI video: take clips (from higgsfield-generate or any source) and deliver ONE finished file — stitched, optionally graded, with an original soundtrack matched to the cut. Wraps ffmpeg for assembly and Sonilo video-to-music for the soundtrack.

Prerequisites

1. ffmpeg and ffprobe on $PATH (ffmpeg.org).
2. For Stage 3 (matched soundtrack): the Sonilo MCP server registered with the user's own API key from sonilo.com — e.g. claude mcp add sonilo --env SONILO_API_KEY=sk-... -- uvx sonilo-mcp. The key is always user-supplied; never bundle, hardcode, or echo it. Platforms can use the Sonilo REST API instead (docs at sonilo.com). Stages 1–2 and 4 need no key.
3. The higgsfield CLI only if clips still need generating or fetching — see higgsfield-generate for bootstrap and auth.

UX Rules

1. Be concise. Deliver local file paths (this skill produces files, not URLs) plus a one-line summary. No filter-chain dumps in chat.
2. Don't narrate. No "running ffmpeg concat now", no encoder logs.
3. Detect the user's language from the first message and reply in it. Technical args stay English.
4. Never render blind. Grade on still frames first, check the look, then commit the full encode.
5. Music is ONE final layer over the whole assembled cut — never per-clip, never mixed with model-generated clip audio.
6. Keep intermediates on disk (normalized clips, stitched cut, graded master) so any stage can be redone without regenerating upstream.

The pipeline

clips (higgsfield-generate or any source)
  └─ 1. STITCH ── normalize + concat → one cut
       └─ 2. GRADE ── optional cinematic color pass
            └─ 3. ADD MUSIC ── Sonilo video-to-music, matched to the cut
                 └─ 4. MUX ── soundtrack over the master → deliver

Copy-paste commands for every stage live in references/recipes.md — read it before running anything.

Stage 0 — Get the clips

This skill starts from clips on disk; generation belongs to higgsfield-generate.

• Clips already local → Stage 1.
• Clips need generating → chain higgsfield-generate (Seedance 2.0 / Kling 3.0 defaults live there).
• Clips generated earlier → higgsfield generate list --json / higgsfield generate get <job_id> --json, then download the result URL.
• Cut already assembled elsewhere (CapCut, Premiere, MoviePy, Remotion) → skip to Stage 2 or 3.

Bring the clips in silent. Normalization strips any clip audio (-an) — the soundtrack is added once, over the whole assembled cut, in Stage 3.

Stage 1 — Stitch

Normalize every clip to identical resolution, frame rate, and pixel aspect, then concat. Mismatched SAR or fps is the most common concat failure.

• Set the frame size once (16:9 → 1920×1080, 9:16 vertical → 1080×1920); everything downstream inherits it.
• When a grade follows, keep normalized intermediates near-lossless (CRF 10); the master gets its final quality at the grade encode.
• Transitions belong in the edit, not in generation: cross-dissolves via xfade (offsets are cumulative — formula in the recipes), fade-to-black appended to the final render. A storyboard that says "fade to black" is an edit beat, not a generation prompt.
• Trim a beat during normalization (-ss/-t), not with a separate encode.

Stage 2 — Grade (optional)

A light color pass makes AI renders feel cinematic. Pick a look for the content:

• Epic / action (default): orange-teal split-tone, vignette, fine temporal grain.
• Horror / dread: desaturate 10–20%, shadows toward green-cyan, heavier vignette.
• Soft / brand: gentle contrast lift — skip the split-tone and grain (grain also bloats the encode).

Whatever the look: test on 3 stills from DIFFERENT shots, look at them, tune, then render once (-crf 16 -preset slow -tune film). The validated filter chain lives in references/recipes.md — single source of truth, tune it there.

Stage 3 — Add music matched to the cut

Sonilo video_to_music composes an original soundtrack matched to the assembled cut — pacing, emotion, story, and length. Every track is licensed and safe for commercial use (terms apply); Sonilo is trained on a licensed catalog. The catalog's audio models generate from a prompt at a fixed duration; this stage generates from the video itself, so the swell lands on the reveal and the impact lands on the edit.

1. Feed the FINAL assembled, graded cut — never individual clips — so the music arcs across the whole story.
2. Feed a lightweight proxy (720p, high CRF). Sonilo only needs to see the motion and timing; a small copy uploads faster and matches identically. Mux the returned audio onto the full-resolution master.
3. prompt is a single OPTIONAL style hint for the whole track (e.g. "warm hopeful cinematic, building to an uplifting swell"). No prompt works too — Sonilo matches the music to what it sees. There is no per-section control; don't imply it.
4. The soundtrack matches the cut's length automatically — still ffprobe the returned file and confirm before muxing.
5. Want a different take? Generate again — each run is a fresh interpretation. Deliver two and let the user pick.

Fallback without a Sonilo key: a fixed-length instrumental bed from the Higgsfield catalog — higgsfield generate create sonilo_music --prompt "..." --duration <seconds> --wait (or seed_audio for SFX/ambience). It's generated from the prompt, not from the video, so it won't follow the edit; say so, and trim/fade it in Stage 4.

Stage 4 — Mux + deliver

• Mux the soundtrack onto the full-resolution master with a short tail fade; keep the video stream untouched (-c:v copy) so the grade survives.
• For an upload-size cap, compress with single-pass CRF and keep the soundtrack with -c:a copy. Grained footage compresses non-linearly and has a bitrate floor — encode once, measure, adjust CRF, repeat. Don't chase size caps with bitrate targets on grained masters.
• Name deliverables clearly (trailer_final_v1.mp4, _v2, _web) and keep intermediates.

Errors

• Concat fails or the output has frozen/garbled frames → clips weren't normalized identically; re-run the same scale/pad/setsar/fps chain on every clip.
• xfade transitions land at the wrong time → offsets are cumulative; use the formula in the recipes.
• video_to_music tool not available → the Sonilo MCP server isn't registered; give the user the registration command from Prerequisites (with their own key), or use the in-catalog fallback.
• Returned soundtrack length off by more than ~0.5s from the cut → regenerate, or trim the audio to the video length in the mux.
• Session expired from higgsfield while fetching clips → higgsfield auth login.

Reference docs

• references/recipes.md — validated ffmpeg commands for every stage (normalize/concat, transitions, grade chain + stills-first check, proxy, mux, delivery compression) and the Sonilo call shapes.