git:20261013.282e74a to git:20261015.07749c7

- description: Pick the effect that fits the moment and genre after reading what the cut already uses, and make it with BashCut's native tools — punch-in, Ken Burns, keyframe zoom/pan, speed ramps, slow motion, freeze, reverse, transitions (dissolve, whip, zoom, wipe…), animated titles, stickers, word-by-word captions with matching SFX, and reframes — or say when an effect is not possible yet. Use when a cut feels flat or repetitive, or the user asks "hiệu ứng", "effect", "chuyển cảnh", "transition", "speed ramp", "freeze", "chữ nhảy", "làm giống CapCut", "zoom vào màn hình", "tua nhanh", "cắt khung dọc", "reframe".

- Reply in the user's language. Decide **when** first; most cuts should stay hard cuts. With a `[Scope]` (Send to

- Agent), work only on those items (`bc:edit-workflow`).

-

- Numbers here are ranges with where they come from (T08 effects, T07 pacing, T19 reframing: the kit's research

- notes; the names inside are the editors' kits they were seen in). They are starting points: a measured reference

- (`bc:style-study`) or the user's taste wins. Look before fixing: measure → choose → act → measure again.

- ```sh

- bashcut review measure # job: picture motion per shot (needed for motion in review shots)

- bashcut review shots --summary # per shot: motion, cameraMove (perSecond, ease), speed, described size/move, and the cut

- # into it: kind, framingBefore/After, sameFraming; transitionIn {kind, duration, easing}; shares

- ```

-

- Count kinds and runs yourself from each shot's `cut.kind`. Look for runs of one transition kind, neighbouring cuts with `sameFraming`, every shot with the same

- `cameraMove` (one failure seen: all 12 shots a push-in, vox-director; T08 §2), one ease on most moves, and long

- stretches with no motion. For each, decide **motif or mistake**; a motif is fine when it is a choice. Other kits

- warn on: the same transition on two consecutive cuts, one kind used more than 2× in a film under 60 s (3 when

- `variety_audit`; T08 §2). Treat them as prompts to look, not rules.

- documentary or cinematic work (saas-motion-kit, openmontage, hyperframes; T08 §3). Everything else is a hard cut

- on a sentence, a beat or an action. Sources disagree on hard cuts: speech-led, documentary and cinematic edits

- keep most cuts hard; motion-graphic and short-form ads rotate flavours (T08 §3).

- - **Choose by what the cut means**, never by rotating through kinds by shot number (student-kit; T08 §4): new place

- → whip, shutter or cover-the-lens; same place with a time skip → blink, dissolve or a jump cut; product or dish

- reveal → speed ramp, freeze or zoom-hit into it. A dissolve says time passed; between takes of one sentence use a

- snap punch-in instead (ghost-editor; T08 §3).

- - **Hits on the whole frame are rare by default** (flash, blink, whole-frame zoom punch, exposure pop): each one is

- a slam. `bashcut review sync --events impacts` lists them with their beat and spacing. One promo study kept about

- 2–4 per 30–60 s on the strongest beats and moved only an element on the other beats; event and MV edits use far

- more. Choose for the genre and look at `perMinute` and `minSpacingBeats` before adding another.

- - **Every visible move gets a matching sound**, sized to it (`bc:audio-mix`). One example: on a punchline, cutting

- all music and SFX for 1–2 s worked.

- - Cinematic style: hard cuts, no whoosh on cuts, the colour look and serif captions carry the feel.

- | Review / ads | freeze + label, price as a keyword sticker, reverse-into-hand hook |

- | Talking head | jump cuts with punch-in, keyword stickers, few transitions |

- | Event / MV | beat cuts, flash, blink, speed ramps |

- | Size change at a cut | 1.15–1.3, capped by headroom | vlog talking-head recipe, kit beat-cut; see `bc:beat-cut` |

- - The ceiling is resolution, not taste: read `scale.maxZoomNative` and `pixelRatio` per clip in `timeline get` or

- `review shots`; past 1 output pixel per source pixel it upscales, so look at `ui frame F` before keeping it.

- - Two moves in a row read as a glitch: merge them into one gesture and front-load the travel (student-kit). Ease

- out on entrances, ease in on exits, linear only for a constant drift (T08 §3).

- - After applying, `review shots` shows each `cameraMove` with `perSecond`: check it against the range you chose.

- **Speed and time.** Speed changes break lip sync: use them on b-roll and action, not on talking shots.

- - Real slow motion needs 50/60/120 fps sources (`media analysis --media ID` tech facts); slowing 30 fps footage

- below ~0.5× stutters (our edits; T08 §3).

- - A clip a few frames short: slow it slightly instead of freezing on its last frame (vox-director stretches by

- ~1.02–1.1; T08 §3).

- - Fast-forward: 1.5–2× when narrated over, 4–20× for silent waiting (digitalsamba, vlog tutorial; T19 §3).

- `setSpeed` takes up to 16×. One example: a 65 s typing stretch read clearly at 18× (3.6 s) with no presenter

- or captions and one label saying what happens (the action, never the speed or effect name).

- **Graphic moves and transitions.** Durations in seconds: frames change meaning with fps (T08 §3).

- | Dissolve | 0.3–1.0 s; bookend fades 0.5–1.0 s | openmontage |

- | Blink, shutter, zoom, spin, wipe | quick ~0.2–0.5 s, standard ~0.7–1.5 s | digitalsamba (two tables in one repo disagree) |

- | Swing (next card turns in about its left edge) | ~0.3 s between full-frame cards of an explainer; never between footage shots | Reelcrew study (30 videos, 2026-10-07) |

- | Glitch (RGB split), halftone (print dots) | glitch 0.2–0.4 s, halftone 0.4–0.8 s; hype, showreel and comic edits only, about every 2.7 s at most | Reelcrew study |

- | Text or sticker entrance / exit | entrance 0.2–0.6 s, exit shorter | talkcraft |

- | Impact (slam, flash, hit) | 0.10–0.25 s after its target is fully visible | assafkip |

- `upsertTransition` takes `duration` in frames: frames = seconds × the project fps (`project get`).

- 1. **Facts**: `timeline get` / `review shots` `scale` (`fit`, `frameCoverage`, `maxZoomNative`); `review layout

- --frame F` lists the pictures on screen at F with their scale and coverage.

- 2. **Look** at what matters at the start, middle, end and action peaks of each shot (nateherkai; T19 §2):

- `media frame --media ID --at S` (source size, so you can read a rectangle in source pixels), `ui frame F` for

- the edit, `ui frames --compare source --items CLIP` for source next to edit. Faces and people come from

- `bashcut media subjects --media ID --from S --to S2` (job): `box` `[x, y, w, h]` as shares of the source picture

- from the top left, so multiply by the media's width and height for a rectangle in source pixels; check it on

- `media frame` at that `frame` (boxes are stored per file once measured). `review layout` `faceOverlap` gives

- how much of a face each text covers, null when no boxes are stored (unknown, not "no face"); a limit in

- `review.maxFaceOverlap` turns it into a `text-face` issue. `media describe` subjects are your own tags.

- 3. **One call for a face subject**: `bashcut clip reframe ITEM --mode locked|cut|follow --base-rev last` (a job)

- measures missing boxes, crops so the face sits at `--anchor`, and fits instead (or `--fallback refuse`) below

- `--gate`; it returns `coverage`, the framings and a `preview` grid: look at the grid, that is your check. Set

- `--gate` (0.85–0.95), `--drift` (0.1–0.2) and `--min-hold` (1–2 s) for the shot: locked for a talking head,

- cut when the presenter changes place, follow only for real movement. For anything that is not a face, step 4.

- 5. **Fall back to fit** when it does not fit (two people far apart, a wide landscape, a sign): the clip's `fill`

- false (`setProperties`) or `project format --clips fit`. Fill the bars with `clip backdrop ITEM --kind blur`

- (or `--kind color`); a blurred backdrop suits screens, slides and photos, not footage with a subject (nateherkai; T19 §3). Order: fit → a fixed crop at a position you checked → keep the original

- shape. A centre crop without a frame check is the anti-pattern (openmontage; T19 §4).

- - `bashcut library list --kind effect-preset` (also `transition-preset`, `sticker`). Built-ins: `ken-burns-in`,

- `ken-burns-out`, `zoom-punch-in`, `punch-in`, `speed-ramp`, `slow-motion`; transitions `soft-dissolve`,

- `quick-whip`, `zoom-punch`; emoji stickers. `library get ID` shows a preset's parameters and ranges: set them

- from sections 3–4, not the defaults.

- - Effect preset: `bashcut library apply ID --item CLIP --set zoom=1.12 --from F --to T --base-rev N` (every step

- in one undo).

- - Transition preset: `bashcut library apply ID --item CLIP --base-rev N` sets kind, duration, easing and its sound

- at the cut beside the clip.

- - Sticker: `bashcut library place ID --at-frame F --position top-right --size 0.25 --base-rev N`.

- - An effect the user liked: `bashcut library save-selection --kind effect-preset --name "Food reveal" --item CLIP`

- (or `transition-preset`, `sticker`). A correction: `library update ID --params '{...}'`, or `--as NEW_ID` for a

- built-in or plugin preset.

- - A sticker or sound the library lacks: `bashcut library search "fire" --kind sticker` (or `library generate`)

- when a plugin provides it; a job, then `library add --from-result JOB:N`.

- | Transition | `{"op":"upsertTransition","id":"t-hook","kind":"whip","from":"A","to":"B","duration":9}` (frames; clips adjacent on one video layer; kinds: dissolve, whip, blink, zoom, spin, shutter, wipe, swing, glitch, halftone; any other name with `motion`: zoom, panX/panY, rotation, opacity, exposure, scaleX, reveal, swing, rgbSplit, halftone) |

- | Speed ramp | `{"op":"setSpeedCurve","item":"ITEM","preset":"hero"}` (montage, hero, bullet, jump-cut, flash-in, flash-out) or `"points":[{"t":0,"speed":1},{"t":0.5,"speed":3},{"t":1,"speed":1}]` |

- | Constant speed | `{"op":"setSpeed","item":"ITEM","speed":2}` (0.1–16; length follows, `"keepDuration":true` keeps it) |

- | Reverse | `clip reverse ITEM` (job) |

- | Freeze frame | select the clip, playhead on the frame, `ui action clip.freeze` |

- | Punch-in / reframe | `setProperties` `{"reframePreset":"custom","transform":{"zoom":Z,"pan":P,"tilt":T}}`, Z from the clip's headroom (`bc:beat-cut`) |

- | Picture in picture, split moment | the second clip on an overlay layer with `transform` zoom below 1 and pan/tilt |

- | Pop text, labels, prices | text templates (`stacked-keyword`, `boxed-keyword`, …), `keyword-sticker`, `place-card` (`bc:captions-text`) |

- | Stickers | `library place ID --position top-right --size 0.25` (image, alpha movie or emoji); animated emoji and brand logos: `fetch_emoji.py`, `fetch_logos.py` in `bc:stock-images` |

- | Fade from/to black | `dissolve` against a black clip, or audio `fadeIn`/`fadeOut` for sound |

- | Ken Burns, slow push-in | `clip motion ITEM --preset zoom-in` (also zoom-out, pan-*), or keyframes at the drift rate above |

- | Animated title or label | `clip motion TEXT_ITEM --preset pop-in` (fade-in-out, slide-up, zoom-punch) |

- | Custom move | `clip motion ITEM --keyframes '{"zoom":[{"frame":0,"value":1},{"frame":45,"value":1.08,"ease":"out"}]}'` (frames from the item's start; eases linear, in, out, inOut, hold) or one key: `clip keyframe ITEM --property pan --value -80 --at-frame F` |

- | Zoom onto a panel of a screen recording | `clip motion ITEM --focus x,y,w,h [--focus-to x,y,w,h] [--ease out]`: the panel's rectangle in the recording's pixels (origin top left, size from `media list`). One panel per sentence; draw the rectangle around the panel only. One example: at zoom 1.9 a 1920 px recording showed 1010 px and a neighbouring window crept in; 2.6 isolated the panel. Confirm with `ui frame` |

- | Presenter box over a screen recording | `setProperties` `{"crop": {"left": 0.2, "right": 0.2, "top": 0.1, "bottom": 0.3, "radius": 0.15}}` on the camera clip (fractions; `radius` 0.5 = circle), then `transform` zoom/pan/tilt to size and place it: 0.25–0.6 of the width, smaller when the screen text is dense, larger when the face carries the story (T19 §3). The visible part keeps its place in the picture: an uneven crop (one example: left 0.28, right 0) left the face box off-centre until pan moved it back by (left − right) / 2 × canvas width × zoom |

- | Word-by-word captions | `captions words --all --style highlight` (karaoke, reveal); see `bc:captions-text` |

-

- ## Not possible yet — say so and offer the alternative

- - Typewriter text, counting numbers, shake, glitch, film grain.

- - Segmentation (text behind a person, cut-outs), motion tracking of objects (faces: `clip reframe`), AI-generated

- transitions.

- When the user needs one of these, note it as a feature request for BashCut (or a plugin action) rather than faking

- it with a pre-rendered file.

- Run `review shots --summary` again: the runs and repeats you meant to break are gone, and the

- ones left are motifs you can name. Render frames just before, inside and after each effect with `ui frame F` (for

- motion: the first, middle and last frame of the item) or one `review window F` across a transition, and read them;

- for a reframe, check that what matters is still in the frame. Ask the user to listen to the matching sound.