editing-gameplay-montages skill

---
name: editing-gameplay-montages
description: Edit gameplay clips (Valorant, CS2 or any shooter) into a music-synced highlight montage, frag movie, velocity edit or TikTok/Reels/Shorts "edit" with beat sync, slow motion, speed ramps, kill zooms, transitions, lyric words and a cover image; also copy the editing of a reference video ("com a mesma edição desse vídeo"), or fix a rendered edit that stutters ("travado", "quedas de fps"), has choppy slow motion or kills off the beat. Portuguese - "edita um vídeo", "faz um montage", "highlight", "edit pro TikTok", "faz uma capa". Not for plain trimming, joining or converting clips (use ffmpeg).
---

# Editing gameplay montages

A music-synced gameplay edit rendered by a custom Python pipeline. ffmpeg only decodes and encodes; time remapping, motion blur,
camera moves, transitions, text, colour and sound are computed in Python from one file, `timeline.py`, written in beats of the music.

**Core principle: you cannot watch or hear the video, so nothing is done by feel.** Frames are addressed by index, beats are measured
on the waveform, each kill is pinned to its muzzle-flash frame, and every render is judged by numbers and by images you read. Every
shortcut around this produced a version the user sent back (pitfalls.md).

The bundled scripts are measured, not assumed (on synthetic projects with sample-exact truth: every picture event on its exact frame,
every gunshot within 0.2 ms, the delivered sound within 0.1 ms of the song; verification.md). Copy them into the project and edit
`timeline.py`; do not rewrite the pipeline from memory.

## The rules that are never broken

1. **Every event on a MEASURED hit.** A kill, a cut, a bump, a boom, a riser end and a word sit on the attack of a drum hit
   (`beat_hits.py` is the one attack definition; `music_hits.py` writes `hits.json`) or a sung onset, converted with
   `hit(t) = (t - BEAT0) / PER - M0` to 9 decimals. A grid line only where the music has no hit. Never the grid time of a hit.
2. **One exact output frame per picture event:** `vis(beat, lead)` = the frame nearest the moment, then `lead` whole frames earlier.
   Cuts use `CUT_LEAD`, shots, accents, flash-ins and words `HIT_LEAD`; default 1 frame, with a reference its measured lead. The
   muzzle flash is whole on that frame and absent on the one before. No `ceil`, no tolerance.
3. **The enemy is SEEN before he dies:** a take's cut is SHOWN 12 to 16 whole frames (`lead_frames`, default 14) before its first shot,
   at real time up to it. Never a kill 4 frames after a cut ("tem kill que nem aparece").
4. **The enemy visibly DIES inside the take:** the take runs until the body is down (`upto`, measured per kill with `deathstrip.py`),
   slow motion only after that frame; the next cut never comes earlier.
5. **No take without a kill**, and no enemy of a few pixels; the kill feed row confirms each kill.
6. **No standing zoom:** never a crop or zoom that enlarges the gameplay for a whole shot. Only short accents that ease in and out,
   capped (`kill_zoom` ≤ 1.5).
7. **Nothing plays faster than real time** unless the user asks for velocity: `MAX_SPEED = 1.0`, which `draft_ref_timeline.py`
   writes and `preflight.py` enforces. In the house style (only on request) state the choice explicitly: `MAX_SPEED = None` (its
   blur-in squeezes to 1.6x) or `1.0` and a calmer blur-in; a timeline that omits it is refused at delivery (`no-ceiling`).
8. **Words:** centred in the exact middle, caps 21 / 19 % of the frame height (226 / 202 px at 1080p; vertical 0.60 of that), widest
   word 70 % of the width, translucent, and a word steps back from the shot until the body is down (`textfx` `duck_death`).
9. **Every kill is the player's**, visible at the aim, and its K is the shot that killed, re-measured on the pictures (`kverify.py`).
   The same play never twice (a DVR and its trim are the same footage); the best kills first (`kill_rank.py --check` clean).
10. **The ending only darkens** (no zoom on the ace); no label, subtitle or watermark.
11. **Output is 1080x1920 or 1920x1080 at 60 fps**, never 4K or an upscale. The whole game screen shows in both frames: vertical puts
    the 16:9 picture in a window over a blurred backdrop of the same footage, never a crop that hides the minimap or kill feed.
12. **Never waive a sync code and never work around the gate** (`av-offset`, `av-drift`, `frame-count`, `cut-frame`, `pts-gap`,
    `timeline-old`, `check-failed`). Fix the cause and render again.