Valmera — AI video editor

Valmera is a hosted AI video editor for footage you have already recorded.

CommunityOnlineNo sign-inGlobalFreeRead-only

What it can do

  • List Projects: List this account's video projects, newest first, with whether each has a video, its project kind, its podcast-shorts status, and which parent generated a short. The navigation-pointer
  • Open Project: Open a project for navigation and return its full state: the video, its transcript and shots, the current EDL and what is available to place. Copy this project_id into every later projec
  • Open Short: Open one generated short for DIRECT editing by this MCP caller. Select it by its 1-based board card number or child project ID; copy the returned child project ID into every normal editor

What data it sees

Do you need an account

No: the server works without sign-in

Valmera is a hosted AI video editor for footage you have already recorded. Its MCP integration lets an enabled account connect a compatible AI assistant to video projects, make direct editing changes and inspect the resulting timeline or rendered preview.

Use it for tasks such as trimming selected sections, adjusting cuts and reframing footage. Edits are stored in a versioned edit decision list; the uploaded source file is not modified. Review the timeline and preview before accepting an edit.

Final delivery: the user starts the final MP4 export in Valmera Studio. MCP cannot initiate final exports or delegate editing to Valmera’s in-house agent. An authorized client can retrieve an existing final.

Connection and access: the remote endpoint uses Streamable HTTP and OAuth. Access depends on account enablement, client authorization and editing entitlement; available tools can vary with service configuration. AI editing uses usage credits, and new paid checkouts have no free trial. See Valmera’s connection guide for current access requirements.

Valmera edits existing footage. It does not generate an entire video from a text prompt.

How to connect

How to connect Valmera — AI video editor to Claude

The server address to paste into Claude settings:

https://video-editor--valmera.run.tools

  1. Open Claude (claude.ai or the desktop app).
  2. Go to Settings → Connectors.
  3. Click Add custom connector.
  4. Paste the server address copied below into Remote MCP server URL and click Add.
  5. In a chat, click + → Connectors and switch the new connector on.

Custom connectors are available on Free, Pro, Max, Team and Enterprise plans (Free is limited to one). On Team and Enterprise an organization Owner adds the connector first under Organization settings → Connectors.

Authorization

After you click Add, a sign-in window for the service opens. Sign in with your own account and approve access. Claude never sees your password.

How to connect Valmera — AI video editor to ChatGPT

The server address to paste into ChatGPT settings:

https://video-editor--valmera.run.tools

  1. Open ChatGPT in a browser (chatgpt.com). A Plus, Pro, Business, Enterprise or Edu plan is required.
  2. Turn on developer mode once: Settings → Apps → Advanced settings → Developer mode.
  3. Open Settings → Connectors and click Create.
  4. Fill in the form: Name (anything), Description (one line about what the service does), MCP server URL (copy it below).
  5. Under Authentication choose OAuth if the service requires sign-in, otherwise None. Click Create.
  6. In a new chat open + → Apps/Connectors and enable the connector.

OpenAI has renamed this section before (Connectors → Apps/Plugins). If the label differs, search settings for "developer mode". On Business/Enterprise workspaces an admin must allow custom connectors first.

Authorization

On first use ChatGPT opens the service's sign-in window. Sign in and approve access.

How to connect Valmera — AI video editor to Cursor

The server address to paste into Cursor settings:

https://video-editor--valmera.run.tools

Fastest: click Open in Cursor below and confirm the prompt.

Manually:

  1. In Cursor open Settings → Cursor Settings → MCP and click Add new global MCP server.
  2. Paste the JSON copied below into ~/.cursor/mcp.json (per project: .cursor/mcp.json in the repo root).
  3. Save the file. The server appears in the MCP list; authorize it there if asked.

Authorization

If the service needs sign-in, an authorize button appears next to the server in the MCP list.

Server tool list (60)

Raw names from tools/list. Only developers need these.

list_projectsList this account's video projects, newest first, with whether each has a video, its project kind, its podcast-shorts status, and which parent generated a short. The navigation-pointer label is informational only; every project-targeting call still requires project_id. Start here.
open_projectOpen a project for navigation and return its full state: the video, its transcript and shots, the current EDL and what is available to place. Copy this project_id into every later project-scoped call; no edit or review tool guesses from the active pointer.
open_shortOpen one generated short for DIRECT editing by this MCP caller. Select it by its 1-based board card number or child project ID; copy the returned child project ID into every normal editor tool for exactly the same capabilities as Valmera's own agent. This does NOT call or delegate to Valmera's agent. Use this, then watch_video and the normal editing tools, when the user says YOU should edit a short. card requires parent_project_id; a direct child_project_id resolves its own parent and never trusts the active-project pointer.
create_projectCreate an empty project and select it for navigation. Copy the returned project_id into every later call. Upload a video into it with upload_start, or build a canvas program from generated/uploaded assets. kind='shorts' creates a Podcast to Shorts intake project. After its main video finishes analyzing, read the podcast and call make_shorts with your explicit story arcs; selection does not start automatically.
project_stateRe-read one explicit project's state (video, transcript, shots, current EDL, assets). Cheap — call it whenever you are unsure what the edit currently looks like.
upload_startBegin uploading a LOCAL file into an explicit project. Returns presigned URL(s) you upload the bytes to yourself (curl), then call upload_finish. kind: 'original' the main video, 'clip' b-roll, 'music' audio, 'image' a still. A clip may instead be marked role='shorts_reference' for reference-only Shorts style analysis.
upload_finishFinish an upload once every byte is in storage. For a main video this starts the analysis (transcript, shots, silences) — poll index_status until it is done.
index_statusProgress of an explicit project's video analysis. The editing tools cannot read a transcript, shots or silences until this reaches 'done'.
shorts_statusRead an explicit project's Podcast to Shorts progress, planner job, generated child project IDs, edit versions, and final-render states. Safe to poll while clips are being built. If project_id names a generated short, this reports its parent run and preserves that explicit child identity in the answer.
wait_for_jobWait for a background job (a render, or a tool call that outran its reply) and return its result. Safe to call repeatedly — each call waits a bounded time and tells you whether it is still running.
download_urlA temporary URL for watching or downloading a render of an explicit project, with a durable receipt. asset_id recovers a historical render. kind 'preview' (complete draft/approval), 'preview_check' (changed sections), or 'final' (an existing Studio or Shorts export). This tool cannot create a final export.
watch_videoWATCH THE VIDEO YOURSELF — the real file, pixels and audio, not a description of it. Use this instead of look_at whenever your own model can take video input: look_at sends frames to Valmera's vision model and hands you back a PARAGRAPH, while this hands you the footage. kind 'timeline' (default) is the assembled program as the viewer sees it — it renders the current edit first if it has not been rendered; 'source' is the raw uploaded footage; 'asset' is one uploaded clip (pass asset_key). start/end watch a window rather than the whole thing. It comes back as a direct download link — a plain MP4 you fetch and watch. Cheap: normally it hands over a file that already exists, untouched.
get_video_infoPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Video metadata plus index and EDL summary. Use only when the supplied project state does not already answer the metadata question.
get_transcriptPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Sentence-level SOURCE transcript with timestamps for a time range (source seconds). For word-exact timing use get_words; for what the current EDIT keeps, use get_kept_transcript. Pass asset_key to read an UPLOADED clip's or song's own transcript instead (clip seconds).
get_kept_transcriptPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. The transcript the CURRENT edit actually keeps, in program time with matching source spans, plus automatic repeated-phrase detection. ALWAYS call this after cutting repetitions or tightening — it is how you verify nothing repeated survived.
get_wordsPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Word-level timestamps [{t0-t1 word}] for any source-time range (the response caps at 400 words and says how to page for the rest). THE source of truth for cut points inside a sentence — never estimate word timing from sentence ranges.
search_transcriptPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Find where something is said (substring + fuzzy over sentences).
get_shotsPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Shot boundaries (scene changes — where transitions may land) for a time range. The PICTURE itself is in your filmstrips and look_at.
get_editorial_mapPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. READ: compact cross-modal SOURCE timeline joining each sentence (or shot when there is no speech) to overlapping shot changes, relative energy/trend, beats, vocal stress, pauses and measured face/source-text/dense-UI evidence. Use this instead of separately re-reading transcript + shots + audio analysis when directing a substantial reel, podcast, montage or B-roll/SFX/motion treatment. It aligns evidence but does not recognize the full picture or prescribe effects: inspect filmstrips/look_at before visual choices. Pass asset_key for an indexed uploaded clip. focus can be all, story, visual, energy, faces, ui, quiet or peaks.
find_visual_momentsPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. READ: focused semantic search across the COMPLETE indexed main-video filmstrip. Use once for a long source when requested highlights are visual rather than transcript-searchable (gameplay saves/fails, a gesture, a product appearing, action moments). query names one concrete visible event. It returns coarse SOURCE timestamps after scanning all tiles in parallel; verify useful candidates with ONE batched look_at call, then WRITE. Never replace it with serial whole-video look_at probing.
read_skillPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Load a focused editing playbook (captions, zooms, audio, transitions, ...) into this turn. The SKILLS list in your instructions names them. Read the matching skill before your first edit of that kind — batch it with your other reading calls. Pass section to retrieve only the decision, evidence, pattern, failure, verification, or repair material needed now.
expand_toolsetPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Load additional tool schemas for the NEXT reasoning step when the compact catalog does not expose a capability you need. This changes no media or EDL and is not a tool limit: request any relevant domains, then continue immediately.
find_silencesPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Silences of at least min_seconds, with midpoints and surrounding words — cut points should snap to these midpoints or word boundaries.
list_assetsPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Every file in this project — used on the timeline AND unused uploads sitting in the library. kind='music' lists audio (use its storage_key with add_music or add_voiceover); 'clip' lists uploaded video clips and 'image' reference images (use with insert_media); 'render' past renders; 'all' everything. UNUSED files are marked AVAILABLE and can be placed without asking the user to re-upload.
compare_uploaded_mediaPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. YOUR OWN EYES on SEVERAL uploaded clips/images in ONE story-wide comparison. Pass every relevant exact storage_key together; each candidate is represented on dynamically built labeled pages, with representative real frames, CLIP seconds and exact sentence/shot IDs. Use this instead of serial look_at_asset calls when choosing/order-casting a reel, montage, B-roll library or multi-clip story. It does not rank by upload order, does not silently shortlist, and explicitly allows leaving a weak/redundant asset unused. Then use source_asset_key + the returned evidence_ids in sequence_map.
open_visual_pagePROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Open one or more labeled pages from the main footage's persisted hierarchical visual storyboard. The full text inventory names every cluster; use this whenever you need the actual pixels for an evidence_id not present in the initial orientation page. Pages are transport batches, not an editorial allowance: call repeatedly and open as many as the edit requires. With pages omitted, opens every page not yet delivered in this logical turn.
look_atPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. YOUR OWN EYES on the footage. Pass times=[...] (1-8 exact source seconds of the MAIN video) and the frames at those moments come back as ONE timestamp-labeled picture in your own context — you see the footage yourself and judge it directly (composition, where the subject is, clear space for text, what a moment looks like). Every frame carries a faint tenths grid ((0,0) = top-left): READ aim points, cx/cy and rects off its labels instead of estimating. start/end still work as a range sampled evenly. OR pass output_times=[...] to see the ASSEMBLED PROGRAM instead: output seconds of the current edit, resolved through the EDL — kept footage AND spliced inserts both sample correctly, each tile labeled with its scene number, in TRUE output geometry (canvas fit and any active zoom applied — so you can SEE an aimed zoom's framing before rendering) — THE way to check what the viewer sees at a moment of the EDITED video ('the second scene') without rendering. Look as often as you need — there is no cap on looking; before aiming anything and before disputing what a user saw, look. Batch the moments you need into ONE call with several times rather than a string of separate calls. The filmstrips already gave you the whole video at a glance — use look_at for the CLOSER look: exact framing, small text, a precise instant. The transcript is ASR and can be wrong; inspect confidence and sentence context using get_words / the transcript — never look to lip-read or guess a word. IMPORTANT: the assembled geometry view omits burn-ins. Set rendered=true after render_preview to inspect the CURRENT preview's real pixels—including captions, text, overlays and grade. In rendered mode output_times (or times) are output seconds and any useful set can be batched for caption QA.
look_at_assetPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. YOUR OWN EYES on an UPLOADED clip or image, or a finished RENDER (storage_key from list_assets; kind='render' lists past previews/finals). Same contract as look_at: pass times=[...] (seconds into the clip) and the frames arrive as one labeled picture you read yourself, with the same tenths grid for reading positions. THE way to choose which moment of a long clip to splice in — one call over the whole clip, then insert_media with clip_start_s at the moment you saw. On a RENDER it is how you CHECK YOUR OWN WORK at exact moments — narrow times sample frame-accurately, so use it to verify a transition junction or an effect the user questions before claiming it is fine. For video clips it also returns a cached, measured temporal profile (static/frozen share, motion intensity and abrupt changes). This is sparse measurement—not continuous playback—and remains available on later turns.
keep_segmentsPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. REPLACE the whole keep list: the parts of the SOURCE video that survive, [[start,end],...] in seconds. Everything else is cut. Use only for wholesale restructuring, always after get_edl — for local fixes prefer cut_range/restore_range. snap_to_words:true moves boundaries outward to word edges so no word is clipped.
cut_rangePROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Remove ONE source-time range from the current keep set (a local edit — the rest of the edit is untouched). Creates a new EDL version. snap_to_words:true keeps neighbouring words whole. SOURCE seconds of the main video ONLY — when the user gives times of the EDITED video ('cut 12-15 of the video'), or the span sits inside an inserted clip, use cut_output_range.
cut_output_rangePROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Cut a span of the ASSEMBLED program — OUTPUT seconds, the clock the viewer and the scene map use — no matter what plays there. Kept footage under the span is cut in source time; an inserted clip it crosses is SPLIT around it (or removed when fully covered); one version write, everything re-anchored. THE tool for 'cut 12-15 of the video' / 'cut that part of the second scene' — never answer that cutting inside an insert is impossible, and never fake it with set_insert_window (that changes WHICH part plays, it cannot remove a middle). One range per call; batch several calls for several ranges.
restore_rangePROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Add a previously-cut source-time range back into the keep set (undo one cut without touching the rest). Creates a new EDL version.
cut_silencesPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. ONE-CALL silence trim — THE tool for 'cut the silences' / 'tighten this up' / 'remove the dead air'. Cuts every detected pause at least min_silence_s long (default 0.5s), keeping padding_s (default 0.12s) of breathing room around speech and snapping to word edges so no word is clipped. Do this in one call instead of many cut_range calls; then get_kept_transcript to verify. If at least half of the gaps contain audible material and the pass would remove 25%+ of the program, it refuses without changing the EDL. Set allow_nonquiet=true ONLY when the user explicitly permits discarding those non-speaking music/game/room-performance moments.
remove_filler_wordsPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. ONE-CALL filler removal — THE tool for 'remove the ums' / 'cut the uhs' / 'take out the filler words'. Cuts every um, uh, er, hmm, etc. using the exact word timestamps (deterministic, never estimated). Pass a custom `words` list to target different tokens (e.g. ["like","you know"]) — the default set is only the safe non-word hesitations.
add_captionsPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Burned captions. mode='from_transcript' (word-timed from the real transcript, recommended) or mode='off', or items=[{text,start,end,style?}] (source seconds) for text the user dictates. PREMIUM PRESETS (style.preset) are professionally designed looks with real fonts. SAFE DEFAULTS: 'clean' (white Plus Jakarta Sans, complete short phrases, size-only hierarchy), 'documentary' (restrained subtitles on a translucent contrast panel), and 'broadcast' (left-aligned news/explainer lower third). SOCIAL/CREATIVE: 'reels' (FLAGSHIP short-form system: tight two-line hierarchy, warm hero word and multi-stage elastic word landings), 'podcast' (bold white words land on screen as spoken, keywords light up in the accent color, get a highlight box or serif italics, numbers render HUGE), 'beast' (loud MrBeast-style: ALL-CAPS impact font, centered, the spoken word pops in the accent color), 'karaoke' (an accent box follows each spoken word), 'spotlight' (ONE glowing word at a time, centred, uppercase — the modern single-word look for hype/motivation/fast talking; the ONLY preset that belongs mid-frame), 'elegant' (calm lower-third, serif-italic accents — interviews/luxury), 'lyric' (phrase-led music/quote typography), plus stacked/iridescent/chrome/editorial/fashion/luxe/impact/retro/neon composed looks; 'classic' is the plain legacy look. If style is omitted, the tool chooses a coherent preset deterministically from the measured format, speech pace and brief — it does not make every project wear the same caption skin. PLACEMENT: multi-word presets default to the BOTTOM, clear of the face — do not move them to 'middle'; only a single-word-at-a-time look may sit centred. With a preset, sparse emphasis is AUTO-SELECTED from the KEPT transcript when emphasis_words is omitted; measured vocal stress leads on short-form/cached audio, with numbers and semantic outcome words as fall
find_songPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Find web links for a SPECIFIC song the user NAMED ('add Blinding Lights by The Weeknd') — the case a generic catalog cannot serve, because named commercial tracks need exact discovery. Returns candidate links best-guess first; pick the real thing (artist's own/'- Topic' channel or 'Official Audio'; no lyric/sped-up/loop/cover versions unless asked; never a full album/mix — one track only), then fetch_url(url, as_kind='music') downloads the pick. Always tell the user which version you grabbed. Search can verify the likely recording, NOT a usage license; a public/downloadable upload does not grant republication rights, so disclose that. For a genre/vibe request ask for a user-supplied file or link; a trending platform sound can only be provided by the user.
add_musicPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Mix music into the edit. The defaults are CONTEXT-AWARE: under speech the track sits low as a bed (-18dB, ducked); when NO speech survives under the window the music is the LEAD audio (-4dB, no ducking) so the user actually hears it. Pass gain_db/duck only to override that. storage_key is an exact key from list_assets(kind='music') — the user's own uploads or a track fetch_url just downloaded — never invent one. Choose from the user's direction, metadata, context and measured get_audio_analysis evidence. start/end are OUTPUT-timeline seconds and DEFAULT TO THE WHOLE VIDEO, so omit them for 'add some music'. Fades in/out by default. loop=true (the default) repeats a short track to fill the span; offset_s starts partway into the track, e.g. to skip a slow intro. Ducking is SMOOTH by default (a sidechain dip that follows the voice; set_music_fit(duck_mode='step') restores the legacy hard -12dB duck).
extract_audioPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Take ONLY the sound out of an uploaded VIDEO and save it as an audio file — THE answer to 'use the song from this clip', 'put this video's audio on my video', 'I want the sound but not the picture'. Users hand you songs as videos because a TikTok or Reel download is the only file they have; that is normal and it works. The clip's picture is never shown. asset_key is a [video_clip] storage_key from list_assets. Returns a new storage_key for add_music / add_sfx / add_voiceover — nothing is in the edit until you place it. Passing a clip's key DIRECTLY to those tools does the same thing in one step; call this when you want the file first (e.g. to get_audio_analysis its beats). If the clip is silent it says so — never claim a sound was added.
find_footagePROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Find REAL footage of a NAMED topic on the web — the b-roll move: the speaker mentions Elon Musk, the cut shows his rocket. Query the concrete THING ('spacex starship launch', 'tesla factory'), not a mood — search_stock covers generic visuals ('busy city'), THIS covers named people, companies, products, events. Returns candidate links best-guess first; pick real footage of the subject (short clips), then fetch_url(url, as_kind='clip'), look_at_asset for the right seconds, and a cutaway or insert at the mention. Tell the user what footage you used (title + channel).
search_sfxPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Search the web for a REAL recorded sound effect — the editor's whoosh, camera shutter, UI click, pop, riser. Query by the sound's PHYSICAL name ('whoosh', 'camera shutter', 'keyboard click'), not a mood. Results carry duration and license terms (public domain, credit, or NON-COMMERCIAL-ONLY) — relay the terms. max_seconds caps length (default 15s; one-shots are seconds long).
audition_sfx_candidatesPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Compare multiple search_sfx candidates using their ACTUAL waveform before choosing. Measures attack, peak position, tail, crest, spectral balance, bass and whether the file contains one clean event or several. Ranks those facts against a named physical/editorial purpose. The language model does not hear the recordings; use this evidence together with title/license, then fetch and place the winner exactly on the visible event.
fetch_sfxPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Download ONE search_sfx result (by its id) into the project — returns the storage_key for add_sfx. Repeat the license line to the user when it carries an obligation.
add_web_sfxPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. ONE-CALL on-demand sound design: search real Openverse/Freesound recordings, rank clean physical one-shots above loops/music/ambience, DOWNLOAD and acoustically compare the candidates. By default an actual-audio reviewer may choose KEEP THIS MOMENT DRY when every sound weakens it; pass allow_none=false only when the user explicitly requires an effect. Otherwise the tool fetches the best measured/listened match and places it at an exact OUTPUT-timeline second. Use for 'add a cinematic whoosh at 3.2s', 'put a shutter on this cut', or any specific requested sound. The result reports the real source and license. gain_db defaults -6; max_seconds defaults 15.
add_sfxPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Punctuate a MOMENT with a one-shot sound effect — a whoosh on a cut, a click on a beat, an impact on a reveal. Choose it when the brief, format, timing, or your editorial judgment says sound design improves the cut. Analysis, metadata, and deterministic preview AUDIO CHECK are useful evidence; uncertainty is something to judge rather than a reason the tool becomes unavailable. storage_key is an exact key from fetch_sfx or list_assets(kind='music') — never invent one. `at` is an OUTPUT-timeline second (the edited program, not source time). This is NOT background music: it plays once, for as long as the sound is, and never ducks. offset_s starts inside source audio — use it when an extracted clip contains the requested hit late in a long track. purpose records the nameable visible/editorial event for later final-mix review; do not add anonymous decorative sounds. Default -6dB.
move_sfxPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Retime an existing sound effect — 'the whoosh is too early'. Keeps which sound and how loud. id from get_edl.
remove_sfxPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Delete a sound effect by id (from get_edl).
swap_musicPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Replace the TRACK of an existing music item while keeping its position, level and fit — THE tool for 'use a different song' / 'try something more upbeat'. id from get_edl; storage_key as for add_music.
set_music_fitPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Retime or refit EXISTING music in place — 'start the music later', 'let it run to the end', 'fade it out', 'loop it', 'stop it ducking'. Anything you omit is left alone. duck_mode: 'smooth' = a sidechain dip that follows the voice and swells back in the gaps; 'step' = the legacy hard -12dB duck. Use this instead of remove+re-add, which loses the other settings. For loudness use set_audio_gain.
remove_musicPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Remove one background-music item by its id (see get_edl). Use this to cut the music entirely or before re-adding it with a different range.
set_audio_gainPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Change the loudness of an EXISTING music, sound-effect or voiceover item without re-adding it — THE tool for 'lower the music' / 'make the narration quieter' / 'that whoosh is too loud'. kind: 'music', 'sfx' or 'voiceover'; id from get_edl; gain_db e.g. -12.
set_caption_stylePROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Change how existing captions LOOK without touching their text or timing. Pass only the fields to change: 'make the captions premium/viral' -> {"style":{"preset":"clean"}} (see add_captions for the preset menu: clean/documentary/broadcast/podcast/beast/karaoke/spotlight/elegant/stacked/.../classic), 'make it red' -> {"style":{"color":"#FF0000"}}, 'center the captions' -> {"style":{"position":"middle"}}, 'bigger / more dynamic captions' -> {"style":{"size":"xl","dynamic":true}} (dynamic = legacy karaoke without a preset; presets animate on their own). highlight_color changes the accent of emphasized/spoken words; uppercase forces casing; emphasis_words (top-level arg, with a preset) replaces the emphasized keyword list. An explicit position or anchor_y locks captions there for the whole video and removes any old shot-aware placement track — use this when the user says captions must stop moving. For fine size control that the s|m|l|xl buckets can't hit pass size_scale (0.5-3.0; 1.5 = 50% bigger). Outline, shadow, backing panel, tracking and text alignment are independently editable. For transcript captions, single_line:true overrides any preset stack and guarantees one rendered row per state. Works for from_transcript and manual captions; errors helpfully if no captions exist yet.
set_volumePROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Volume automation on the ORIGINAL footage's audio (the speaker) over a SOURCE-time span. NOT for music or voiceover loudness — use set_audio_gain for those.
set_framePROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Set the output aspect ratio for every render. ratio: source, 16:9, 9:16, 1:1 or 4:5; mode: crop (default), pad (black bars) or pad_blur (blurred backdrop). focus_x/focus_y aim the CROP at the subject (fractions of the source frame, (0,0) = top-left) — without them the crop is the dead-center window, which chops an off-center speaker. For 'make it 9:16' on real footage PREFER auto_reframe, which measures the subject and sets the focus for you. Never upscales beyond the source's pixels. focus_track replaces the complete per-shot track: [{t0,t1,x,y,mode}] in SOURCE seconds. Read get_edl(frame) first; change only the desired spans. Tracks survive trims and speed changes.
auto_reframePROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. THE tool for 'make it 9:16 / vertical / for TikTok'. It samples frames across the kept footage and MEASURES two things before writing the frame: where the subject is (faces found in the pixels; vision or a detail-energy estimate only when there is no face), and whether a crop is the right operation at all — how much of the picture's detail would survive the crop window. With mode='auto' (default) footage with a subject gets a crop aimed at it, and footage whose content runs to the edges (gameplay, screen recordings, wide scenes) is FITTED into the new frame over a blurred backdrop so nothing is cut off — cropping those is the 'it just truncated my video instead of adjusting it' complaint. Pass mode explicitly to force one. Read what it reports and repeat THAT.
start_media_sequencePROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Start a NEW media-only sequence from one uploaded video clip or image, replacing the current programme in ONE valid append-only EDL write. Use this when the requested story should be assembled from uploaded assets instead of the project's main video. This is the safe first operation in an atomic recipe: it never creates an invalid empty timeline. Add later scenes with insert_media. Every earlier EDL version remains recoverable. duration_s and clip_start_s select a video window; motion/fit match insert_media.
insert_mediaPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Splice an uploaded video clip or image INTO the edit at ANY position in the FINAL edited video — mid-take positions split the take cleanly at a word edge, so 'in the middle of the talk' works exactly. NEVER splice a clip the user sent as a STYLE REFERENCE ('watch this', 'make it like this', 'use this as reference', 'recreate this', a YouTube they asked you to study) — look_at_asset it, extract_audio / add_music if they want THAT song, and rebuild the look from the MAIN gameplay/footage. If the studio already placed a reference on the timeline, remove_insert it. Call list_assets(kind='clip') or kind='image' first and pass the exact storage_key. duration_s: how long the insert plays (image default 3.0s; a video defaults to its available length). clip_start_s: where in the source clip the window starts — use look_at_asset to pick the right moment. motion: 'zoom_in', 'zoom_out', 'pan_left' or 'pan_right' gives either a still or a video insert its own slow local camera move without changing timing or audio. Use it deliberately to direct attention, not on every shot. Inserted media is NOT transcribed — captions cover the main footage only. fit defaults to 'auto': the WHOLE asset is preserved (black bars when the program frame is already pad; a blurred extension otherwise) so a portrait card cannot be center-cropped into an empty middle band. Pass fit='pad' for solid black; never use blur when the user asked for black. fit='crop' fills edge-to-edge. Assets may be reused whenever the edit benefits from repetition or a different source window.
compose_panelsPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. PROJECT-SCOPED: build ONE 16:9 clip that shows 2 or 3 independent videos side-by-side on a solid BLACK canvas — the signature multi-panel athlete/action wall. Do NOT fake this with pad_blur inserts plus small PIP overlays. columns is either a list of 2–3 asset_keys or a list of columns, each a list of {asset_key, start, duration} clips that play in that column (when one clip ends the next one in that column starts). duration_s caps the result (1–20s, default 8). The file is saved as a video_clip and is NOT in the program until insert_media (use fit='pad'). Audio is omitted — add_music for the bed.
set_insert_windowPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Change which part of an already-spliced clip plays, IN PLACE — duration_s for how long it runs, clip_start_s for where in the clip it starts, rate for how FAST it plays. USE THIS instead of remove_insert + insert_media to trim or re-window a clip that is already on the timeline: removing and re-adding costs two edit versions and two renders, and the user watches their clip disappear and come back. rate (0.25-4, round 76) is THE tool for 'speed up that scene instead of cutting it': rate alone keeps the clip window and shortens the block (a 10s screen recording at rate 2 becomes a 5s scene with nothing lost, audio pitch-corrected); with duration_s the block is duration_s long and consumes duration_s*rate of clip. TO SPLIT a spliced clip in two: shorten it here to the first part, then insert_media the same asset_key at the SAME at_output_s with clip_start_s set to where the first part ended — the two halves play in the order you created them. crop=[x0,y0,x1,y1] (round 77) shows ONE REGION of the clip as the whole scene, letterboxed (black bars) — THE tool for 'show the full timeline strip/panel, nothing else, static': a zoom's 16:9 window can never hold a wide UI strip without also holding what sits above it, so crop the insert instead and leave the zoom wide over it. Fractions of the CLIP's frame, read off a look_at_asset grid; pass 'full' to clear. mute=true (round 78) silences the scene's OWN audio — THE answer to 'mute that clip' / 'mute all scenes' (set_volume only reaches the main footage; muting every scene = set_volume on the kept spans + mute on each video insert). mute=false brings it back. fit (round 79) sets how THIS scene maps onto the canvas: 'pad' shows the WHOLE picture letterboxed on black — THE fix for a portrait image or clip that the default cover-crop beheads ('the image looks corrupted / cut off') — 'pad_blur' fits it over a blurred bac
move_insertPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. MOVE A SPLICED SCENE — reorder an inserted clip between any other scenes, in place. after_id is the insert it should play right AFTER (the scene map in get_edl names each scene's insert id); omit it to play FIRST at its boundary. THE tool for 'move this clip between those two scenes' / 'put the uploaded video after the intro' — never remove + re-insert, which costs two versions and the user watches the clip vanish. Everything anchored to the moved scenes (zooms, takeovers, texts) re-anchors and follows.
remove_insertPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Remove one spliced insert by its id (see get_edl) — the surrounding timing is restored exactly. If an insert landed wrong, remove it BEFORE re-inserting, or the old one stays in the video.