AGENT SKILL

cut-spec

Use before every set_cuts call. How a cut spec is built - removals, pause trimming, bleeps, blur boxes, zooms and cutaways - in source seconds, with media named by assetId only.

License 许可
Apache-2.0
最近更新
2026-11-06
Stars
★ 1
Forks
0

01 前言 Front Matter

name
cut-spec
description
Use before every set_cuts call. How a cut spec is built - removals, pause trimming, bleeps, blur boxes, zooms and cutaways - in source seconds, with media named by assetId only.

03 SKILL.md 正文

<!-- Created by The Angelo Umali. -->

Cut spec

A cut spec describes the full edit as changes to one joined source. set_cuts replaces the whole spec, so always send every field you want to keep. To change part of a stored spec, start from read_spec (kind: "cuts") and send it back with only that part changed.

Shape

  • schemaVersion: 1, sourceAssetId (the joined source from ingest), durationS, and fps as a rational ({ num: 30000, den: 1001 }, never 29.97: frame identity depends on it).
  • removals: spans { at, end, reason } in source seconds, end after at. Media is named by assetId only; a spec with a path in it is rejected.
  • A removal that comes from propose_cuts carries fromCandidate with the candidate id. Only ids the user approved pass; never reuse a rejected one.
  • pin: true keeps a removal exactly where you put it. Without it the engine snaps each edge up to 0.15 s to the quietest point nearby, which is almost always what you want.

Pauses

  • Prefer trimPauses over hand-written pause removals: { thresholdDb, minS, keepS, exclude }. A start point is thresholdDb: -35, minS: 0.6, keepS: 0.15.
  • Put deliberate beats (after a punchline, before a reveal) in exclude.
  • set_cuts reports keptS before pause trimming; the rendered edit will be a little shorter.

Other fields

  • bleeps: swears to mask, { at, end, x, y }. Place them from the words of an isolated window around the swear, not from long-form transcript times, which drift by about half a second.
  • blurBoxes: on the 1080×1920 grid, inside the frame. Blur other people's private details (their faces in photos, names, addresses, phone numbers, emails). Do not blur the creator's own family or home unless the user asks, and then exactly as asked. A blur box sits still on the frame, so its span must not overlap a zooms window: the picture would slide under it.
  • zooms: a preset (snap, push, reveal, through-out, through-in, portal, lean) over a span. lean is a restrained 5 % push for where the face is already close. Jump cuts already get an alternating punch-in; add zooms for emphasis only. Every preset is animated: when get_capabilities reports zoomExpr: false, leave zooms empty and let the jump-cut punch-ins carry the emphasis.
  • cutaways: a title card { title, sub?, style? } over a span, for a chapter change.
  • faceCamRanges and matteRanges: spans where the speaker's face is the subject. A house-theme cue with depth: "behind" draws under the person only inside a matteRanges window, so give every behind cue one that covers it. Learning kinds have no depth: their text always stays in front.
  • focus: rack focus { at, end, amount } (1–40 px of blur on the room behind him) where he turns inward. Each focus window is matted for you; no matteRanges needed.
  • grade: "house" (the default) or "learning" for the v2 Live Motion look.
  • follow: "speaker" frames every kept second without a reframes window on whoever is speaking (learning theme).
  • blurFaces: the user's answer to "are other people's faces blurred?": "others" blurs every face but the creator's, a guest's even while they speak (the camera still follows them), following every reframe and zoom, and the covers too; "none" leaves them. Ask before the first render: a learning edit of footage with anyone besides the creator does not render without it.
  • places: [{ name, lon, lat }] for places the footage visits that its own GPS cannot prove (ask the user); each needs a routeMap pin. Never home.
  • reframes: for a square or landscape source, { at, end, cx, cy?, scale? } windows that crop a 9:16 slice of the picture (cx/cy are shares of the picture band frame_faces reports). Cover every kept span, move only on a cut.
  • music: an original bed under his voice, { bpm?, sections: [{ at, kind, energy? }] } with kind one of cold, intro, chapter and outro; sections start at 0 and are in source seconds.

Before you call set_cuts

  • Every span sits inside 0 … durationS, and removals do not cut a word in half (check read_transcript with format: "words" around each edge).
  • The opening line is the hook you agreed with the user.
  • Then call validate_spec and fix whatever it reports.

Hands to next: a stored CutSpec version → style-rules, then cues (the cue sheet) and captions.

04 同仓库更多 Skills