Film edit
The filmmaker cuts; the agent holds the timeline. This skill turns approved clips into a finished, honestly labelled film. The work is plain ffmpeg: tested commands are in ffmpeg-recipes.md, and the footage log, edit decision list, production log, delivery checklist, credits template and an FCPXML skeleton are in edit-sheets.md.
Rules for every step
- The filmmaker conducts; the agent plays. The agent assembles, measures, proposes and renders. What to keep, cut, hold, swap or reorder is the user's call. When a choice is open (which take, crop left or right, speed up or trim), offer the options with what each costs.
- The +1 is intent, not taste. If the cut departs from what the user said they wanted (a note that could not be applied exactly, a beat that lost its reaction), flag it once, let the user decide, and log the decision. Your preference is not a departure.
- Never overwrite, never delete. Every pass writes a new, numbered file (
cut-v4.mp4); sources are read-only. Use ffmpeg's-n(refuse to overwrite), not-y, unless the user asked for that exact file to be replaced. Old cuts, weak takes and replaced clips go in asupersededfolder. - Ask before spending and before publishing. Before any paid step (cloud transcription, a generative re-render, a paid upscaler), state the tool, how many and the estimated cost, and wait for a yes. A re-render after a rejected result is new spend: ask again. Silence is not a yes.
- Rights and consent. Footage, music and voices that are not the user's need rights; a real person's likeness or voice needs their consent. Downloading someone else's video needs the owner's permission or a licence; a terms-of-service warning is not permission, so wait for the user's answer.
- Keep a production log: each version, the notes applied, the user's decisions, and for each paid step the tool, job ID and cost. Log a generated result as kept only once the user approves it.
Where this skill ends
- Titles, lower thirds, kinetic type, animated or per-word captions, arrows and maps drawn in code: motion-graphics. This skill lays their rendered output over the clean cut.
- Narration, dialogue, music, effects, the mix and loudness: film-sound. This skill lays the delivered mix under the locked picture.
- Shots, stills and clips: cinematic-shots, including a shot missing from the coverage.
- Not covered yet: color grading. Leave the color as generated unless the user asks.
1. Probe and log the footage before cutting
Probe before planning: duration, frame rate (r_frame_rate differing from avg_frame_rate means a variable rate), size, pixel shape and format, audio streams. Generated clips often differ from shot to shot, and some have no sound.
Log each clip as an observer, not a director: shot number, file, what is in frame, usable in and out, where complete lines and actions start and end, the moment that carries the beat, problems seen. Keep what you saw apart from what it might mean; write "unclear" rather than invent a story. Measurements are candidates, not verdicts:
- A contact sheet of several frames per clip, labelled with times. One frame hides a ghost object or a face that drifts.
- Scene-change candidates. Motion, flashes and dissolves also score high; check each at normal speed.
- Silence windows, where cuts can land. A gap in a transcript is not proof of silence.
- Dropped frames: timestamp gaps longer than one and a half frames.
- Speech: for a long recording, read the transcript first, then pull frames only where the picture matters.
2. Assemble in shot-table order
The first cut is mechanical: the approved clips in shot-table order, each at its logged in and out. It is a draft for the user to watch.
- Normalize every clip to one format: size, square pixels, frame rate, pixel format, audio rate and channels. Give a clip with no sound a silent track. When the aspect differs, fit (bars) or fill (crop) is the user's choice.
- Join by stream copy when every piece matches exactly, otherwise with the concat filter (one re-encode). Compare video and audio durations after joining.
- Re-encode as few times as possible: high-quality intermediates, one delivery encode at the end.
- Keep each clip's own sound (keep the video model's ambient track; levelling it is film-sound's work).
- Number the version, log it, make a contact sheet.
3. Cut notes become an edit decision list
The user watches and types notes in their own words: trim, swap, hold, cut, move. Each note becomes a row of an edit decision list (EDL): note number, the user's words verbatim, shot, source in and out, action, reason, status. Times stay in source seconds; anything on the output timeline (narration, captions, markers) is re-timed after every recut.
- Ask when a note is ambiguous ("tighten the middle"): offer two concrete readings with timecodes.
- Give each row a reason: the beat it serves, why it enters and leaves there. Keep the moment that makes the beat land, not the whole event.
- List the must-keep moments (a question and its answer, a reaction, a payoff); after any automatic boundary change, check they are complete and in order.
- For dialogue, show the whole transcript numbered with times and ask what to remove, before any graphics are timed to the cut. When a sentence is said twice, the later take is often the correction; ask before dropping either.
- Apply, render a new version, log notes and decisions. Repeat until the user says the cut is theirs.
4. Trim and pacing
Cut on sentence ends and pauses. An in or out point belongs in a measured silence, at the head of the source, or at a continuous join within one take. If a boundary still falls inside speech, move it or drop the whole sentence; never clip a word to hit a length. Trim dead air from the middle of a pause so both sides keep a breath. Give non-continuous joins a very short audio fade so they do not click. Ask before removing a deliberately slow speaker's pauses.
Avoid flash frames: one- or two-frame fragments left when a boundary lands beside a hard cut in the source. Move the boundary or drop the fragment; do not stretch a short shot with a freeze or slowdown, or hide a bad cut under a transition.
Length targets. "Make it 60 seconds" by speed and by trim are different answers (speed changes every movement and voice; trimming loses material). Show both.
Fitting picture to narration (the picture side): when a narrated line runs longer than its shot, slow that clip by at most 10% and let the rest spill into the next shot. On one film, 7 of 25 shots needed it. Keep the frame rate constant after any speed change, so the clip still matches the others for joining.
Cutting to the beat. Get the beat times of the approved music as a list of seconds (from film-sound, or a beat tracker run on the track). Propose the strongest moment of each clip, snap cuts to the nearest beat, and show a numbered shot sheet before assembling. Where a beat and a sentence end disagree, show both and let the user choose.
5. Effects fixes on finished clips
Work in cost order and keep the original beside every fix.
-
Free fixes that keep the original pixels: reframe, speed, hold a frame, fill dropped frames by interpolation, light denoise.
-
Overlays never go into generated footage. Arrows, routes, labels and grids are drawn by motion-graphics over the clean clip. If a generated clip has one baked in, regenerate it clean rather than paint over it.
-
A generative re-render is a new shot, not a fix. Reference-video models use the original as a guide for motion and look, not as locked pixels, so faces, props and camera moves can drift. If the user wants one:
- Read frames across the whole clip; write down what must stay the same (identity, gestures, camera move, framing, light, held objects) and the change, timed to its moment.
- Where the tool allows, change one still first and get it approved before paying for motion.
- State model, count and estimated cost; wait for a yes.
- Check the result against the source: length, speech to the end, the mouth moving through the last words, the face at start, middle, joins and end, the approved change still there. Report a miss as a miss and offer one repair; do not escalate on your own.
What a model preserves is something to test on one shot first.
-
Label each shot real or generated as you go; the disclosure needs it.
6. Captions and subtitles
Make captions after picture lock and after any reframe; captions made before a crop can land off-frame.
- The words. If the narration was written first, the script is the caption text: align it to the audio instead of transcribing. Otherwise transcribe; a local engine keeps the media on the machine, a cloud service uploads it (ask first). Recognition timestamps are often coarse windows, not word timings; align when timing matters.
- Correct by reading. Recognizers mishear dialect, names and specialist words. Never add a word that was not said, and never shorten or paraphrase a caption to fit: use a smaller size or another line, or ask. Words respelled so a synthetic voice says them right keep their real spelling in the captions.
- One master, many formats. Keep the richest version (word timings, speakers) and convert from it: SRT for text and time, VTT for web players, ASS for styling.
- Translate keeping timing: the same number of cues in the same order, with the same times and speaker labels; no empty cues; sound tags kept; no dashes, parentheses or brackets the source lacks. Confirm the source language if unclear. Captions that highlight each word as spoken must be in the audio's language; for another language, use a plain translated line.
- Burn or mux. Burned captions are part of the picture and cannot be switched off, so burn last, after upscaling; it needs an ffmpeg built with libass. Muxed subtitles stay switchable: one track per language, tagged with its language. Platforms take one subtitle file per language.
- Placement: keep captions off faces and clear of the platform's buttons on vertical video; check its current safe areas.
7. Upscale last, per clip
Upscale only after the cut is locked, each clip on its own rather than the joined film, so cuts do not smear. Rebuild the cut from the upscaled clips with the same EDL, then add captions and graphics so text stays sharp. AI upscaling suits photographic footage; on one film series it degraded flat vector art. Ask before any paid upscaler.
8. The final viewing
Check the file you will deliver, not an earlier version, a proxy or a captionless master.
- Play it once at normal speed without stopping to fix; note what you notice.
- Play each join, half a second to a second either side, at normal speed.
- Listen once without the picture.
- Watch the opening, the key moment and the ending again.
- On a revision, confirm each requested change happened and nothing else moved.
- Then probe the numbers, run a decode pass, check subtitle tracks, and make a contact sheet of every shot.
Sheets and automatic checks only point at problems; playback decides. If you cannot view images or play media, say so instead of claiming a check. Fix a problem where it lives (the cut, the sound, the words), not with packaging. Report in the five-line form in edit-sheets.
9. Delivery files, disclosure and credits
- Ask where it is going. The destination decides aspect, length, codec and loudness. Read its current spec and note the date.
- A master, then one file per destination encoded from it and probed; with them, subtitle files per language, a transcript, credits and disclosure, the rights record.
- Disclosure and credits: what the script was adapted from, which picture and sound are AI-generated and which are real, and credit for footage, music and voices with their rights. The agent drafts this with blanks; the user edits and signs it. Set a platform's synthetic-media flag truthfully.
- Rights record: every outside asset with source and licence; every generated asset with model and job ID.
10. Handing the timeline to an editor (FCPXML)
When the user or their editor will finish in an editing program, hand over a timeline as well as a flattened file.
- Export the EDL as FCPXML (ask which format the editor's program imports) plus a CSV of it. Point at the original clips by absolute path; list missing media.
- Time is frames over frame rate (
72/24s), never a rounded decimal.offsetis the position on the timeline,startthe in-point inside the source,durationthe length. Markers are children of the clip they mark and can carry the cut notes. Thespineis the main storyline; connected clips sit on lanes, positive above, negative below. A.fcpxmldbundle is a folder with sidecar data; keep it whole. - Never edit the editor's file in place: write a new version and list what changed.
- Writing the file is not importing it. Import a small test first; the import is the user's step.
11. Upload: ask first, private by default
- The default is a package the user uploads: file, captions, title, description, tags, cover, disclosure.
- Upload only on the user's request, per platform, as private or a draft. Public or scheduled release needs the user to name the platform, file and time. "Post it everywhere" is not that approval: list each platform's planned action (file, title, visibility, time) and confirm.
- One platform at a time. At a login screen, verification code, captcha or security warning, stop and hand over. Never type passwords or codes, or read or repeat credentials.
- Afterwards, read back title, description start, captions, visibility and the synthetic-media setting. Success is a video ID plus a processing status; a failed login is not a publish. Do not start a second upload to debug the first.
- Never change speed, add noise or crop to get past copyright matching.
Tools as of 2026-11-17: The author's first two films were assembled with ffmpeg build scripts, two later design films with the author's own Python film builder. On the author's Mac, Homebrew's
ffmpeg8.1.2 lacks libass and freetype (nosubtitles,assordrawtext); the keg-onlyffmpeg@66.1.6 (/opt/homebrew/opt/ffmpeg@6/bin) has them and was used to test those recipes. Upscaling was Topaz Video AI'stvai_upfilter in Topaz's own ffmpeg, piped asyuv4mpegpipeinto Homebrew ffmpeg for H.264; one test took a 3 s 1928x1072 clip to 3856x2144 in 19 s, and the author dropped 4K for later films. Sources name these engines: Whisper, faster-whisper, Parakeet, SenseVoice (local transcription); Gemini, ElevenLabs Scribe, MiMo (cloud transcription, media uploaded); Seedance and Kling reference video via Pika's MCP server (re-renders); fcp-mcp-server (FCPXML). Private YouTube upload: the YouTube Data API or YouTube Studio; descriptions cannot contain angle brackets.