Skip to content

Open source CapCut alternative.

TypeScript
32.2 KB
Raw Blame
/**
 * The assistant's timeline tools — selection, cutting, placement, tracks,
 * overlay video layers, the toolbar's Text button, freeze frames, and the
 * timeline view — kept beside the timeline component that exposes the same
 * editing surface. The catalog spreads this list into the model's toolset
 * and `aiTools.ts` keys its handlers on `TimelineToolName`.
 */

import { bool, ids, num, obj, str, type AiToolDef } from "@/cut/lib/aiToolDef";
import { ITEM_KIND_IDS, ROW_ITEM_KINDS, canSplitItem } from "@/cut/lib/itemKinds";
import { TIMELINE_ITEM_KINDS } from "@/cut/lib/timelineGroups";
import {
  TEXT_EMPHASIS_IDS,
  TEXT_LAYOUT_IDS,
  TEXT_LAYOUT_NOTES,
  TEXT_VARIATION_IDS,
} from "@/cut/lib/textCompose";
import { TEXT_MOVE_IDS, TEXT_MOVE_NOTES } from "@/cut/lib/textMotion";
import { LETTER_SPACING_MAX, LETTER_SPACING_MIN, OVERLAY_ANIM_STYLE_IDS, TEXT_TEXTURES, TEXT_WEIGHTS } from "@donkeycut/effects-kit";
import { IMAGE_CLIP_SECONDS, REGION_MAX_SCALE, TIMELINE_IDS, TIMELINE_LABELS } from "@/cut/lib/types";
import { BLOCKOUT_MAX } from "@/cut/lib/blockSource";

/** The title sizes the assistant and the inspector set, px at a 1080 short
 * side. */
export const TEXT_SIZE_MIN = 16;
export const TEXT_SIZE_MAX = 1600;

/** The fields one title takes, alone or as an item of `titles`. */
const TITLE_FIELDS = {
  text: str("The title text (\\n for line breaks)"),
  start: num("Start time s (default: playhead)"),
  end: num("End time s (default: start+3)"),
  x: num("Center x 0..1 (default 0.5)"),
  y: num("Center y 0..1 (default 0.42)"),
  size: num(`Font size px at 1080w, ${TEXT_SIZE_MIN}..${TEXT_SIZE_MAX} (default 88); a capital is about 0.7 of the size tall, so one letter filling a third of a 1080 frame is about 500`),
  color: str("CSS color (default #FFFFFF)"),
  font: str("Font id (see the graphics skill; default sf)"),
  weight: { type: "number", enum: [...TEXT_WEIGHTS], description: "Font weight: 400 regular, 500 medium, 600 semibold, 700 bold, 800 extra bold, 900 black" },
  italic: bool("Italic"),
  align: { type: "string", enum: ["left", "center", "right"], description: "Multi-line alignment (default center)" },
  letter_spacing: num(`Tracking in em, ${LETTER_SPACING_MIN}..${LETTER_SPACING_MAX} (0 = normal, 0.1 = airy, negative = tight)`),
  line_height: num("Line height multiplier (default 1.25)"),
  stroke_color: str("Text outline color"),
  stroke_width: num("Text outline width in em (0..0.15; 0 removes it)"),
  shadow: bool("Drop shadow (default true)"),
  plate: bool("Translucent plate behind text (default false)"),
  texture: {
    type: "string",
    enum: [...TEXT_TEXTURES, "none"],
    description: 'Grain inside the letters: "stipple" breaks each letter into spray-paint specks along its left edge, solid by its middle (the gritty teaser title); "none" makes the type solid again',
  },
  rotation: num("Degrees clockwise, -180..180, to a tenth (0.4 matches a slight lean)"),
  opacity: num("Whole-element opacity 0..1"),
  lane: num("Element row (0 = the front row, drawn over every higher row). Elements on one row never overlap — a title over a shape needs a lower row than the shape. Use as few rows as the stacking needs: an element shares a row with anything it never overlaps in time."),
};

export const TIMELINE_TOOLS = [
  {
    name: "select",
    description:
      "Select any timeline item: video, audio, an overlay element, caption cue, or transition (or clear the selection). Selection appears in the timeline and preview. Use additive:true to toggle an item in the selection; move_selection moves the selected visual items together.",
    inputSchema: obj({
      kind: { type: "string", enum: [...TIMELINE_ITEM_KINDS, "none"], description: "What to select — 'clip' is any video clip, whatever track; 'overlay' is any title-lane element" },
      id: str("The item id (omit for kind=none)"),
      additive: bool("Toggle this item in the existing selection"),
    }, ["kind"]),
  },
  {
    name: "group_items",
    description: "Group the selected timeline items, including video, audio, text, shapes, captions and transitions. Use select with additive:true to build the selection first. New items start ungrouped. Selecting any group member selects the whole group; drag a member to move the group.",
    inputSchema: obj({}),
  },
  {
    name: "ungroup_items",
    description: "Ungroup every group represented in the current selection. Items keep their timing and become independently selectable and movable.",
    inputSchema: obj({}),
  },
  {
    name: "move_timeline_selection",
    description: "Move selected timeline items and their group members together by delta seconds, preserving relative timing and caption word timings. Negative moves stop at the timeline start; occupied rows move the set to the next free position. Use this for a grouped selection, including captions and transitions.",
    inputSchema: obj({ delta: num("Timeline shift in seconds") }, ["delta"]),
  },
  {
    name: "insert_item_row",
    description: "Move an item into a new row before a displayed row in its own timeline band, like dropping between rows. Display rows count from the top starting at 0; the row count inserts after the last row. Empty source rows collapse. Timing stays fixed and the edit is undoable.",
    inputSchema: obj({
      kind: { type: "string", enum: ROW_ITEM_KINDS, description: "Timeline item kind" },
      id: str("Timeline item id"),
      before_row: { type: "integer", minimum: 0, description: "Display row to insert before" },
    }, ["kind", "id", "before_row"]),
  },
  {
    name: "pack_lanes",
    description:
      "Close the timeline up onto the fewest lanes, changing lanes only — no start, trim or look moves. Soundtrack clips that never overlap in time share a lane. Elements keep the front-to-back order of every pair that overlaps, and effects keep rows of their own. Run it after building or rearranging a cut a piece at a time; it reports each band's lane count before and after. One undo step.",
    inputSchema: obj({
      band: { type: "string", enum: ["both", "soundtrack", "elements"], description: "Which band to pack; default both" },
    }),
  },
  {
    name: "split_at",
    description:
      `Split items and their group members at a time, like pressing S: the items \`ids\` names, else the selection, else the video on track 0. Supported kinds: ${ITEM_KIND_IDS.filter(canSplitItem).join(", ")}. Transitions remain whole. Omit t for the playhead. Times stay fixed; the result includes the new selected ids.`,
    inputSchema: obj({
      t: num("Timeline seconds to cut at (optional)"),
      ids: { type: "array", items: { type: "string" }, description: "Ids of the items to split, any track or kind (optional; default the selection)" },
    }),
  },
  {
    name: "move_clip",
    description:
      "Reorder a track-0 video clip to a new index: its old spot becomes a gap and clips from the landing index shift right to make room. The moved clip and displaced clips carry their group members with relative timing preserved. Occupied rows can move a group farther right. To set a timeline start, use place_clip.",
    inputSchema: obj({ clipId: str("Video clip id"), toIndex: num("Target index, 0-based") }, ["clipId", "toIndex"]),
  },
  {
    name: "place_clip",
    description:
      "Move a track-0 video clip to a timeline start time (seconds). The track is free-positioned: gaps are allowed and play black. If another clip occupies that spot, the clip slides right to the next free one.",
    inputSchema: obj({ clipId: str("Video clip id"), start: num("Target timeline start s") }, ["clipId", "start"]),
  },
  {
    name: "add_clip",
    description:
      `Put a project asset on the timeline, the same way the user dragging it in would: a video or image lands on video track 0 (at \`start\`, inserted at \`index\`, or appended at the end; a taken spot slides it right), audio lands on the soundtrack (at \`start\`, default the playhead). Asset ids come from \`media\` in editor_state — imports, attachments, and chat media alike. Call it only when the user asked for the media in the cut ("add my beach photo", "stitch these into a movie"); otherwise media stays on its card or panel for them to drag. Pass \`blocks\` instead of an asset to lay out a cut whose footage does not exist yet: one block per shot on track 0, each the length that shot runs, labelled with what belongs there. That is how a video you watched becomes a timeline — the cuts land at their real times, titles and sound go on top, and the person fills each block later. Blocks own no file and store nothing; footage dropped on one takes its place and its length, and replace_item does the same from here. A block runs one frame (1/60 s) or longer, so detect_cuts' \`shots\` go down as they are, flash cuts included — pass each as its \`from\` and \`to\`, which land every cut on its frame, where lengths summed from times written to the millisecond drift a frame late; one call takes up to ${BLOCKOUT_MAX}, and a longer list goes in more calls with no start, each appending after the last block. Pass \`spans\` to cut one source into a run of clips — the moments of a talk worth keeping, with everything between them left out, or a video cut at its own shot boundaries when its picture is what plays. add_clip lays down the whole file; an item another timeline already has ("Main's music", "the same intro as Main") is copied with copy_from_timeline, which keeps its trim and mix.`,
    inputSchema: obj({
      asset_id: str("Project asset id from `media` in editor_state"),
      blocks: {
        type: "array",
        description: "Shots with no footage yet, in order — one block each on track 0",
        items: obj(
          {
            from: num("The shot's first second, as detect_cuts' shots read it"),
            to: num("The second the shot ends, as detect_cuts' shots read it; with from it sets the block's length exactly"),
            seconds: num("How long this shot runs on the timeline, when there is no from/to"),
            label: str("What the person puts here. It names the slot on its timeline chip; the frame itself is the flat colour"),
            color: str("The shot's backdrop as #rrggbb, so the slot carries the look it sits in"),
          },
          []
        ),
      },
      spans: {
        type: "array",
        description:
          "Stretches of this source, in SOURCE seconds — one clip each, in order. Gapped spans keep the moments and drop the rest; spans that meet cut the source at those boundaries.",
        items: obj({ from: num("Source start s"), to: num("Source end s") }, ["from", "to"]),
      },
      lane: { type: "integer", minimum: 0, description: "Audio assets only: soundtrack lane. Omit it and a sound placed with `start` lands at that moment on the lowest lane free there — lane 0 unless it overlaps another sound. Pass one only to stack on purpose; never open a lane per sound." },
      start: num("Timeline start s"),
      index: num("Insert position on video track 0 (video/image only; 0 = first)"),
    }),
  },
  {
    name: "trim_clip",
    description:
      "Set a video clip's source trim points in seconds. Growth pushes overlapping neighbors on its own video track; shrinking leaves a gap. Other rows keep their timing.",
    inputSchema: obj({ clipId: str("Video clip id"), in: num("New in point (optional)"), out: num("New out point (optional)") }, ["clipId"]),
  },
  {
    name: "refine_speech_cuts",
    description:
      "True up speech-cut edges against the words themselves: re-reads the audio around each clip's in/out, measures that recording's own room tone and voice level, finds where the words actually start and finish — tails and soft attacks included — and re-trims so every edge sits a measured beat clear of one. An edge inside a word moves outward until the word is whole; stray dead air trims off. THIS IS WHERE PACE IS SET: `pace` fast|natural|relaxed chooses how much air is left (~0.14s/0.26s/0.45s after the last word, ~0.09s/0.16s/0.28s before the next), and even fast never cuts closer than 0.08s to a word. Cutting closer than the pace is not faster, it is clipped. Clip spacing survives: a tightened clip closes up, butted joints stay butted, deliberate gaps keep their width, and where a pause is too short for both sides' air the two edges meet inside it. An edge with no word within ~2s stays put and comes back flagged. Run it on every clip you recut for speech, after cutting and before listening; leave out clips whose edge you placed mid-speech on purpose.",
    inputSchema: obj(
      {
        clip_ids: {
          type: "array",
          items: { type: "string" },
          description: "Video clip ids whose in/out edges are speech cuts",
        },
        pace: {
          type: "string",
          enum: ["fast", "natural", "relaxed"],
          description:
            "How much air each edge keeps around the words — fast for a punchy recut, relaxed to let it breathe. Default natural.",
        },
      },
      ["clip_ids"]
    ),
  },
  {
    name: "set_clip_muted",
    description: "Mute or unmute a video clip's own audio.",
    inputSchema: obj({ clipId: str("Video clip id"), ids: ids("clipId"), muted: bool("true to mute") }, ["muted"]),
  },
  {
    name: "rename_item",
    description:
      "Name any timeline item — a video or image clip on any track, a soundtrack clip, or a title/shape/sticker/effect element — by id. The name shows on its timeline bar, in the inspector and in editor_state, so a cut full of look-alike items stays legible. An empty name clears it, back to the file's name or what the element is. Pass `names` to name a whole cut in one call.",
    inputSchema: obj({
      id: str("Clip, soundtrack clip, or element id"),
      name: str("The name, up to 60 characters; empty clears"),
      names: {
        type: "array",
        description: "Several items at once, each {id, name}",
        items: obj({ id: str("Item id"), name: str("Its name") }, ["id", "name"]),
      },
    }),
  },
  {
    name: "set_clip_hidden",
    description:
      "Hide or show a video clip on any track. A hidden clip stays on the timeline (grayed) but is excluded from playback and export — its span plays black and silent on track 0; an overlay layer just disappears.",
    inputSchema: obj({ clipId: str("Video clip id"), ids: ids("clipId"), hidden: bool("true to hide") }, ["hidden"]),
  },
  {
    name: "set_track_hidden",
    description:
      "Hide or show a whole timeline row at once — the row's eye toggle. Applies to every item on that row: a hidden video track plays black and silent, a hidden soundtrack lane is silent, hidden text (title) lanes and subtitle tracks drop out of the picture, and hidden transitions leave their cuts hard. Items stay on the timeline, grayed. The transitions row is the only one of its kind, so omit `track` for it.",
    inputSchema: obj({
      kind: {
        type: "string",
        enum: ["video", "soundtrack", "text", "subtitles", "transitions"],
        description: "Which row kind",
      },
      track: num("Track/lane index, 0-based; omit for transitions"),
      hidden: bool("true to hide"),
    }, ["kind", "hidden"]),
  },
  {
    name: "set_track_muted",
    description:
      "Mute or unmute every clip on one video track at once — the track header's speaker toggle. The picture keeps playing.",
    inputSchema: obj({ track: num("Video track index, 0-based"), muted: bool("true to mute") }, ["track", "muted"]),
  },
  {
    name: "reorder_track",
    description:
      "Move a whole timeline row to another place in its own band — the gutter drag. Rows only ever reorder among their own kind: video tracks restack (row 0 is the bottom track, the spine that carries ripple and transitions; higher rows composite in front), element rows and soundtrack lanes renumber from there. Everything on the row travels with it and keeps its times.",
    inputSchema: obj({
      kind: { type: "string", enum: ["video", "soundtrack", "text"], description: "Which band the row belongs to" },
      from: num("The row's current index, 0-based"),
      to: num("The index it should end up at, 0-based"),
    }, ["kind", "from", "to"]),
  },
  {
    name: "delete_item",
    description:
      "Delete a timeline item and its explicit group by id. Other items keep their timing. The deleted footprint becomes a gap; remove_gap closes it.",
    inputSchema: obj({
      kind: { type: "string", enum: TIMELINE_ITEM_KINDS, description: "Item kind — 'clip' is any video clip, whatever track; 'overlay' is any title-lane element" },
      id: str("Item id"),
      ids: ids("id"),
    }, ["kind"]),
  },
  {
    name: "remove_gap",
    description:
      "Close the empty span on one video track containing `at` seconds: that track's later clips slide left to shut the gap; every other track, titles, captions, and the soundtrack stay put. Errors unless `at` falls inside a gap on that track.",
    inputSchema: obj({
      at: num("A time (seconds) inside the gap to close"),
      track: num("Video track the gap is on (default 0)"),
    }, ["at"]),
  },
  {
    name: "set_magnet",
    description:
      "Turn the project's magnet on or off. On, track 0 stays closed up: deleting, trimming or moving a clip there pulls everything after it left, and the clips on other tracks, the elements, captions and soundtrack move with the track-0 footage under their start, keeping their lengths (one over a closed gap lands on the join). Nothing can land below track 0 while it is on. Off, track 0 keeps its gaps, which play the background. Turning it on closes every gap at once. It is the user's setting: call it when they ask for the magnet, ripple editing, or a track 0 that never has gaps; remove_gap closes one gap. editor_state project.magnet reports it.",
    inputSchema: obj({ on: bool("true turns the magnet on, false turns it off") }, ["on"]),
  },
  {
    name: "add_overlay_video",
    description:
      "Put a project video or image asset on an overlay video track, composited over track 0: tracks stack bottom-up, and the topmost full-frame clip covers everything below. Pick a layout to share the frame — halves for a split screen, pip for picture-in-picture. Asset ids come from `media` in the editor state. An image over a talking head belongs to the line that speaks of it: start it as that line starts and end it as the line ends.",
    inputSchema: obj({
      asset_id: str("Project asset id (video or image)"),
      start: num("Timeline start s (default: the playhead)"),
      end: num(`Timeline end s. An image runs from start to here; without it an image runs ${IMAGE_CLIP_SECONDS}s, stopping at the end of track 0. A video runs its source's length unless this ends it sooner`),
      track: num("Video track, 1 or higher; 1 = first layer above track 0, higher = further in front (default 1)"),
      layout: {
        type: "string",
        enum: ["full", "top", "bottom", "left", "right", "pip"],
        description: "Frame region (default full = covers the frame)",
      },
    }, ["asset_id"]),
  },
  {
    name: "update_overlay_video",
    description:
      "Update an overlay video clip: move it (start, track), trim (in/out), mute, hide, change its frame region (layout preset, or a custom region rect in frame fractions that may run past the frame's edges, e.g. to cover a screen in the shot that spills off the frame), fit, zoom, mirror (flipH/flipV), rotation, opacity, or speed. replace_item swaps the asset it plays.",
    inputSchema: obj({
      id: str("Overlay video clip id"),
      start: num("Timeline start s"),
      in: num("Source in s"),
      out: num("Source out s"),
      track: num("Video track, 1 or higher; higher = further in front"),
      muted: bool("Mute the clip's own audio"),
      hidden: bool("Hide the layer without deleting it"),
      layout: {
        type: "string",
        enum: ["full", "top", "bottom", "left", "right", "pip"],
        description: "Frame region preset; leave out when passing region",
      },
      region: obj({
        x: num("Centre of the box, frame fractions (0.5 = the middle), as add_title and add_shape take x; the box may run past the frame, and the frame crops the overhang. A box known by its left and top edges centres at left + w/2, top + h/2"),
        y: num("Centre of the box, frame fractions (0.5 = the middle)"),
        w: num(`Width in frame fractions, 0.05..${REGION_MAX_SCALE}; past 1 the box runs off the frame`),
        h: num(`Height in frame fractions, 0.05..${REGION_MAX_SCALE}`),
      }, ["x", "y", "w", "h"]),
      fit: { type: "string", enum: ["fit", "fill"], description: "How the video meets its region" },
      zoom: num("Zoom the picture past its fitted size, 1 (none) .. 4; the overflow crops"),
      flipH: bool("Mirror the picture horizontally (left for right)"),
      flipV: bool("Mirror the picture vertically (top for bottom)"),
      rotation: num("Resting turn in degrees clockwise, -180..180, to a tenth: match a screen in the shot that leans 0.4° (0 clears)"),
      opacity: num("Resting opacity 0..1 (1 clears)"),
      speed: num("Playback rate (1 = normal, no upper limit)"),
    }, ["id"]),
  },
  {
    name: "add_title",
    description:
      "Add a text title overlay. Position is the text center as a fraction of the frame (x,y in 0..1; y=0.42 is the default band). Size is px at 1080-wide. Font ids come from the graphics skill (system set + the bundled Google families). A line wider than the room its anchor leaves is broken onto more lines when it draws, so a title always sits inside the frame — write the words and pick the size the design wants. Pass `titles` to place a stretch's titles in one call.",
    inputSchema: obj({
      ...TITLE_FIELDS,
      titles: { type: "array", description: "Several titles at once, each the fields one title takes", items: obj(TITLE_FIELDS, ["text"]) },
    }),
  },
  {
    name: "add_text_sequence",
    description:
      "Place a run of text on the timeline in one call — plain lines timed to speech, a lyric video, a kinetic-typography passage, a quote sequence. Design is opt-in: with no `look` the run comes out plain — one readable face, one place in the frame, a short fade, no cards, no moves, and the project's frame color untouched. That is what a bare \"add the text\" or \"put the words on screen\" asks for. Name a `look` when the user asked for a designed run (a lyric video, kinetic type, a style, a vibe, \"make it interesting\"): `look` carries the design of one line (frame color, cards, type, entrance) AND the ensemble the run walks across its whole length: where successive lines land, which faces they rotate through, which entrances, and what each line does while it holds. So one such call already produces a varied, composed run without a hundred repair calls after it. Lines come from `lines` ({text, start, end} in timeline seconds), or from the caption track with from_captions when a sync already timed them. Each line keeps the start and end you give it, on its frame, and runs one frame (1/60 s) or longer, so a label per shot of a fast cut lands on that shot's frames however short; a line under 0.2 s cuts in and out (no entrance or exit, which would leave it blank on so few frames). In a designed run, mark the loud lines with `emphasis: \"hero\"` and the quiet ones `\"whisper\"`, and label passages with `section` (\"verse\", \"chorus\") — a new section restarts the type and color rotas, so a chorus does not look like the verse before it. Anything you set per line (font, x/y, rotation, in_style, move, color, size) wins over the ensemble. The words land on `lane` and each card on the row under them. A look that paints a frame color sets the project background to it unless background is false; the plain and over-footage looks leave the background alone unless background is true. Look ids, layouts and moves are in the text-videos and text-creativity skills.",
    inputSchema: obj({
      look: str("Look id from the text-videos skill. Omit it for the plain run — that is the default and the right answer whenever the user did not ask for a design."),
      variation: {
        type: "string",
        enum: [...TEXT_VARIATION_IDS],
        description:
          "How far the run departs from one repeated design. Defaults to what the look carries: the plain look runs at none, the designed looks at bold. bold walks the look's whole ensemble — faces, tilts, palette, moves; subtle keeps one typeface and varies placement and entrance; none lays every line identical.",
      },
      layout: {
        type: "string",
        enum: [...TEXT_LAYOUT_IDS],
        description: `Where successive lines land, overriding the look's own. ${TEXT_LAYOUT_IDS.map((id) => `${id}: ${TEXT_LAYOUT_NOTES[id]}`).join(" ")}`,
      },
      lines: {
        type: "array",
        description: "The run, in order. Omit times on a line and it follows the one before it.",
        items: obj(
          {
            text: str("The line (\\n for a break inside it)"),
            start: num("Timeline start s"),
            end: num("Timeline end s"),
            emphasis: {
              type: "string",
              enum: [...TEXT_EMPHASIS_IDS],
              description:
                "How loud this line is: hero is markedly bigger and takes the look's hero move, whisper is small and quiet. Default normal.",
            },
            section: str('Passage label ("verse", "chorus", "bridge") — a new label restarts the type and color rotas'),
            color: str("Override the run's color for this line"),
            size: num(`Override the composed size for this line, ${TEXT_SIZE_MIN}..${TEXT_SIZE_MAX}`),
            font: str("Override the face carrying this line"),
            x: num("Frame-width fraction 0..1, overriding the layout"),
            y: num("Frame-height fraction 0..1, overriding the layout"),
            rotation: num("Tilt in degrees, -45..45"),
            in_style: {
              type: "string",
              enum: [...OVERLAY_ANIM_STYLE_IDS],
              description: "Entrance for this line, overriding the rota",
            },
            move: {
              type: "string",
              enum: [...TEXT_MOVE_IDS],
              description: `What this line does WHILE it holds (the entrance is separate). ${TEXT_MOVE_IDS.filter((m) => m !== "none").map((m) => `${m}: ${TEXT_MOVE_NOTES[m]}`).join(" ")}`,
            },
          },
          ["text"]
        ),
      },
      from_captions: num("Build the run from this caption track's cues (0-based) instead of `lines`"),
      lane: num("Row for the words; their color cards go one row under them (default 0, the front row)"),
      cards: bool("Paint the look's color cards behind each line (default: whatever the look does)"),
      background: bool("Set the project background to the look's frame color (default true)"),
    }),
  },
  {
    name: "replace_item",
    description:
      "Replace what an item plays, keeping the item: a video clip (including a blocked-out shot) keeps its place and its length and plays the asset you name instead, trimmed from that source's head; a soundtrack clip keeps its slot; a sticker shows the new image. This is how a block becomes the person's own footage (\"put the kitchen clip in shot 3\"), and how any clip swaps its source without moving what comes after. The clip keeps its framing and rotation; its mask goes with the old picture unless keep_mask names it the layer's own region. A block left playing nothing goes with it.",
    inputSchema: obj(
      {
        id: str("The item to refill — a video clip, a soundtrack clip, or a sticker"),
        asset_id: str("Project asset that plays there instead"),
        keep_mask: {
          type: "boolean",
          description: "Video clips: keep the clip's mask when it cuts the layer to a region of the frame, such as a screen or a window",
        },
      },
      ["id", "asset_id"]
    ),
  },
  {
    name: "freeze_frame",
    description:
      "Extract the video frame at a time (default: the playhead — what the user is looking at) as a still clip and insert it into the timeline. Default insert position is index 0, making it the first thing viewers see (a cover/hook frame).",
    inputSchema: obj({
      t: num("Timeline time of the frame to grab (default: playhead)"),
      duration: num("Still clip length in seconds, 0.5–10 (default 1)"),
      index: num("Insert position on the video track (default 0 = first)"),
      with_elements: bool(
        "Bake the whole picture as the preview shows it — titles, captions and effects burned into the still (default false: the video frame alone)"
      ),
    }),
  },
  {
    name: "select_items",
    description:
      'Find every item a description covers, in one call: "the clips with no one talking", "the titles that are all caps", "the short ones at the end". Each item on the track is judged against the description at once and the matches come back as ids — this is how a sweep is done, instead of reading the state and deciding one item at a time. Then land the change on all of them with a single call: set_clip_muted, set_clip_hidden, set_clip_volume, set_color_preset, set_speed, set_framing, set_transition, delete_item, update_cue, delete_cue, update_audio and update_overlay all take `ids` in place of their one-item argument, and the whole write is one undo step. Describe what the items have in common, not what to do with them. It judges what the timeline already says about each item — its name, timing, text, and settings — so anything that needs the footage watched or the audio heard is measured first (watch_video, detect_silence, measure_level) and the finding is done here.',
    inputSchema: obj(
      {
        kind: {
          type: "string",
          enum: [...TIMELINE_ITEM_KINDS],
          description: "Which row of the timeline to look through",
        },
        describe: str("What the wanted items have in common, in plain words"),
        limit: num("At most this many ids, best fit first (default: every match)"),
      },
      ["kind", "describe"]
    ),
  },
  {
    name: "switch_timeline",
    description: `Open another of the project's ${TIMELINE_IDS.length} timelines (${TIMELINE_IDS.map((id) => `${id} = ${TIMELINE_LABELS[id]}`).join(", ")}) — the picker at the left of the timeline toolbar. Each timeline holds its own clips, soundtrack, transitions, elements, subtitles and aspect ratio; the media and the project settings are shared. The preview, the export and every other tool work on the open one, which editor_state project.timeline names, with project.timelines summarizing each. A timeline opened for the first time is empty at Main's aspect ratio, and each keeps its own undo history. A share link plays the timeline its share settings pick, Main by default. There are exactly these ${TIMELINE_IDS.length}; none can be added, renamed or deleted.`,
    inputSchema: obj({
      timeline: { type: "string", enum: [...TIMELINE_IDS], description: "The timeline to open" },
    }, ["timeline"]),
  },
  {
    name: "copy_from_timeline",
    description:
      "Copy items another timeline holds onto the open one, exactly as that timeline has them: a soundtrack clip keeps its in/out, volume, fades, speed and sound treatment; clips, elements, captions and transitions keep every property, and several items keep their spacing. This is how \"Main's music\" or \"the same title as on Main\" lands on this timeline. A parked timeline's soundtrack is in editor_state project.timelines; get_state with `timeline` lists all of its items. The source timeline is left as it was. A copy that would overlap an item on its row slides right past it, and the result gives that copy's askedStart and why.",
    inputSchema: obj({
      timeline: { type: "string", enum: [...TIMELINE_IDS], description: "The timeline to copy from" },
      ids: { type: "array", items: { type: "string" }, description: "Ids of the items on that timeline" },
      at: num("Where the earliest copy starts on the open timeline, seconds; omit to keep the source's times"),
      lane: { type: "integer", minimum: 0, description: "Soundtrack lane or element row for the copies (the lowest one when they span several); omit to keep the source's. Video clips keep their tracks." },
    }, ["timeline", "ids"]),
  },
  {
    name: "set_view",
    description:
      "Adjust the timeline view: zoom (pxPerSec 12..800), fit the whole cut, or panel height (170..600).",
    inputSchema: obj({
      pxPerSec: num("Zoom in px per second"),
      fit: bool("Fit the whole cut to the window"),
      timelineH: num("Timeline panel height px"),
    }),
  },
] as const satisfies readonly AiToolDef[];

export type TimelineToolName = (typeof TIMELINE_TOOLS)[number]["name"];