WeftCut
A full-control MCP server for the WeftCut desktop video editor: it edits a live timeline, analyzes media, transcribes/transcribes audio, builds code-based overlays, and renders/exports video.
App & project management — check/launch the app, open or create projects, read any
project://view (composition, tracks, markers, history, settings, taste, tacks, skill docs).Timeline editing — add, paste, move, shift, restack, trim, split, retime and delete layers; manage tracks, links, groups/compositions, and markers.
Keyframes & transforms — set/read/update/delete keyframes, replace whole param tracks with easing and Bézier tangents, animate or path-move position, patch per-kind layer params.
Effects & transitions — add, reorder, patch and delete effects (incl. chroma key, audio denoise); add/update/delete crossfades, wipes and slides.
Media — import video/audio/image/subtitles, force-delete media with cascade.
Footage analysis — shot detection and defect spans, frame comparison, audio waveform/onset analysis, pause detection, vision-model clip descriptions, raw audio extraction.
Speech & captions — transcription (local whisper.cpp/FunASR or cloud), TTS voiceover, lay transcripts/subtitles as caption layers, text correction, caption merging, SRT/VTT export.
Audio mixing — role-based gain and mute/solo.
Review workflow — agent sessions, checkpoints, undo/redo/jump, timeline craft audits, restyle-to-taste, and Tacks for time-ranged review comments.
Motifs — list, open, read, batch-edit, preview, publish, export and delete code-authored overlays.
Export — manage presets, inspect/override output settings, start/retry/cancel exports, poll status, and render preview frames.
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.

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
We don't have a verified macOS installer yet, so allow it under System Settings → Privacy & Security → Open Anyway
Download the installer for your platform from the releases page.
Install the app, open the settings panel, and copy the prompt that teaches your agent how to connect to WeftCut.
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 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;
},
});
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

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

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.

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 ( |
Preview | PixiJS v8 · WebGPU / WebGL · WebCodecs |
Export | Worker + |
Native core | Rust · napi-rs 3 · Tokio · imbl · serde · schemars · blake3 · reqwest · ffmpeg-sidecar |
Native decode |
|
Shared math |
|
ffmpeg | GPL CLI sidecar (jobs, encode, mux) · LGPL shared libs (in-process decode) |
Agent surface | MCP · streamable HTTP on localhost · stdio through the |
Motifs | Offscreen BrowserWindow · Chrome DevTools Protocol · |
Speech & vision | Cloud providers over reqwest · whisper.cpp · FunASR · on-demand model download |
Tests & CI | Vitest · cargo test · go test · Playwright · |
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 editorAlso 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.
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 toolsadd_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_audioARead-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_clipARead-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_shotADestructive
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_sessionAIdempotent
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_exportADestructiveIdempotent
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_compositionARead-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_framesARead-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_linkA
Create a new link from >=2 distinct layer ids. If any layer is already in another link, the op fails unless reassign=true, which removes them from their prior link(s) first (auto-dissolving any link that falls below 2 members). Returns the link record (link_id, members).
Inputs: layer_ids (required), reassign.
create_projectADestructive
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_compositionADestructive
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_effectCDestructive
Remove an effect from a layer by id.
Inputs: layer_id (required), effect_id (required).
delete_export_presetADestructiveIdempotent
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_keyframeADestructive
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_layersADestructive
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_linkADestructive
Dissolve (delete) a link. The member layers themselves are not deleted.
Inputs: link_id (required).
delete_markerCDestructive
Remove a marker.
Inputs: marker_id (required).
delete_mediaADestructive
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_motifADestructive
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_tacksADestructive
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_trackADestructive
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_transitionADestructive
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_clipARead-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_pausesARead-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_captionsARead-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_motifADestructive
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_audioARead-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_optionsARead-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_statusARead-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_trackARead-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_mediaAIdempotent
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_toADestructive
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_weftcutAIdempotent
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_presetsARead-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_motifsARead-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_captionsADestructive
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_effectAIdempotent
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_trackAIdempotent
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_projectADestructive
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_previewARead-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_motifARead-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_motifARead-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_projectARead-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.
redoADestructive
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_pausesADestructive
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_compositionAIdempotent
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_layerAIdempotent
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_trackBIdempotent
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_framesARead-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_layerAIdempotent
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_checkpointADestructive
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_tasteAIdempotent
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_layersAIdempotent
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_keyframeAIdempotent
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_flagsAIdempotent
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_anchorAIdempotent
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_trackADestructive
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_positionADestructive
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_settingsAIdempotent
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_flagsAIdempotent
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_gainAIdempotent
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_flagsAIdempotent
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_clipARead-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_layerAIdempotent
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.
undoADestructive
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_compositionAIdempotent
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_effectAIdempotent
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_presetAIdempotent
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_keyframeAIdempotent
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_paramsAIdempotent
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_linkA
Change a link in one recorded edit — any of: add_layer_ids (join layers; one already in another link is refused unless reassign is true, which pulls it out of its old link first, dissolving that link if it falls below two members), remove_layer_ids (drop members; below two, the link dissolves). At least one. Applied add → remove. Every layer must be in the link's composition (CrossCompositionSet). Create with create_link, delete with delete_link.
Inputs: link_id (required), reassign, add_layer_ids, remove_layer_ids.
update_markerAIdempotent
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_filesADestructive
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_tackAIdempotent
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_transitionAIdempotent
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_statusARead-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
Scored across 101 tools
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.
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.
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.
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
Related MCP Connectors
Compose, edit and render video with your AI agent. Turn footage into finished edits with content-aware reframing, word-timed captions and motion graphics. Hosted MCP with OAuth sign-in; cloud processing uses credits.
AI video editor for agents and humans: timeline, captions, color, audio and generation as MCP tools.
Hosted video MCP server for branded explainers and reference-driven edits.
A video editor in your browser that your AI drives: cuts, captions, multicam, motion titles, export.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP 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.9MIT
- AlicenseAqualityDmaintenanceGive any MCP client a real video editor — 32 typed tools over ffmpeg, Whisper and MediaPipe, plus an optional local UI with a drag-and-drop timeline.38MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceEnables 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.8GPL 3.0