Skip to content

Open source CapCut alternative.

TypeScript
5.0 KB
Raw Blame
/**
 * The assistant's Transitions tools — the styled join between two clips and
 * a clip's own entrance/exit — kept beside the panel that gives users the
 * same tiles. The catalog spreads this list into the model's toolset and
 * `aiTools.ts` keys its handlers on `TransitionsToolName`, so the style ids
 * the model can pass are exactly the ones the panel renders and a removed or
 * renamed tool breaks the build until every side catches up.
 */

import { bool, ids, num, obj, str, type AiToolDef } from "@/cut/lib/aiToolDef";
import { ANIM_STYLE_IDS, TRANSITION_STYLE_IDS } from "@/cut/lib/types";
import { BAND_STYLES, FEATHER_STYLES, TRANSITION_BAND_MAX, TRANSITION_FEATHER_MAX } from "@/cut/lib/transitionShape";

export const TRANSITIONS_TOOLS = [
  {
    name: "set_transition",
    description:
      "Set the transition from this clip into the next clip on its track (any video track), in seconds (0 clears it, max 2). 0.5s suits a blend on the picture; the cross dissolve (audiocross) wants about 0.3s, since it is centered on the cut and both clips sound through it. A transition is a blend across the cut — it never moves, trims or overlaps clips, and it plays only while the pair touches. On upper tracks every style blends as an alpha dissolve (the tracks beneath show through). Only valid when a next same-track clip exists. Each edge holds one effect: setting a transition clears the animations adjacent to its joint (and set_animation on that edge replaces the transition). Read the transitions-and-fades skill before styling cuts.",
    inputSchema: obj({
      clipId: str("Video clip id (the clip the transition starts from)"),
      ids: ids("clipId"),
      seconds: num("Transition length in seconds, 0–2 (0 = hard cut)"),
      style: {
        type: "string",
        enum: [...TRANSITION_STYLE_IDS],
        description: "Transition look (default crossfade)",
      },
      feather: num(
        `Softness of the reveal edge for ${FEATHER_STYLES.join(", ")}: a share of the frame the edge crosses, 0..${TRANSITION_FEATHER_MAX} (0 = hard edge, 0.15 = a soft blurred band); other styles ignore it`
      ),
      band: num(
        `A solid white panel running just ahead of the reveal edge of ${BAND_STYLES.join(", ")}, as a share of the frame the edge crosses, 0..${TRANSITION_BAND_MAX} (0 = none): the outgoing shot is wiped first by white, then by the incoming one, and the panel leaves past the far edge. A 0.1s wiperight with band 0.5 is the white-panel slide of a recap montage. Draws a hard edge (overrides feather)`
      ),
    }, ["seconds"]),
  },
  {
    name: "remove_transition",
    description:
      "Delete a transition bar by its own id — the handle for a parked bar, one lining up with no cut or clip edge and playing nothing. editor_state's `transitions` lists every bar and marks the parked ones, and each timeline mutation reports the bars its edit left parked. Use this to clear leftovers after moving or retiming clips; a bar that still plays a cut is better changed with set_transition (0 clears it).",
    inputSchema: obj({
      transitionId: str("Transition bar id, from editor_state `transitions`"),
    }, ["transitionId"]),
  },
  {
    name: "set_transition_hidden",
    description:
      "Hide or show one transition bar by its own id. A hidden bar stays on the transitions row (grayed) and keeps the cut it sits on, so nothing else claims that boundary, but plays nothing — the cut renders hard in the preview and in every export. Use it to try a cut without its blend; remove_transition is for deleting one outright.",
    inputSchema: obj({
      transitionId: str("Transition bar id, from editor_state `transitions`"),
      hidden: bool("true to hide"),
    }, ["transitionId", "hidden"]),
  },
  {
    name: "set_animation",
    description:
      "Animate one clip's own entrance (which:'in') or exit (which:'out'): fade, blur (defocuses as it fades), zoom, pop, or a slide named by its motion direction. style 'none' clears. Track-0 clips take every style; upper-track clips only fade and zoom. Each edge holds one effect, last pick wins: animating an edge a transition owns replaces that transition, and setting a transition clears the animations adjacent to its joint. At an abutting cut the animation plays over the neighbor's held frame; at the timeline's ends and across gaps it plays against black.",
    inputSchema: obj({
      clipId: str("Video clip id"),
      which: { type: "string", enum: ["in", "out"], description: "Entrance or exit" },
      style: {
        type: "string",
        enum: [...ANIM_STYLE_IDS, "none"],
        description:
          "Animation style, or 'none' to clear. Slide names give the motion direction: entering from the left edge is slideright, from the right slideleft, from the top slidedown, from the bottom slideup.",
      },
      seconds: num("Ramp length in seconds, 0.1–2 (default 0.5)"),
    }, ["clipId", "which", "style"]),
  },
] as const satisfies readonly AiToolDef[];

export type TransitionsToolName = (typeof TRANSITIONS_TOOLS)[number]["name"];