Skip to main content
Glama
NOTE

WeftCut is still under active development, so some features and UI/UX may change before v1.0.0. Join us to improve the project: start with thecontributing guide.

An agent editing the timeline live over MCP

Most editors bolt AI on as a feature: a button that generates something, a sidebar that suggests a cut. WeftCut exposes the editor itself as a tool surface. A localhost MCP server publishes all editing tools — place, trim, split, restyle, keyframe, group, caption, mix, checkpoint — and whatever agent you already have open drives them. The intelligence lives outside the app: the installer bundles no model weights, and the local engines for speech and vision are an opt-in download when you want them.

None of that rides on a stripped-down editor. Everything an agent can reach, you can do by hand, in a full NLE: A/B-roll timeline, keyframes with a curve editor, effects, captions, a role-based audio mixer, and hardware-accelerated export.

Quick start

NOTE

We don't have a verified macOS installer yet, so allow it under System Settings → Privacy & Security → Open Anyway

  1. Download the installer for your platform from the releases page.

  2. Install the app, open the settings panel, and copy the prompt that teaches your agent how to connect to WeftCut.

  3. Enjoy your work.

Related MCP server: ffmpeg-mcp-video-editor

Hand your timeline to an agent

Copy the prompt in settings into your client, and your agent is holding the editor.

  • It edits the project you are watching. No import/export round trip, no separate headless copy.

  • Every batch is reversible. A work session begins with a checkpoint that is one click from being restored, and every edit the agent commits is a step of your undo history.

  • Multi-agent, with rules. Sessions are per-connection. A work session locks undo for everyone but its agent, so a stray Ctrl-Z doesn't land in the middle of its work — the lock and the reason it gave are shown to you, and Unlock is yours.

Watch and review in Agent view

For a longer run, the agent can call begin_agent_session to open Agent view: a preview, a compact review timeline, and an Agent panel with Activity, Tacks and Changes tabs. Follow its tool calls in Activity while you watch the edit play, discuss specific passages with Tacks, then audit the result with Timeline diff in Changes. You can return to the full editor at any time.

Agent view with added, removed and modified clips and titles in the Changes panel, plus change and Tack ranges across the review timeline

Agent view after an editing pass: Changes lists additions, removals and modifications. The timeline shows them in green, red and yellow, with Tack ranges in teal.

Tacks give the conversation a place. An agent leaves a note, issue or question on a time range; you locate and play it, then resolve, dismiss or convert the Tack into a marker to keep. Tacks follow the content they cover and become outdated when what plays there changes, including on other tracks. The agent can read their statuses and receives feedback when its edits affect its open Tacks.

Timeline diff shows the result of the work. Open Changes to compare the current project with the state when you opened it or last chose Approve all. Inspect additions, removals and modifications, with before/after details and timeline highlights. Approve all makes the result your new review baseline; Revert all restores that baseline in one undoable step. Both include your own edits since the baseline.

Try: “Find the pauses in this interview and leave Tacks on the ones worth cutting. Let me review them before you edit.” Review the passages, tell the agent which cuts to make, then use Timeline diff to approve or revert the result.

Tacks last only for the current project opening. They are not saved or exported, and managing them adds nothing to undo history.

Agent: create_tacks · read_project { view: "tacks" } · update_tack · delete_tacks

Code as video: Motifs

A Motif is an on-screen element written as code — a real web page (HTML, CSS, SVG, canvas, WebGL, whatever you reach for) dropped on the timeline as a layer. It isn't a fixed preset: the author declares the knobs, and the inspector builds the form from that declaration, so seconds, label and accent below are editable in the app.

The one rule that makes it an editor feature instead of a screen recording: a Motif renders as a pure function of time. It never advances itself. The harness owns the clock and drives the page to each composition frame, so the same t always yields the same pixels — when you scrub, when you re-export, and in preview and export alike.

// The built-in Countdown's whole script, near enough verbatim — the rest of the
// file is the SVG ring it animates. `props` is whatever the manifest declares;
// `frame` runs once per composition frame and keeps no state of its own.
motif.define({
  setup: async function (props, ctx) {
    _label = props.label != null ? String(props.label) : "GO";
    num.style.color = props.accent;
    ring.style.stroke = props.accent;
    ring.setAttribute("stroke-dasharray", C);
    ring.animate([{ strokeDashoffset: 0 }, { strokeDashoffset: C }],
      { duration: ctx.duration * 1000, easing: "linear", fill: "both" });
  },
  frame: function (t, ctx) {
    var n = Math.max(0, Math.ceil(ctx.duration - t));
    num.textContent = n > 0 ? String(n) : _label;
  },
});

A Motif on the timeline, with its props in the inspector

Writing a web page is the thing coding agents are already best at — so an agent can author a brand-new overlay for your edit instead of picking one from a catalog. The authoring spec ships inside the app as an agent skill, so the model gets the contract without you pasting documentation.

Lower thirds, countdowns, karaoke text and animated title cards are the obvious uses. Anything you can build on a page is the actual limit.

A complete editor underneath

WeftCut editor

Timeline — A/B-roll rows with filmstrips and waveforms, frame-accurate SMPTE editing, ripple delete that closes the gap behind it, linked A/V that trims as one clip, cross-track groups, and nested compositions. Agent: move_layers · trim_layer · split_layer · shift_layers · create_link · create_group · move_layers_to_composition

Keyframes — animate any parameter, with bézier easing, a curve editor, tangent control, motion paths and extrapolation. Agent: set_keyframe · update_keyframe · set_param_track · get_param_track

Speech and captions — transcribe a clip and get editable caption layers packed onto your caption tracks; import SRT/VTT/ASS into the media pool and drop it where it starts. Transcription runs against a cloud provider, or entirely on your machine once you let the app fetch a local engine (whisper.cpp, FunASR) — or an agent can pull the raw audio out and run its own model. Text-to-speech for scratch voiceover. Agent: transcribe_clip · extract_clip_audio · apply_transcripts · apply_subtitles · synthesize_speech

Audio — role-based mixing (dialogue / music / SFX / voiceover) with live per-role metering, gain, pan, fades and denoise. Pauses finds the dead air in a take and cuts it as one undoable edit, keeping a pad so speech still breathes. Agent: detect_pauses · remove_pauses · set_role_gain · set_role_flags

The Role Mixer console, metering during playback

Understanding the footage — shot-boundary detection with per-shot brightness, motion and sharpness, frame comparison, and vision-model descriptions of what a clip actually contains. An agent can cut on content, not just on timecode. Agent: analyze_clip · auto_split_by_shot · describe_clip · compare_frames

Titles, effects and transitions — styled text layers with outlines, per-layer effect chains including chroma key with an eyedropper that picks from the live frame, and transitions between clips. Agent: add_effect · update_effect · add_transition · update_transition

Export — H.264 / HEVC / AV1, hardware or software encoders, resolution / fps / quality controls, and streamed muxing.

Find anything — one Ctrl+K palette over commands, media, clips, captions and markers, search for whatever you want.

Search palette

Tech stack

Layer

Stack

Shell

Electron 44 · TypeScript 7 · electron-vite · Vite 8 · Node 24

UI

React 19 · Zustand · Immer · Tailwind CSS v4 · Base UI · shadcn/ui · Dockview · lucide · i18next (en-US / zh-CN) · fuzzysort

Preview

PixiJS v8 · WebGPU / WebGL · WebCodecs VideoDecoder pool · mediabunny · own YUV→RGB shaders · Web Audio clock

Export

Worker + OffscreenCanvas · GPU YUV pack pass · PBO readback · rawvideo over IPC · native ffmpeg sink · WebCodecs encoder (pin) · stream-copy mux

Native core

Rust · napi-rs 3 · Tokio · imbl · serde · schemars · blake3 · reqwest · ffmpeg-sidecar

Native decode

@weftcut/native-decode · ffmpeg-next · software + GPU lanes · sharedTexture (Windows)

Shared math

weftcut-eval crate · native + wasm32 · snap · keyframe eval · envelope · role gate

ffmpeg

GPL CLI sidecar (jobs, encode, mux) · LGPL shared libs (in-process decode)

Agent surface

MCP · streamable HTTP on localhost · stdio through the weftcut binary (Go, standard library only) · @modelcontextprotocol/sdk · bearer token · TS + Rust tool catalog

Motifs

Offscreen BrowserWindow · Chrome DevTools Protocol · motif: scheme · CSP default-src 'none'

Speech & vision

Cloud providers over reqwest · whisper.cpp · FunASR · on-demand model download

Tests & CI

Vitest · cargo test · go test · Playwright · node --test · Stryker · GitHub Actions (Windows / macOS / Linux)

Design decisions: ADRs.

Build from source

Prerequisites: Node 24+, Rust (version pinned by rust-toolchain.toml, installed via rustup), Go (version named by apps/desktop/cli/go.mod), and your platform's C/C++ build tools and libclang — per-OS commands in docs/setup.md.

npm install       # JS dependencies
npm run bootstrap # one-time: fetch ffmpeg + build the Rust addons
npm run dev       # start the editor

Also useful: npm run typecheck, npm test, npm run e2e, npm run build, npm run package (installers).

Documentation

Start with architecture for the system map, or MCP server & agent UX for the tool surface, resources and multi-agent behavior. Motifs and motif authoring cover the overlay engine and its contract.

  • Data model — project state schema, history, persistence, validation.

  • Render — PixiJS + WebCodecs renderer architecture.

  • Preview — interactive preview surface and transport.

  • Export — export pipeline, settings and range, audio, finalization, export jobs and presets.

  • Captions · Audio — caption ingestion and the audio engine.

  • Conformance — E2E gates that export real media and check frame alignment, audio sync and colour.

  • Features — the concrete behavior of each editor capability: selection, links, groups, ripple delete, markers, shot review, pauses, search, gizmo, crop.

  • Status / log system — the bottom-of-editor log bus.

  • Setup — per-OS toolchain prerequisites and first-run flow.

  • Licensing — MIT app plus the two FFmpeg lanes and their build-time compliance gates.

  • v1 target — release scope and open work, tracked as an issue: docs/ describes what exists today.

Community

Join the WeftCut Discord community to share feedback, discuss feature ideas, and get help. Please use GitHub Issues for bug reports and feature requests so they can be tracked. Before opening a pull request, read the contributing guide.

Maintainer

WeftCut is built and maintained by UncleChair.

It exists to speed up my own video work. I wanted an editor an agent could actually drive, and a timeline I could keep watching while it did — so the MCP surface is the part I use daily, not a demo bolted onto the side. Motifs came from the other half of that: the overlays I wanted were easier to write than to find, and an agent that can write a web page can write one for the shot in front of it.

The project sits under the WeftCut organization so the name, domain and releases have a stable home, but it is a one-person project — issues and pull requests all reach me.

Star History

License

WeftCut is licensed under the MIT License. Packaged installers bundle FFmpeg binaries under their own licenses (LGPL shared libraries for in-process decode, GPL command-line tools run as a separate process) — see THIRD-PARTY-NOTICES.md and docs/licensing.md for the full model.

Available Tools

101 tools
add_effectA

Append an effect to a layer's chain (applied last), with params as plain numbers, and return its record (effect_id, kind, index, params). An unset param is its catalog default (effects://catalog: every kind's params, defaults and ranges), and can be keyframed at once as effects[<effect_id>].params[<key>]. Visual kinds ("blur", "chromakey", "brightness", "contrast", "highlights", "saturation", "sharpen") go on visual layers; the colour controls and sharpen default to 0, no change; chromakey's key colour keyR/keyG/keyB is 0..1, not 0..255. audio.* kinds go on Audio layers ONLY, params STATIC ONLY (AudioEffectParamStatic); a kind on the wrong layer kind is EffectKindNotApplicable. "audio.denoise" (strength, margin dB) does nothing until profile_in_us/profile_out_us, SOURCE-time bounds of a noise-only span ≥ 250000 µs, are set.

Inputs: kind (required), layer_id (required), params.

add_group_membersA

Move selected clips into an existing Group while preserving external placement. Requires Group rate 1 and compatible selection. Refuses partial links, locked members and cycles. Returns the resulting Group. To land them at a chosen time inside: move_layers_to_composition.

Inputs: layer_ids (required), group_layer_id (required).

add_layersA

Place 1–50 layers in ONE recorded edit, all or nothing: any refusal commits none. content.kind picks what each layer is. A layer without track_id gets a fresh track in the same edit; layers on one lane cannot overlap. A Video with an audio stream also lands its dialogue Audio on the same track's audio lane, linked (audio); an occupied audio lane refuses naming the blocker. Audio-only media is kind audio, a still kind image; a subtitle document is apply_subtitles. Returns { layers: [{ layer_id, track_id, t_start_us, t_end_us, adjusted, linked }] } in input order; adjusted lists grid snaps, linked is { audio_layer_id, link_id } or null.

Inputs: layers (required), composition_id.

add_markerA

Add a marker (point or region) to a composition's timeline — the root, or the Group named by composition_id. Returns the marker record (marker_id, t_us as snapped). Set t_end_us to make it a region marker. Set anchor_layer_id to have the mark FOLLOW a clip instead of standing at a fixed time; omit it for an ordinary marker. color defaults to the timeline's marker blue.

Inputs: t_us (required), label (required), note, color, +3 more.

add_trackA

Add a track and return its record (track_id, index, composition_id). Tracks are kind-agnostic — any layer kind goes on any track. A track disappears when its last layer leaves it (deleted or moved away), so place a layer rather than reserving a track; a track created empty survives until it has been filled and emptied.

Inputs: label, composition_id.

add_transitionA

Add a transition at the cut between two adjacent layers on the same track — from_layer_id (outgoing) ends exactly where to_layer_id (incoming) starts — and return its record. kind 'Crossfade' (default) | 'Wipe' | 'Slide'; direction is the MOTION direction ('left' = the boundary or the sliding content moves left), required for Wipe/Slide and rejected for Crossfade. placement 'overlap' (default) moves the INCOMING layer left by the frame-rounded duration so both still play exactly their trimmed ranges and the vacated span stays a gap — nothing ripples; link siblings follow, bouncing to a free lane. 'extend' instead borrows outgoing tail media past its out-point, positions untouched (extended_us = duration), refused with TransitionInsufficientHandle { available_us } when the tail is short. A pair already overlapped by exactly the duration attaches as-is. Refuses: participants sharing a link, a move crossing t = 0, a duration longer than either participant, an Audio participant (TransitionUnsupportedLayerKind). Recorded — one undo restores every moved layer.

Inputs: duration_us (required), to_layer_id (required), from_layer_id (required), kind, +2 more.

analyze_audioA
Read-only

Analyze original source audio from cached waveform peaks; local, read-only, no model. Returns bounded peak/RMS waveform bins, onset candidates and signed energy changes (dB), all in source µs (src_*), plus resolution and event counts. Choose music edit/alignment points, including outside a clip's trim. These are amplitude measurements, not beats, bars or melody recognition. At most 60 s per call; max_points affects only the summary. Peaks are cache-limited, not true-peak or LUFS. To land src_us at timeline T on a layer: src_in_us = src_us - (T - t_start_us) * rate (rate from project://tracks, 1 when absent).

Inputs: media_id (required), max_points, src_end_us, src_start_us, +1 more.

analyze_clipA
Read-only

Shots and defect spans of a video's source, deterministic. media_id: a pooled item, placed or not, whole; layer_id: a VideoClip, clipped to the source it plays, plus its mapping (t = t_start_us + (src - src_in_us) / rate). Returns { media_id, mapping?, shots: [{ index, src_start_us, src_end_us, src_keyframe_us, brightness, motion, sharpness, flags }], cut_scores: [{ src_us, score }], spans? }, source µs; score 0..1. Stats from 3 frames/shot: brightness midpoint mean luma 0..1; motion 1 - SSIM of the end frames; sharpness Laplacian variance, relative per source. flags: "black" (all 3 < luma 0.02), "freeze" (SSIM >= 0.985), "fade" (monotonic luma ramp >= 0.15 touching < 0.10). Dark/blurry/frozen spots in shots: passes: ["spans"] samples every step_us into spans: [{ kind, src_start_us, src_end_us, value }]: "dark" luma < 0.08 >= 0.5 s (value: mean), "soft" sharpness < 35% of source median >= 1 s (value: ratio), "frozen" adjacent SSIM >= 0.985 >= 1 s (value: min). passes default shots, stats, events; ["shots"] = timing only. To split: auto_split_by_shot.

Inputs: passes, step_us, layer_id, media_id, +2 more.

apply_subtitlesA

Lay an imported Subtitle item (a .srt/.vtt/.ass from import_media) onto the caption tracks as one editable Text layer per cue, one recorded edit. The whole document lands, its time 0 at t_start_us. Each cue packs onto the first unlocked caption track with room, opening a new one only where it collides with all of them. Advanced ASS styling is simplified. Returns { caption_track_id, cues, simplified }.

Inputs: media_id (required), t_start_us, composition_id.

apply_transcriptsA

Lay transcripts on the caption tracks of composition_id (root by default), keeping per-word timing. Pass transcribe_clip's transcripts as is, or your own cues with word_timing: 'none', unsplit: cues are built to the style's caption limits (lines broken, long segments split). A transcript whose source clip changed since it was transcribed (trimmed, cut, moved) is refused: transcribe it again. Cues pack into the existing caption tracks, opening a lane only when all collide, and snap to frames. Returns { caption_track_id, cue_layer_ids }, cues in time order. At most 1000 transcripts. One recorded edit.

Inputs: transcripts (required), composition_id.

auto_split_by_shotA
Destructive

Split a VideoClip at cached analyze_clip shot cuts as one edit. min_shot_us defaults to 500000. drop_short deletes shorter shots and overlapping link members. Returns layer_ids in timeline order (the original id alone when no interior cut exists) and siblings: [{ layer_id, segments }], each link partner cut with it.

Inputs: layer_id (required), drop_short, min_shot_us.

begin_agent_sessionA
Idempotent

Begin a work session for a batch: one Pre-agent checkpoint, the review baseline pinned to it, and the lightweight agent view. lock (default true) locks the user's undo until the session ends, reason shown in its place; your own undo, redo, jump_to and restore_checkpoint still work. Repeating on the same connection returns the session, changing the lock only when lock is passed. Another connection's session refuses (AgentSessionBusy names the holder) unless force: true ends it and begins yours. end_agent_session, the user or your connection closing ends it. Answers the session with locked, and taken_over after a force. Unrecorded.

Inputs: reason (required), lock, force.

cancel_exportA
DestructiveIdempotent

Cancel or discard an export from either entry point. Cancellation drains active work before releasing the project edit lock; wait on get_export_status until terminal.

Inputs: job_id (required).

check_compositionA
Read-only

Check a composition against the craft rules (skill craft/rules.md) and the project's taste: { composition_id, revision, findings: [{ severity, rule, range, layers, message, fix }], counts }. hard: fix before handoff; warning: fix, or leave a tack saying why not; review: a departure from the style to confirm. Project data only — text extents are estimated. The whole composition is checked and remembered; t_start_us/t_end_us only narrow the findings returned. Run it after your edits and after fixing.

Inputs: t_end_us, t_start_us, composition_id.

compare_framesA
Read-only

Compare two video frames for perceptual similarity — dedup shots, match a cutaway. Each side is { media_id | layer_id, src_us }: a pooled video (placed or not) or a VideoClip, and a source µs time (the space of analyze_clip's src_keyframe_us and media://{id}/frame/{src_us}); the two may be one source or two. Returns { phash_hamming, ssim, similar }: phash_hamming is the 0..64 distance between the frames' perceptual hashes (0 = identical, 20+ = a different scene), ssim is structural similarity 0..1, and similar is phash_hamming <= 10 && ssim >= 0.5. Read-only; video only, errors naming the offending side.

Inputs: a (required), b (required).

correct_caption_textA

Correct caption TEXT against script, the full verbatim transcript of what is said (not notes or a glossary): each cue's words are aligned to it and misheard words, names and terms replaced. Cue segmentation and timing never change. Refuses (InvalidArgument, field script) when under half of the caption words align to it. Every caption in composition_id (root by default); layer_ids narrows it (a non-caption id refuses). Returns { changed, match_ratio, changes: [{ layer_id, before, after }] }, at most 20 listed (changed counts all). Refuses whole, before any write, if a target or its track is locked. One recorded edit; nothing to change records nothing.

Inputs: script (required), layer_ids, composition_id.

create_checkpointA

Create a named checkpoint of the current state and return { checkpoint_id, label }. It lasts for this project opening only: opening another project or quitting drops it. It survives later commits (unlike the redo tail); project://history lists checkpoints and the agent panel shows each with a Restore button. begin_agent_session already makes one. Unrecorded.

Inputs: label (required).

create_export_presetA

Create a reusable personal export preset. Copies base_preset_id (default builtin:match) and applies optional settings. Built-in base bitrate is copied as a fixed standard-frame-rate value; use get_export_options with preset_id to inspect project-adapted values. Does not change the default or project settings.

Inputs: name (required), settings, base_preset_id.

create_groupA

Pre-compose selected clips into a new Group, preserving their placement and links. Refuses partial links, locked members and incompatible selections. Returns the Group clip and composition. Group members retain their own timing and effects.

Inputs: layer_ids (required), label.

create_projectA
Destructive

Create <parent_folder>/<name> and open it, as New Project does; only when the user asked. The project open before is saved. Defaults: the session view's default_parent_folder; 1920x1080 at 60 fps (the rate locks once a layer is placed). Returns { name, dir, replaced }.

Inputs: name (required), fps, width, height, +1 more.

create_tacksA

Point the user at time ranges to review — a pause to check, a shot to judge, a cut to decide. Not a marker: it lives in the agent panel for this project opening only; the user resolves, dismisses or clears it; use it unless the user asked for markers. Create after your edits; all or none. It comments on what plays in its range on every track: it moves with that content and is outdated once the range plays anything else. Describe content, never times: the panel shows the live place. One place, one tack. Returns { tacks, hints? } as project://tacks reads them; later edits report your moved or outdated ones as affected_tacks. TackLimit past 1000. Unrecorded; works while history is locked.

Inputs: tacks (required).

delete_compositionA
Destructive

Delete a composition nothing references — an orphan left when its Group layers were deleted. Refuses while any Group layer points at it (CompositionInUse { ref_count }; project://compositions shows the count) and refuses the root (RootComposition). Recorded.

Inputs: composition_id (required).

delete_effectC
Destructive

Remove an effect from a layer by id.

Inputs: layer_id (required), effect_id (required).

delete_export_presetA
DestructiveIdempotent

Delete a personal export preset. Deleting the default restores builtin:match. Existing projects are unchanged. Built-ins are read-only.

Inputs: preset_id (required).

delete_keyframeA
Destructive

Remove a keyframe by id from a layer param (keyframe_ids in get_param_track). When it was the last key, the track collapses to Static holding that key's value. Returns the track's mode and keyframe_ids, or the static value.

Inputs: layer_id (required), param_key (required), keyframe_id (required).

delete_layersA
Destructive

Delete a set of layers as one recorded edit. Nothing is expanded: pass link partners (link_id in project://tracks), or a lifted video leaves its dialogue playing. ripple decides what happens to the vacated span: false (default) is the lift — it stays empty and nothing moves; true closes each hole so the film gets shorter — every remaining layer starting at or after a hole shifts left by its length on EVERY track of the composition (anchored markers riding along), touching holes merge, and layers starting before a hole, free markers and the playhead stay put. The set is one composition's (CrossCompositionSet); any locked layer or track refuses the whole batch; tracks the batch emptied are pruned. A ripple refuses whole, before any write, naming the blocker: RippleInsideHole (a remaining layer starts inside a hole — add it to layer_ids, or lift), RippleCollision (a mover would land on a layer that is not moving), RippleLinkStraddles (a link spans the hole), RippleLockedLayer (only a layer that shifts blocks). An empty set is refused as a ripple.

Inputs: layer_ids (required), ripple.

delete_markerC
Destructive

Remove a marker.

Inputs: marker_id (required).

delete_mediaA
Destructive

Remove a media item. Rejects if any layer references it unless force=true. With force=true, also deletes the referencing layers in one atomic commit, exactly as delete_layers would: their links dissolve below two members, a transient lane they empty is pruned, a locked lane refuses as TrackLocked. Unrecorded when nothing used it; the forced cascade records.

Inputs: media_id (required), force.

delete_motifA
Destructive

Delete a user Motif or draft (and its pending proposal); linked source directories are never deleted. Built-ins are refused. Referencing layers become missing-content placeholders.

Inputs: motif_id (required).

delete_tacksA
Destructive

Remove tacks: the listed tack_ids (every one must exist, or none is removed), or every tack created in work session session_id. Exactly one of the two. Returns { deleted_tack_ids }. Unrecorded.

Inputs: tack_ids, session_id.

delete_trackA
Destructive

Remove a track. Refuses a track with layers unless force=true (TrackNotEmpty); with force the layers go with it and their links are cleaned up in the same undo entry. A Group layer among them leaves its composition in place with ref_count 0 (project://compositions) — delete_composition removes that. Only A roll / B roll tracks are protected (TrackNotRemovable); audio and caption tracks can be deleted.

Inputs: track_id (required), force.

delete_transitionA
Destructive

Remove a transition and restore the hard cut, routed by provenance: the outgoing layer's end shrinks back by extended_us (only borrowed tail is returned, never real content) and the incoming layer moves RIGHT by duration_us − extended_us, link siblings following. TransitionRestoreCollision when that destination has since been filled — move or delete the blocker first; the system never makes room. Recorded. TransitionNotFound for an unknown id.

Inputs: transition_id (required).

describe_clipA
Read-only

Describe a video's visual content as timestamped segments with a video-understanding model (local Qwen3-VL / MiniCPM-V, or an OpenAI-compatible endpoint). Name a pooled item by media_id (placed or not; the whole source by default) or a VideoClip by layer_id (the source it plays, plus its mapping, as analyze_clip's). Samples the window at fps (default 1.0), ≤3600 frames per call. Returns { backend, model, summary?, media_id, mapping?, segments: [{ src_start_us, src_end_us, text, tags }] }, source µs; text is prose, tags short visual keywords; long windows add a summary. Cached per source range, so a retry after a client timeout or an interruption resumes; refresh re-describes. src_start_us/src_end_us (e.g. a shot's) narrow the window; focus steers tags; language is BCP-47 (default: UI language). qwen3_vl and minicpm_v run on this machine; byo_endpoint UPLOADS frames — name it only with the user's consent. backend REQUIRES that engine, never substituting; omitted: the selected engine, then availability (local first).

Inputs: fps, focus, backend, refresh, +5 more.

detect_pausesA
Read-only

Find the pauses in the audio a clip plays — the stretches nobody is speaking — from the pre-computed waveform. Read-only: the writes are remove_pauses (cut them, or a reviewed subset via its pauses) and create_tacks (point the user at them). A pause is a run where every channel's peak stays below threshold_db (dBFS, default -34) for at least min_pause_us (default 500000); a louder run under 80 ms inside it (a click, a cough) does not end it. layer_id is an Audio layer, or a VideoClip, read through the linked Audio member that plays (refused when it plays no sound). Returns { pauses: [{ t_start_us, t_end_us }], noise_floor_db, peaks_source }, timeline µs, sorted; noise_floor_db is the 10th-percentile peak (null in silence; a threshold reads well 6 dB above it); peaks_source is "raw" or "fx" (baked effect chain). Refused (DerivativeNotReady with the waveform's state) until ready: retry after retry_after_s; failed names its reason.

Inputs: layer_id (required), min_pause_us, threshold_db.

end_agent_sessionA

End your work session and release its history lock; the view, activity, running tasks and connection stay. Only the owning connection may end it (begin_agent_session { force: true } takes over a stale one). Unless your last check_composition is current, the app audits first; hard or warning findings keep the session open (ended: false, held: "audit"): settle them and end again. Answers { ended, audit } (ended: the closed session, null with none), plus tacks_to_review when open tacks are outdated. Unrecorded.

Inputs: no named parameters.

export_captionsA
Read-only

The captions of a composition as a subtitle document — format srt or vtt — read from every caption lane (or one track_id) in time order, with the cue text as it stands. range (start_export's) clips cues to it and shifts them to 0, in step with a range export. Returns { format, cues, body }, plus the snapped range; write body to a file yourself. Records nothing.

Inputs: format (required), range, track_id, composition_id.

export_motifA
Destructive

Write a complete ZIP snapshot to path: an absolute app-machine .zip in an existing folder; an existing file is refused, never overwritten. Refuses invalid linked content.

Inputs: path (required), motif_id (required), expected_revision.

extract_clip_audioA
Read-only

Extract the ORIGINAL source audio that plays on a VideoClip or Audio layer (a VideoClip through its linked Audio member) — before gain, mute, effects or mixing — for an agent running its own speech model; no engine or API key is involved and nothing is uploaded. Returns a JSON metadata block (layer_id, media_id, t_start_us, t_end_us, src_in_us, src_out_us, duration_us, rate {num, den}, sample_rate_hz, channels, bits_per_sample, byte_length, mime_type) plus an MCP audio block: base64 WAV, mono 16 kHz 16-bit, starting at zero — about 2.6 MB of base64 per 60 s. Optional t_start_us/t_end_us are timeline µs, defaulting to the layer endpoints; at most 60 s of source audio per call (timeline windows ≤ 60 s / rate), so a long clip is several calls. Map a WAV offset w to the timeline as t_start_us + w / rate, then apply_transcripts. Refuses a layer that plays no sound and a window outside the layer.

Inputs: layer_id (required), t_end_us, t_start_us.

get_export_optionsA
Read-only

Read effective export settings and composition limits. Optional preset_id previews that preset without changing project settings; otherwise uses saved project settings, then the global default.

Inputs: preset_id.

get_export_statusA
Read-only

Read an export job as { job }. Omit job_id for the active job, else the most recent one; job is null only when none has run. wait_s blocks until its state changes. queued waits for resources; job.queued names the holders. Records survive MCP reconnects until the app exits.

Inputs: job_id, wait_s.

get_param_trackA
Read-only

Read a layer param's animation. track is exactly set_param_track's shape, to edit and send back as is: {"mode":"Static","value":v} or {"mode":"Keyframed","value":[{t_us, value, time_fraction?, in, out, continuity, segment}],"extrapolate"}, t_us timeline-absolute. Beside it, parallel to the keys: keyframe_ids (for update_keyframe / delete_keyframe), local_t_us (layer-local) and preset_ids (the easing preset the segment leaving each key matches, else null). in/out are tangents {x, y, mode} ("Auto" solved on write, "Free" authored); segment is {kind, …}, the class of the segment leaving the key — only Spline reads the tangents. An unset effect param reads as its catalog default. Position params are mode-specific: x/y in XY mode, path_progress in Path mode (a fraction).

Inputs: layer_id (required), param_key (required).

import_mediaA
Idempotent

Import media files: every path is checked first (a directory, missing or unreadable file refuses the call, nothing imported), then each is hashed, probed and copied into the project's Media/ folder. Returns { media: [record] } in path order, each the pooled record with derivatives; path / path_rel name the Media/ copy (copying: true while it lands). A pooled file answers existing: true (a repeat is harmless), a missing one now read from here relinked: true; same_content_as names copies of its bytes. .srt/.vtt/.ass pool for apply_subtitles; .svg rasterises to PNG. Unrecorded.

Inputs: paths (required).

install_motifA

Propose publishing a draft's expected_revision; the library is untouched until the user approves it in WeftCut's Motif panel. Answers {state: awaiting_approval, proposal_id, target: {id, version} | {new_id}}: tell the user to review it, do not poll. list_motifs shows the outcome. A new proposal from the draft supersedes the old. A new id is the name's; a taken one is refused (MotifIdTaken). To replace an installed Motif pass target_id and expected_version.

Inputs: motif_id (required), expected_revision (required), target_id, expected_version.

jump_toA
Destructive

Move the history cursor to the state right after op op_id (an ops[].op_id of project://history): the way to a state that is neither one undo away nor a checkpoint. An op the stack no longer holds is refused. A revert path like undo, so another session's history lock blocks it. Records nothing; a later edit drops whatever sat ahead, as after an undo. Answers at: the op the cursor now sits on.

Inputs: op_id (required).

launch_weftcutA
Idempotent

Launch the WeftCut desktop app (opens its GUI window on the user’s machine) and wait until its MCP endpoint is reachable. On success the full WeftCut tool catalog becomes available in this session automatically (tools/list_changed). Safe to call when already running — reports that instead of launching twice. Use after weftcut_status says the app is not running.

Inputs: no named parameters.

list_export_presetsA
Read-only

List built-in and personal export presets, complete portable settings, default ID and name limit. Available without a project.

Inputs: no named parameters.

list_motifsA
Read-only

List built-in, installed and draft Motifs with props schemas, revisions and diagnostics. A draft with a proposal carries publication {state: awaiting_approval|approved|rejected, note?, version?, rebound?}.

Inputs: status.

merge_captionsA
Destructive

Merge two or more captions of ONE caption lane into the earliest, as one recorded edit: its span becomes the union, its text the texts joined by a line break in time order, its style stays; the others are deleted. A gap between them is spanned. Refuses a layer that is not a caption, captions on different lanes, and a union that would overlap another cue of the lane (LayerOverlap). Returns the merged caption's record with removed.

Inputs: layer_ids (required).

move_effectA
Idempotent

Reorder an effect within its layer's chain. new_index is 0-based; 0 = first applied. Must be < effect count.

Inputs: layer_id (required), effect_id (required), new_index (required).

move_layersA

Move named layers in time and/or onto another track of the SAME composition, as one recorded edit. layer_ids[0] is the seed: land it with one of t_start_us (absolute) or delta_us, or with neither for a lane change alone. Every member keeps its offset on its own track, link partners included unless escape_link; track_id moves only the seed — a track of the same composition, or "spawn" for a fresh top track. insert: true is the ripple move: the set's span closes behind it and opens at its landing on every track, so a later landing is read with that span already closed; it refuses like delete_layers { ripple: true }. Each layer snaps on its own grid. A start before 0, an occupied landing (LayerOverlap) or a lock refuses whole. Returns { layers, rippled, track?, pruned_tracks }. Every layer from a time on: shift_layers; into another composition: move_layers_to_composition; drawing order against one layer: restack_layer.

Inputs: layer_ids (required), insert, delta_us, track_id, +2 more.

move_layers_to_compositionA

Move layers out of their composition into ANOTHER one: into a Group's composition, back out to the root, or between timelines. The anchor starts at t_start_us on the destination's clock; other members retain offsets. Lane assignment is per source track: omit to_track_id to find space, use spawn for fresh lanes, or name a free unlocked lane. Refuses mixed source compositions, locks, cycles, negative starts and membership changes involving retimed Groups. Internal links/transitions move; straddling ones are cut. Markers stay; compositions autofit; Group windows stay fixed. Within one composition: move_layers; into a Group keeping their place on the outer timeline: add_group_members.

Inputs: layer_ids (required), t_start_us (required), anchor_layer_id (required), to_composition_id (required), +1 more.

move_trackA
Idempotent

Move a track to a different z-order position, one recorded edit; 0 is the bottom of the stack, and the position must be below the track count (TrackPositionOutOfRange). Refuses a reserved A roll / B roll track (TrackReserved; they keep their place), a locked track (TrackLocked) and a track holding a locked layer (LayerLocked). One layer's drawing order: restack_layer.

Inputs: track_id (required), new_position (required).

open_motif_draftA

Open a draft; returns {motif_id, revision}. directory: a live linked folder (reopening returns its draft). motif: a draft id resumes that draft, any other id copies it. copy: an independent copy of any Motif, drafts included. Copies answer source {id, version}. empty: 960×540, 5 s, no props.

Inputs: source (required).

open_projectA
Destructive

Open a project folder (the one holding project.json) in the editor, as the start screen's Open does; only one the user asked for. The project open before is saved; its undo history is dropped. The folder already open is not reloaded and answers already_open: true. Recent projects: read_project { view: "session" }. Returns { name, dir, replaced, already_open }.

Inputs: path (required).

open_side_previewA
Read-only

Open the side preview: a page beside this chat, in a desktop host's built-in browser, with the timeline, play/pause/seek, export progress and, on request, a live picture of the edit. Use it when the user asks to open or see the preview; it is not for opening WeftCut, which is already running whenever this tool answers. Open the returned link in that browser, or give it to the user. A terminal has nowhere to show it. The page never edits the project. Returns { url }.

Inputs: no named parameters.

paste_layersA

Duplicate a set of layers as one recorded edit — the only copy tool. layer_ids[0] is the seed; land its clone with exactly one of t_start_us or delta_us (from the seed's start). Every other clone shifts by the same delta on its source's track; track_id moves only the seed's clone. Nothing is expanded: pass link partners to copy them. All-or-nothing: a locked or occupied destination refuses the batch (TrackLocked, or LayerOverlap naming the source). Two or more clones link to each other. A Group clone shares its composition unless unique. Returns { clones: [{ source, clone }], layers, groups? }; groups names each unique copy's composition_id.

Inputs: layer_ids (required), unique, delta_us, track_id, +1 more.

preview_motifA
Read-only

Render a Motif at each local_t_s as one labelled PNG contact sheet (frames keep their alpha), plus the exact revision and the canvas and frame sizes. Each frame is the whole canvas scaled to fit, never cropped. Refreshes this draft's linked files first; refuses an invalid directory or a stale expected_revision.

Inputs: motif_id (required), local_t_s (required), props, width, +2 more.

read_motifA
Read-only

Read manifest, revision and file inventory. With path: a UTF-8 file returns its text (max 256 KiB); a binary file returns only {size, sha256}. Includes working-directory diagnostics.

Inputs: motif_id (required), path.

read_projectA
Read-only

The project://* views as a tool result, for clients without resources. view: composition, compositions, media (with id, one item's card), tracks (layer envelopes), layer (needs id), markers, links, transitions, settings (preferences, role mix, metadata), history, session (work session), effects (catalog), tacks (review tacks; composition_id narrows), taste (style tokens + provenance), playhead (where the user is in the editor), media_thumbnail / media_frame (an IMAGE of media id; media_frame takes src_us). composition, tracks, markers, links, transitions take composition_id for a Group's (root if omitted). JSON views are text.

Inputs: view (required), id, path, src_us, +1 more.

redoA
Destructive

Redo the next edit. Errors with NothingToRedo if no redo is available. A new commit truncates the redo tail. Answers redone: the op reapplied.

Inputs: no named parameters.

remove_pausesA
Destructive

Cut pauses out of the audio a clip plays and ripple downstream, as one edit. layer_id is an Audio layer, or a VideoClip read through its linked Audio member; link members are cut together, on the frame grid when picture is linked. pauses cuts exactly those ranges (detect_pauses output, e.g. the subset the user kept); without it the clip is detected at threshold_db / min_pause_us (detect_pauses' defaults). pad_us keeps 100000 µs of each pause on each side; a pause at a clip edge trims whole. Returns { surviving_layer_ids, removed, removed_us }. To review first: detect_pauses, then one create_tacks batch. Refuses whole, before any write: RippleInsideHole (a layer on another track starts inside a pause), RippleCollision, RippleLinkStraddles, RippleLockedLayer / TrackLocked, InvalidArgument (pad too large, a pause outside the clip or overlapping another, a clip silent end to end).

Inputs: layer_id (required), pad_us, pauses, min_pause_us, +1 more.

rename_compositionA
Idempotent

Name a Group's composition (label: null or blank clears it back to the derived name). Recorded, so undo reverts it. The root composition refuses (RootComposition): it has no name — it is the timeline. Composition ids: project://compositions.

Inputs: composition_id (required), label.

rename_layerA
Idempotent

Rename a layer: label, or null to clear it. One recorded edit. Times are move_layers (start) and trim_layer (one edge); enabled / locked are set_layer_flags; kind-specific params are update_layer_params.

Inputs: label (required), layer_id (required).

rename_trackB
Idempotent

Name a track, reserved A roll / B roll / audio / caption tracks included. Recorded. label: null (or blank) clears it back to the derived name — its role, or its position in the stack.

Inputs: track_id (required), label.

render_framesA
Read-only

See the root composition as export renders it (footage, Motifs, text, captions and Groups composited) as JPEGs. Pass t_us, or layer_ids to judge beats over their whole span: each is sampled settled, in the middle, in its exit, and just after every cut or shot change under it. Returns one labelled contact sheet (default) or one image per frame, plus each time and why it was taken. Read-only; refused while an export runs, or (RendererCannotDraw) for frames with effects, crops or transitions the host cannot draw; without: ["effects"] skips effects. Seconds per frame.

Inputs: t_us, sheet, width, without, +1 more.

restack_layerA
Idempotent

Change drawing order: put a visual layer directly above/below an anchor layer or track, keeping its time. Supply exactly one anchor; track anchors work through gaps. A sole occupant carries its track; shared or reserved sources split onto a fresh track. Reserved tracks stay put. Audio, cross-composition and self-anchors reject. Already in place records nothing. One undo step. A time or named-lane move: move_layers; a whole track: move_track.

Inputs: layer_id (required), position (required), anchor_layer_id, anchor_track_id.

restore_checkpointA
Destructive

Restore a named checkpoint. Records a new history entry — undo will return to the pre-restore state. Errors with CheckpointNotFound if the id doesn't exist. The agent panel preserves activity and inserts a restore boundary; only edits with known history provenance are marked reverted.

Inputs: checkpoint_id (required).

restyle_to_tasteA
Idempotent

Reset Text and style Motif layers to the project's style tokens (project://taste), one edit: text takes its role's tokens (untagged: none), captions the caption tokens, a Motif its token-backed props. Select by exactly one of layer_ids, graphic_role, captions: true (the last two within composition_id). groups: look (face, size, colour, outline, shadow, box), position, motion (intro/outro); default look + motion (placement kept); position moves Text only. Returns { restyled, unchanged }.

Inputs: groups, captions, layer_ids, graphic_role, +1 more.

retime_layersA
Idempotent

Retime exactly these clips in one recorded edit, keeping their starts and source windows. target is an absolute Rate — source µs per timeline µs, so 2/1 plays twice as fast at half the length — or a Duration (µs). preserve_pitch sets the pitch policy of the Audio and Group clips among them (default true), with or without a target. Nothing is expanded: pass link partners too, or their A/V sync drifts; the answer's unretimed_partners names any left out. Atomic; refuses collisions, transitions, locks and nested targets. Returns { layers: [{ layer_id, t_end_us, duration_us, actual_rate, … }], unretimed_partners } after grid snapping.

Inputs: layer_ids (required), target, preserve_pitch.

retry_exportA

Retry only finalization of an awaiting_retry job. Optional filename changes the basename in the same directory; keep its extension.

Inputs: job_id (required), filename.

set_keyframeA
Idempotent

Insert or update one key on a layer param by time (t_us, timeline-absolute), snapped to the frame first: a key on that frame is updated in place, id kept. On a Static track the first key replaces the static value, which is not kept — key the start value too, or use set_param_track. value is typed by param_key: a number, or {r,g,b,a} (0..255) for "color"; an effect param needs no prior write and must sit in its catalog range. easing eases the segment leaving the key, or on the last key the one arriving at it; omitted, a new key inherits the easing of the segment it splits. Returns the key (keyframe_id, t_us, local_t_us). Sides, continuity, Auto tangents: update_keyframe.

Inputs: t_us (required), value (required), layer_id (required), param_key (required), +1 more.

set_layer_flagsA
Idempotent

Set enabled and/or locked on exactly these layers in one recorded edit; omit one to leave it alone, and name at least one. Nothing is expanded: pass link partners (link_id in project://tracks) to hide or lock a linked pair. enabled is the layer's output in preview and export. A locked layer refuses edits; its track's lock is separate (set_track_flags). A locked layer or track (LayerLocked / TrackLocked) refuses the visibility write for the whole batch: unlock in its own call first. Hide and lock is one call.

Inputs: layer_ids (required), locked, enabled.

set_marker_anchorA
Idempotent

Tie a marker to a clip so the mark FOLLOWS it through moves, trims, splits and composition crossings, or cut it loose with layer_id: null. layer_id must be a clip of the marker's own composition. Tying names the source instant the mark already sits on, so nothing moves; t_us stays the field to read. Refuses without writing: a layer in another composition (CrossCompositionSet), a kind with no source window such as Color or Text (WrongLayerKind), a marker outside the clip's span (InvalidArgument — update_marker it onto the clip first). Re-tying replaces the tie. Untying keeps the frame currently shown and is the one exit from hibernating; untying a free marker records nothing.

Inputs: layer_id (required), marker_id (required).

set_param_trackA
Destructive

Replace a whole param track in one undo step, discarding its keys: {"mode":"Static","value":v}, or {"mode":"Keyframed","value":[keys],"extrapolate"?} (Hold/Hold when omitted). A key needs only {t_us (timeline-absolute), value}; easing (as set_keyframe's) or in/out/segment/continuity shape the curve, else Linear. get_param_track's track is this shape and round-trips as is; IDs are generated, so omit them. Two keys snapping onto one frame are refused, naming both. A Text layer's static scale stays 1 (ADR 0049). Returns the committed keys {keyframe_id, t_us, value} and extrapolate, or the static value.

Inputs: track (required), layer_id (required), param_key (required).

set_positionA
Destructive

Replace a layer's position outright, motion included: XY tracks, or a motion path with a scalar progress track. Keys are timed local_t_us (layer-local) and need only local_t_us/value (Linear, identity tangents); nodes need only point (Line, Corner, zero handles); IDs are generated, so omit them. A static update_layer_params x/y also flattens XY animation; translate_position offsets it instead. One undo step; returns the position as committed.

Inputs: layer_id (required), position (required).

set_project_settingsA
Idempotent

Update the project's editing preferences; only the fields you send apply, and an unknown key or an empty patch is refused. Unrecorded — preferences are setup, patched into every history snapshot, so undo walks past them (the update_composition contract). Fields: auto_pair_audio_on_import, prefer_proxies, proxy_override, shot_review, pause_review (the last two validated and refused as a whole, against the detectors' own bounds; null clears one back to defaults). Returns { settings, changed }; changed names the fields that moved (empty: all already set). Read current values from project://settings.

Inputs: patch (required).

set_role_flagsA
Idempotent

Mute/solo an audio role; omit one flag to leave it alone, and name at least one. role ∈ {dialogue,music,sfx,voiceover}. Mute wins over solo; any solo silences non-soloed roles. Gates preview AND export. Unrecorded (undo does not revert it) and not in the review diff — restore the flags before handing back. A mix change the user reviews is set_role_gain.

Inputs: role (required), solo, muted.

set_role_gainA
Idempotent

Set an audio role's mix gain (dB). role ∈ {dialogue,music,sfx,voiceover}. Recorded (undoable). Folds into every layer of that role at mix time.

Inputs: role (required), gain_db (required).

set_track_flagsA
Idempotent

Set a track's enabled and/or locked flag; omit (or null) one to leave it alone, and name at least one. locked is what every TrackLocked refusal points at — a locked track rejects edits to its layers, and clearing it here is the fix. enabled is the track's output in preview and export; its layers stay put. A layer's own locked is separate (set_layer_flags), and an edit needs both clear. Mute/solo live on roles: set_role_flags. Unrecorded.

Inputs: track_id (required), locked, enabled.

shift_layersA

Shift every layer starting at or after t_from_us by one delta_us, as one recorded edit — on track_ids, or on every track of the composition. A positive delta opens room there (the ripple insert); a negative one closes [t_from_us + delta_us, t_from_us) the way delete_layers { ripple: true } closes a hole, refusing by the same names (RippleInsideHole: a layer starts inside the span; RippleCollision, RippleLinkStraddles, RippleLockedLayer) and keeping each carried transition. A link the sweep would split is ShiftLinkStraddles; a start before 0 refuses. Each layer snaps on its own grid. To move named layers, move_layers. Returns { moved: [layer records], delta_us }.

Inputs: delta_us (required), t_from_us (required), track_ids, composition_id.

split_layerA

Split at sorted, grid-snapped times in one atomic edit. Each half retains its mapped content window. Linked members are cut too and form a separate link per segment unless escape_link. Returns layer_ids, the actual t_cut_us and siblings: [{ layer_id, segments }], each link partner cut with it.

Inputs: layer_id (required), t_cut_us (required), escape_link.

start_exportA

Start an asynchronous export. Use one request_id per intent; reuse it when reconnecting. Settings, path, extension and an on_conflict: fail collision are refused before a job exists. get_export_status { wait_s } reports the actual completed path.

Inputs: range, settings, preset_id, request_id, +3 more.

synthesize_speechA

Synthesize speech with the configured cloud TTS provider (OpenAI tts-1; the text is uploaded) and place it as a voiceover Audio layer, one placement or none: a refused placement leaves nothing in the pool. text ≤ 4096 chars; voice; optional speed 0.25..4.0 (default ≈ 1.0); composition_id (default root); t_start_us (default: the composition's duration, so it appends); target_track_id, else the topmost unlocked track whose audio lane is free across the clip, else a new 'Voiceover' track. The MP3 is cached by (model, voice, speed, text), so a repeat costs no API request. Returns { layer_id, media_id, track_id, t_start_us, t_end_us, cached }.

Inputs: text (required), voice (required), speed, t_start_us, +2 more.

transcribe_clipA
Read-only

Transcribe the audio that plays on 1–20 VideoClip or Audio layers (a VideoClip through its linked Audio member). Returns { transcripts: [{ source: { layer_id, signature }, backend, segments: [{ t_start_us, t_end_us, text, words: [{ t_start_us, t_end_us, text }] }], language, word_timing }], failed? }, one per layer in order, timeline µs; hand transcripts to apply_transcripts as is. Cut pauses first, caption after: a clip changed since is refused there. failed lists layers that refused, with why. t_start_us/t_end_us narrow one layer's window. language is BCP-47; a model that does not cover it, or the language it detects, refuses with options. whisper_cpp and funasr run on this machine; openai (cloud) and byo_endpoint (the user's server) UPLOAD the audio — name one in backend only with the user's consent. Without backend the model selected in Settings runs, never another; if it cannot, the refusal names what it lacks and the ready engines. A retry after a client timeout joins the running job.

Inputs: layer_ids (required), backend, language, t_end_us, +3 more.

translate_positionA

Offset a layer's position by (dx, dy) composition px as one undo step, keeping its motion: in XY mode every x/y key (or the static value), in Path mode every node (handles and progress kept). Returns the position as committed, as set_position does. One static spot: update_layer_params x/y; new motion: set_position.

Inputs: dx (required), dy (required), layer_id (required).

trim_layerA
Idempotent

Trim an edge to t_edge_us. Source time follows the clip rate; keyframes remain glued to content. Aligned linked edges follow unless escape_link. Refuses targets outside the legal source/timeline window. Returns committed spans, trimmed siblings and grid adjustments.

Inputs: edge (required), layer_id (required), t_edge_us (required), escape_link.

undoA
Destructive

Undo the newest edit by anyone: history is shared, so it may be the user's — check undone.actor, and redo puts it back. NothingToUndo at the origin. Only timeline edits record — layers, tracks, markers, transitions, links, Groups, role gains (set_role_gain), and media removals that cascade. Outside the stack and untouched by undo: media imports, the composition envelope (update_composition), project settings (set_project_settings), track and role flags, and loading a project (which resets history). Answers undone: the op reverted.

Inputs: no named parameters.

ungroup_layerA

Expand a Group layer back into its members, in place. Refuses unless the Group is PLAIN — identity transform, static opacity 1, no effects (GroupNotPlain { reason }), because those apply to the composite and would be discarded; reset them first or keep the Group. Members intersecting the Group's [src_in_us, src_out_us) window are copied into the parent at the same on-screen time, trimmed to the window; members wholly outside are dropped. The composition's tracks become fresh tracks at the Group's z position; inner links and transitions carry over. The composition is removed when nothing else references it. One undo restores the Group.

Inputs: layer_id (required).

update_compositionA
Idempotent

Update a composition's envelope — canvas width/height, fps, sample_rate, channels, color_space, background, duration_us; only fields you set apply; composition_id names a Group's composition, the root when omitted. Unrecorded: the envelope is setup, so the patch reaches every history snapshot and undo walks past it. fps is LOCKED once the timeline, any history snapshot or any checkpoint holds a layer — refused with FpsLockedByContent { current, requested, layer_count, locked_by: "current" | "history" }; set the rate on a project that has never held a layer, or empty the timeline and reopen the project to clear a history lock. sample_rate is never locked. Setting duration_us PINS the duration so layer edits stop auto-fitting it; duration_us: null (alone in the patch) unpins it and refits to the layers.

Inputs: patch (required), composition_id.

update_effectA
Idempotent

Update an effect: patch is { enabled?, params? }, at least one; params merge key by key as plain numbers, null unsetting a key back to its catalog default. A value written to a keyframed param replaces its keys; animate with set_keyframe on effects[<effect_id>].params[<key>]. Unknown keys and out-of-range values are refused, never partially applied. Returns the effect record.

Inputs: patch (required), layer_id (required), effect_id (required).

update_export_presetA
Idempotent

Change a preset in one write: name and/or settings of a personal preset, and/or default: true on any preset, built-ins too. Pass at least one. Existing projects and admitted jobs keep their copied settings.

Inputs: preset_id (required), name, default, settings.

update_keyframeA
Idempotent

Change one keyframe by id in one commit — any of: t_us (move it, timeline-absolute, snapped to the frame; the track re-sorts; a frame another key holds is refused, KeyframeOccupied), easing (as set_keyframe's: the segment leaving the key, or on the last key the one arriving at it; read back in preset_ids), in / out (one side's tangent {x, y}, stored Free — x within [0, 1], y may overshoot — its segment becoming Spline; a side written on an Auto key frees the whole key), continuity ("Smooth" re-derives in from out, "Broken" changes no number), smooth: true (both sides Auto, solved on write and kept smooth as neighbours move; the adjacent segments become Spline). At least one; applied in that order, smooth alone or with t_us. Returns the key.

Inputs: layer_id (required), param_key (required), keyframe_id (required), in, +5 more.

update_layer_paramsA
Idempotent

Patch static fields of one layer; fields are kind-specific (schema variants). A static write replaces that field's animation, x/y included (Path mode refuses x/y: translate_position; new motion: set_position); set_param_track animates. scale_linked links the scale pair; while linked, one axis writes both. Text has no scale fields: resize its box. src_in_us slips the source window (span kept); retime_layers changes the rate. Returns the layer with params, each patched field as committed (values are quantized); locked layers and invalid values are refused.

Inputs: patch (required), layer_id (required).

update_markerA
Idempotent

Update a marker. Setting t_us re-sorts the marker list. On a marker ANCHORED to a clip, t_us names the time the mark should read and moves the ANCHOR to make it read that, so the mark keeps following its clip from the new offset — a time outside that clip's span is refused, and t_us together with t_end_us is refused (an anchored region's end follows its anchor by itself; patch one or the other).

Inputs: patch (required), marker_id (required).

update_motif_filesA
Destructive

Batch edit draft files; requires current expected_revision. Each entry replaces a file with text or base64 bytes (at most 4 MiB decoded per call), applies exact-match edits to an existing text file, or deletes a path. Prefer edits over resending a whole file. The whole package must remain valid. Linked drafts write through to their directory.

Inputs: files (required), motif_id (required), expected_revision (required).

update_tackA
Idempotent

Change a tack's label, body, kind or status — resolved once you fixed what it pointed at, dismissed when it no longer matters, open to raise it again. At least one field. Its place is fixed at creation; to move one, delete and create it again. Returns the tack as project://tacks reads it. Unrecorded.

Inputs: patch (required), tack_id (required).

update_transitionA
Idempotent

Patch a transition's duration_us, kind/direction and/or extended_us in one recorded commit; only fields you set apply. direction rides with kind: switching to Wipe/Slide needs both, and direction alone or beside Crossfade is rejected. Geometry is two targets: extended_us is the borrowed share of the overlap (0 = pure placement, duration_us = pure borrow); the outgoing layer ends at its exit frame + extended_us, the incoming starts duration_us before that. With extended_us OMITTED the trimmed ranges are preserved — growing moves the incoming layer further left and never borrows, shrinking returns borrowed tail first then moves it right. Only an explicit extended_us grows the borrow (checked against the remaining tail: TransitionInsufficientHandle { available_us }); a NEGATIVE one is a deliberate tail trim of real content. Link siblings follow the incoming layer; a move onto occupied space or across t = 0 refuses the commit. TransitionNotFound for an unknown id.

Inputs: transition_id (required), kind, direction, duration_us, +1 more.

weftcut_statusA
Read-only

Report whether the WeftCut desktop app is currently running and reachable, and which project it has open. Returns the endpoint state and what to do next when it is not running. Costs nothing; call this first when WeftCut tools appear to be missing or failing.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 101 tools

    Disambiguation4/5

    Tools are mostly partitioned by distinct resource and action, and many descriptions explicitly point to the right alternative for adjacent operations such as move_layers vs shift_layers vs move_layers_to_composition. Still, with 101 tools there are several closely related clusters around layer movement, group composition, review tacks, history, and export that can require careful reading to avoid misselection.

    Naming Consistency4/5

    Nearly all tools use snake_case and a verb_noun pattern, e.g. add_layers, trim_layer, create_tacks, update_export_preset. The main deviations are noun-first or brand-prefixed names such as weftcut_status, but overall the convention is predictable.

    Tool Count1/5

    At 101 tools, the surface is far beyond a well-scoped tool set and is an extreme selection burden for an agent. Even for a full video editor, this many operations should be consolidated or exposed through higher-level workflows.

    Completeness5/5

    The tool surface is exceptionally complete for a nonlinear editor: media import and analysis, timeline editing, tracks, layers, keyframes, effects, transitions, groups, captions, speech, markers, tacks, history/session control, motifs, and export are all covered. There are no obvious lifecycle gaps that would block an agent's core workflows.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that enables LLM agents to control the OpenCut classic video editor's timeline through a Playwright-controlled browser, allowing automated video editing tasks like adding media, inserting clips, splitting, trimming, and exporting.
      9
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents and MCP clients to programmatically edit video projects on a local desktop editor, with 119 tools for multitrack editing, effects, captions, audio, and batch auto-editing, producing reviewable and reversible real timeline edits.
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to drive a desktop video editor through MCP, providing the same editing operations as the user — placing, trimming, rippling, grading, captioning, and exporting — on the actual project with local rendering.
      8
      GPL 3.0