Valmera MCP tool reference

How the tools fit together

1. Pick a project. list_projects or create_project returns a project_id, which every later call passes explicitly.
2. Upload and index. upload_start, a PUT to the presigned URL, then upload_finish; index_status reports when the transcript, shots and silences are ready.
3. Read. get_words, get_transcript, get_edl and look_at give the model real timings and frames to decide from.
4. Edit. Each editing tool writes a new version of the edit decision list; the original file is never modified.
5. Review. render_preview returns a job; wait_for_job follows it; watch_video and look_at show the result.
6. Deliver. export_final, then wait_for_job, then download_url(kind="final") for the MP4.

Two clocks run through the catalog. Source seconds address the original upload and never move. Output seconds address the edited program and shift as cuts are made. Each tool says which one it takes; see the two timeline clocks.

Projects, uploads, jobs and export (14)

Pick a project, upload footage, follow jobs, watch renders and deliver the MP4.

apply_short_edit_batches

Save edits for up to 30 shorts in one request, each applied atomically, without rendering.

create_project

Create an empty project and return its project_id. kind="shorts" creates a podcast-to-shorts project.

download_url

A temporary link to a preview, a changed-section check or a completed final export (kind="final").

export_final

Export a reviewed edit version as a full-resolution H.264 MP4 rendered from the original file. Returns a job; repeating the request reuses it.

index_status

Progress of the one-time analysis. Transcript, shot and silence tools work once it reports done.

list_projects

List your projects, newest first, with whether each has a video and what kind it is. Start here.

open_project

Return a project's full state: the video, transcript, shots, current edit and assets you can place.

open_short

Open one generated short by card number or child project ID and edit it directly.

project_state

Re-read a project's current state. Cheap enough to call whenever the edit's state is unclear.

shorts_status

Progress of a podcast-to-shorts run: the child projects, their edit versions and render states.

upload_finish

Finish an upload once the bytes are in storage. For a main video this starts indexing.

upload_start

Start uploading a local file as the main video, a clip, music or an image. Returns presigned URLs and the exact curl command; files over 16 MiB upload in parts.

wait_for_job

Wait for a background job (a render, or a call that outran its reply) and return its result. Safe to call repeatedly.

watch_video

Hand over the real MP4 of the current edit, the source or an uploaded clip, rendering the edit first if needed.

Reading the footage (25)

Transcript, words, shots, silences, audio analysis, frames and the current edit. Most of an edit is reading.

find_burned_text

Measure where text is burned into the picture (subtitles, watermarks, handles) as exact rectangles with timings.

find_footage

Find real web footage of a named subject for b-roll, such as the rocket when the speaker mentions SpaceX.

find_shots

Its description and argument schema are in your client's tools/list.

find_silences

Pauses of at least a given length, with their midpoints and the surrounding words.

find_song

Find links to a specific song you name, best match first; fetch_url downloads the pick. There is no mood or genre catalog, and finding a track doesn't license it.

find_visual_moments

Search the whole indexed filmstrip for a concrete visible event, such as a gesture or a product appearing, and get source timestamps.

get_audio_analysis

Tempo with a confidence figure, beat timestamps and energy over time for the source audio.

get_editorial_map

One compact source timeline joining each sentence to shot changes, energy, beats, vocal stress, pauses and on-screen evidence.

get_edl

The current edit decision list and its version, by section, with paging for large timelines.

get_kept_transcript

What the current edit keeps, in program time with matching source spans, with repeated phrases flagged.

get_shots

Shot boundaries for a time range: where scene changes and transitions can land.

get_syllables

Its description and argument schema are in your client's tools/list.

get_transcript

Sentence-level transcript with timestamps for a source-time range, or the transcript of an uploaded clip or song.

get_video_info

Source metadata with a summary of the index and the current edit.

get_words

Word-level timestamps for any source-time range, up to 400 words per response. The source of truth for cut points inside a sentence.

list_assets

Every file in the project, used or not: clips, images, music and renders.

list_motion_templates

Its description and argument schema are in your client's tools/list.

list_music_library

Its description and argument schema are in your client's tools/list.

list_sound_library

Its description and argument schema are in your client's tools/list.

look_at

Frames of the source or the edited program at chosen times, returned as one labeled image with a coordinate grid.

look_at_asset

Frames of an uploaded clip, image or past render.

look_at_world

Its description and argument schema are in your client's tools/list.

read_skill

Load a focused editing playbook (captions, zooms, audio, transitions) before the first edit of that kind.

search_stock

Search stock b-roll, and real topical photos with kind="photo", at the project's aspect ratio.

search_transcript

Find where something is said, by exact and fuzzy match.

Cutting (6)

Remove dead air, filler words and passages, or put them back.

cut_output_range

Remove a span of the finished edit in output seconds, splitting any inserted clip it crosses.

cut_range

Remove one source-time range, optionally snapped to whole words. The rest of the edit is untouched.

cut_silences

Cut every pause over a threshold in one call, keeping breathing room and snapping to word edges. It won't cut gaps full of music or other sound unless allowed.

keep_segments

Replace the whole keep list with new source ranges, for a full restructure.

remove_filler_words

Remove um, uh, er and similar using exact word timestamps, or a custom list such as "you know".

restore_range

Put a cut source range back without touching the rest of the edit.

Captions and on-screen text (12)

Word-timed burned-in captions, fixes and styles, titles, kinetic text and text behind the subject.

add_captions

Burned-in, word-timed captions from the transcript, or captions you dictate. Presets include clean, podcast, karaoke, beast and spotlight, with active-word highlight.

add_kinetic_text

Place each spoken phrase on screen as it is said, animated in the space around the speaker.

add_text

Designed text over a window: title, subtitle, lower third, callout, big number, quote or chapter.

add_text_behind

Put words behind the moving subject with a real depth composite, so the person passes in front of the letters.

add_title_card

Cut to a full-frame card showing only this text, then return to the footage.

audit_captions

Check the burned caption track for late first captions, missed words, overlaps and line counts.

erase_burned_text

Remove burned-in captions or watermarks by repainting the picture behind them.

remove_text

Remove one text element.

set_caption_fixes

Correct how words appear in the captions, such as names and product terms.

set_caption_mutes

Hide captions over chosen windows, such as under a title card or a full-frame graphic.

set_caption_style

Change how captions look (preset, color, size, position, animation) without touching their text or timing.

set_text_motion

Keyframe position, scale, rotation and opacity on an existing text item.

Framing and motion (19)

Aspect ratios, reframing, zooms, speed, freeze frames and screen-recording treatments.

add_aspect_shift

Morph to a different aspect ratio mid-video, smoothly, and back.

add_freeze_frame

Freeze on a moment, optionally behind big text with the frame blurred and darkened, then continue.

add_screen_takeover

Push into a screen in the shot, like a laptop or phone, and let another clip take over the frame.

add_zoom

A punch, ease, push-in or pull-out zoom over a range of the finished edit, aimed anywhere in the frame.

add_zoom_path

A zoom that holds and travels between points, such as following a cursor between buttons.

auto_reframe

Reframe to 9:16, 1:1, 4:5 or 16:9 by measuring where the subject is. Footage that runs to the edges, like gameplay, is fitted over a blurred backdrop instead of cropped.

deliver_aspects

Its description and argument schema are in your client's tools/list.

enhance_cursor

Make the mouse pointer in a screen recording bigger and steadier.

remove_aspect_shift

Remove one mid-video aspect change.

remove_cursor_enhance

Restore the original pointer.

remove_screen_frame

Return the picture to full-bleed.

remove_screen_takeover

Undo a screen takeover, optionally keeping the clip as a plain cut.

remove_speed

Return one speed span to normal speed.

remove_zoom

Remove one zoom.

remove_zoom_path

Remove one travelling zoom.

set_frame

Set the output aspect ratio with crop, pad or blurred-pad mode and optional per-shot focus points.

set_screen_frame

Inset the picture as a rounded, shadowed floating window on a color or gradient background.

set_speed

Speed up or slow down a source range from 0.25x to 4x; captions, music and zooms re-anchor automatically.

set_speed_ramp

Its description and argument schema are in your client's tools/list.

Audio (21)

Music, sound effects, voiceover, levels, loudness and stem separation.

add_library_music

Its description and argument schema are in your client's tools/list.

add_music

Mix a music track: a ducked bed under speech, or lead audio where no speech remains. Fades and loops by default.

add_sfx

Place a one-shot sound effect on a moment: a whoosh on a cut, an impact on a reveal.

add_voiceover

Lay an uploaded audio file over the program from any point, ducking other audio under it.

analyze_music

Its description and argument schema are in your client's tools/list.

audit_audio_mix

Audit the current mix: each item's role, window, gain, ducking, mastering and track provenance.

beat_align_cuts

Slide internal cuts onto the nearest beat, never inside a word.

extract_audio

Save only the sound of an uploaded video as an audio asset.

move_sfx

Retime an existing sound effect.

plan_to_music

Its description and argument schema are in your client's tools/list.

remove_music

Remove one music item.

remove_sfx

Remove one sound effect.

remove_voiceover

Remove one voiceover.

separate_music

Split the original soundtrack into speech and everything else, then rebalance: drop the background music or keep only the music.

set_audio_gain

Change the level of an existing music, effect or voiceover item.

set_master_loudness

Normalize the final mix to -14 LUFS with a -2 dBTP ceiling, on previews and exports.

set_music_fit

Retime or refit existing music: start later, run to the end, fade, loop or change the ducking.

set_volume

Volume automation on the original footage's audio over a source range.

shape_music

Its description and argument schema are in your client's tools/list.

suggest_motion_beats

Its description and argument schema are in your client's tools/list.

swap_music

Replace a music item's track while keeping its position, level and fit.

Colour and finishing (10)

Grades, looks, picture enhancement, stylize effects, fades and transitions.

add_stylize

Windowed finishing effects: grain, vignette, glow, halation, chromatic aberration, dream blur and more.

apply_look

One call for a whole aesthetic: caption preset, grade, transitions, fades and stylize together.

enhance_video

Improve picture quality: sharpen detail and denoise grainy low-light footage.

match_grade

Its description and argument schema are in your client's tools/list.

remove_stylize

Remove one stylize effect.

set_color_grade

A grade preset for the whole video: vibrant, warm, cool, black and white, vintage or cinematic.

set_fades

Fade picture and sound in from black and out to black.

set_grade_custom

Exposure, contrast, saturation, temperature and tint, applied on top of the preset.

set_grade_window

Its description and argument schema are in your client's tools/list.

set_transitions

Transitions at real scene changes and inserted clips, not at every jump cut.

Media and screen capture (13)

Insert clips and images, overlays, links, stock footage and website recordings.

add_overlay

Draw an image or clip over the picture: picture-in-picture, a corner logo or a full-frame cutaway.

add_stock_media

Download one stock or b-roll research result into the project, ready to place.

fetch_url

Download a video, song or image from a link (direct files, YouTube, TikTok, Vimeo, SoundCloud) as a project asset. Downloading doesn't grant republishing rights.

insert_media

Splice a clip or image in at any point of the edit; mid-take positions split cleanly at a word edge.

move_insert

Reorder an inserted clip between scenes.

move_overlay

Reposition, retime or resize an existing overlay.

record_website

Record a live web page as video: open the URL, hold, then smooth-scroll to the bottom.

record_website_demo

Record a browser using a site, with a visible cursor, real clicks and typing, following steps you write.

remove_insert

Remove one inserted clip and restore the surrounding timing.

remove_overlay

Remove one overlay.

set_insert_window

Change which part of an inserted clip plays, for how long and how fast.

set_overlay_motion

Keyframe position, scale, rotation and opacity on an overlay.

showcase_demo

Place a screen recording and cut it like a product video, with a zoom on each run of clicks.

Repair and censoring (6)

Blur or erase regions, and cut to color or glitch screens.

add_color_screen

Cut to a full-frame solid or gradient color screen for a moment.

add_corrupt_screen

Cut to a full-frame glitch screen as a transition between sections.

blur_region

Cover a fixed rectangle with blur, mosaic or a black bar, for faces, documents or plates.

erase_region

Remove what's inside a rectangle by repainting the background, such as a sign, sticker or logo.

remove_blur

Remove one censor region, or all of them.

remove_erase

Put the original pixels back for an erased region.

Batch edits, shorts and advanced composition (91)

Atomic edit batches, shorts, b-roll planning, emphasis, graphics, typography, previews and resets.

add_accent

Its description and argument schema are in your client's tools/list.

add_breakdown

Its description and argument schema are in your client's tools/list.

add_collage

Its description and argument schema are in your client's tools/list.

add_custom_filter

Apply your own ffmpeg filter chain for a look no preset covers.

add_depth_effect

Its description and argument schema are in your client's tools/list.

add_device_stage

Its description and argument schema are in your client's tools/list.

add_element

Its description and argument schema are in your client's tools/list.

add_finish

Its description and argument schema are in your client's tools/list.

add_hud

Its description and argument schema are in your client's tools/list.

add_motion_graphic

Its description and argument schema are in your client's tools/list.

add_region_effect

Its description and argument schema are in your client's tools/list.

add_strobe

Its description and argument schema are in your client's tools/list.

add_subject_effect

Its description and argument schema are in your client's tools/list.

add_time_effect

Its description and argument schema are in your client's tools/list.

add_type_window

Its description and argument schema are in your client's tools/list.

add_typeset

Its description and argument schema are in your client's tools/list.

add_ui_scene

Its description and argument schema are in your client's tools/list.

add_vector_graphic

Native vector shapes over a window: panels, highlights, arrows, rings, underlines and progress bars.

align_lyrics

Its description and argument schema are in your client's tools/list.

analyze_reference

Its description and argument schema are in your client's tools/list.

animate_still

Its description and argument schema are in your client's tools/list.

apply_edit_batch

Apply up to 64 edits atomically against a base version, with a retry ID so a repeated request can't write twice.

apply_format_pack

Its description and argument schema are in your client's tools/list.

apply_recipe

Its description and argument schema are in your client's tools/list.

ask_user

Ask you a specific question when a choice belongs to you.

attach

Its description and argument schema are in your client's tools/list.

audit_motion

Its description and argument schema are in your client's tools/list.

bind_motion_motif

Record which motion motif an existing movement carries out, for the edit's motion plan.

check_speech

Its description and argument schema are in your client's tools/list.

compare_uploaded_media

Compare several uploaded clips or images from their real frames to choose and order them.

compose_panels

Build one 16:9 clip with two or three videos side by side on black.

conceal_jump_cuts

Its description and argument schema are in your client's tools/list.

critique_short

Its description and argument schema are in your client's tools/list.

expand_toolset

Load extra tool schemas for a domain such as captions, audio or motion into the next step. Changes nothing in the edit.

import_font

Its description and argument schema are in your client's tools/list.

import_lut

Its description and argument schema are in your client's tools/list.

isolate_colour

Its description and argument schema are in your client's tools/list.

justify_verification_findings

Record evidence that a verification finding was a false positive.

make_shorts

Seed child short projects from the source ranges the assistant picks after reading the transcript. It doesn't choose the arcs or edit them; open and edit each child.

make_variant_set

Its description and argument schema are in your client's tools/list.

open_visual_page

Open pages of the footage's visual storyboard to see the actual pixels of a moment.

pick_still

Its description and argument schema are in your client's tools/list.

pin_to_plane

Its description and argument schema are in your client's tools/list.

place_in_world

Its description and argument schema are in your client's tools/list.

plan_footage

Its description and argument schema are in your client's tools/list.

plan_loop

Its description and argument schema are in your client's tools/list.

proof_device

Its description and argument schema are in your client's tools/list.

punch_in_on_emphasis

Punch-in zooms on vocally stressed words, when you ask for them.

recolour_object

Its description and argument schema are in your client's tools/list.

remove_broll

Its description and argument schema are in your client's tools/list.

remove_custom_filter

Remove one custom filter.

remove_depth_time

Its description and argument schema are in your client's tools/list.

remove_editorial_graphic

Remove one editorial graphic.

remove_finish

Its description and argument schema are in your client's tools/list.

remove_motion_graphic

Its description and argument schema are in your client's tools/list.

remove_picture_card

Remove one picture card.

remove_punctuation

Its description and argument schema are in your client's tools/list.

remove_region_effect

Its description and argument schema are in your client's tools/list.

remove_stem_mix

Restore the original soundtrack after separate_music.

remove_subject_effect

Its description and argument schema are in your client's tools/list.

remove_typeset

Its description and argument schema are in your client's tools/list.

remove_typography_scene

Remove one typography scene.

remove_ui_scene

Its description and argument schema are in your client's tools/list.

remove_vector_graphic

Remove one vector graphic.

remove_world

Its description and argument schema are in your client's tools/list.

render_preview

Render the current version: an inexpensive 480px draft, an approval render from the original at up to 720×1280, or just the changed sections.

render_variants

Its description and argument schema are in your client's tools/list.

research_broll

Plan b-roll as a sequence: a visual query, purpose, time and duration for every cutaway.

reset_edit

Start again from the untouched source. Earlier versions stay in history.

retypeset_language

Its description and argument schema are in your client's tools/list.

select_object

Its description and argument schema are in your client's tools/list.

set_background

Its description and argument schema are in your client's tools/list.

set_brand_kit

Its description and argument schema are in your client's tools/list.

set_composite

Its description and argument schema are in your client's tools/list.

set_editorial_graphic

Editable editorial layouts: statement, comparison, metric, quote, chapter, label or headline.

set_intensity

Its description and argument schema are in your client's tools/list.

set_junction

Its description and argument schema are in your client's tools/list.

set_motion_graphic

Its description and argument schema are in your client's tools/list.

set_picture_card

Show the footage as a rounded card on the canvas while captions and type stay full size.

set_stack

Its description and argument schema are in your client's tools/list.

set_typeset

Its description and argument schema are in your client's tools/list.

set_typography_scene

A speech-cued, mixed-font phrase built as editable native text.

set_vector_graphic

Change an existing vector graphic's shape, timing, colors or motion.

source_broll

Its description and argument schema are in your client's tools/list.

start_media_sequence

Start a new program from one uploaded clip or image instead of the main video.

suggest_devices

Its description and argument schema are in your client's tools/list.

suggest_emphasis

Candidate emphasis words from the real transcript: stressed words, numbers and distinctive terms.

suggest_match_cuts

Its description and argument schema are in your client's tools/list.

suggest_recipes

Its description and argument schema are in your client's tools/list.

suggest_story

Its description and argument schema are in your client's tools/list.

track_point

Its description and argument schema are in your client's tools/list.

Not in the catalog

The server card lists these limits so an assistant never promises them:

• Handing the edit to Valmera's in-house agent; over MCP, your assistant edits with the tools directly.
• Generating a whole video from a text prompt.
• SRT or VTT import or export; captions are burned in.
• Team seats or collaboration, and direct publishing to YouTube or TikTok.
• Custom font uploads, true crossfade or dissolve transitions, and motion-tracked overlays or stickers.
• Audio denoise ("studio sound") and AI music generation.

Frequently Asked Questions

Made with Valmera: real exports

Put these tools in your assistant

Connect Claude, ChatGPT, Cursor or any MCP client in a minute. Creating an account and uploading are free; editing requires a subscription.