Clueso

Clueso's house style for composing video clips — how to think about concept, typography, color, composition, motion, and pacing. Read it before composing or editing a clip's visuals when you're NOT following a clueprint, or to fill gaps a clueprint leaves silent. General craft, not clueprint-specifi

Create a new blank Clueso project. Returns the projectId and initialClipId — the project starts with one blank clip already at index 0 (default short duration). Use update_clips to resize/retitle clip 0, add_clips(kind='blank') to append more clips, add_elements to place content, and add_audio to at

Update a project's metadata: rename, change description, move to a different folder, or change aspect ratio. Only fields you provide are changed. To move a project to the workspace root, pass folder_id="" (empty string). Aspect ratio: pass any "W:H" (positive integers). The canvas is fit inside 19

Clone an entire project — every clip, voiceover, asset, and metadata field — into a fresh project. The copy has its own S3 namespace, so changes or deletions to the source never affect the duplicate. Defaults: - new_title omitted → "{source title} (copy)" when no folder_id is given (or it's empty)

Kick off a video export of the project. Returns immediately with an export_id; the export pipeline runs in the background. The user can find the rendered video in the Exports tab in the editor. Defaults: 1080p / 30fps / no captions / English. Pass overrides only when needed.

Find any resource in Clueso by type, optionally filtered by name or exact id. One tool for listing and searching across the workspace. type: • projects | folders | clueprints | workspaces • backgrounds | voices | image_gen_style_packs | element_components • images | videos | music | sfx — m

Switch the active workspace for this session. Use find(type='workspaces') to see available options.

Get a summary of a project: canvas dimensions, per-clip summary (ids, indices, durations, element counts, voiceover_volume), and `audio_tracks` — every music/SFX entry on the project flattened to the same wire shape `add_audio` accepts (id, src, name, source_duration, guide_start_time/end_time, musi

Read one clip: its elements (positions/sizes in canvas pixels), voiceover (text, voice, duration, voiceover_volume), background and transition. Pass `render` to also get a PNG of the frame. ASK FOR WHAT YOU NEED. A full read is large — on a dense clip the per-word voiceover array and the element ty

Update one or more clips in a single call — background, transition, duration, title, visibility, position, and (video clips) the footage transform via video_styling. Always batch. Each entry: { clip_index, duration?, title?, background_color? | background?, transition?, hidden?, position?, voiceove

Remove a clip from the project by index. Cannot remove the last remaining clip. After removal, all clips with index > clip_index shift down by 1. When removing multiple clips by index, remove from highest index to lowest (or capture clip_ids first and re-derive indices between calls). Concurrency:

Split a video clip into two clips at the given timestamp. The left clip keeps the original clip ID; the right clip gets a new ID and is inserted immediately after. Elements spanning the split point are duplicated into both clips with adjusted timing. Voiceover transcript and transcribed words are sp

Clone one clip — within the same project, or **from another project** — into a target project. - Same project: pass `target_project_id` and `source_clip_id` (omit `source_project_id`). - Cross-project: pass `target_project_id`, `source_project_id`, `source_clip_id`. The source clip's S3 assets (voi

Create new clips on a project. One tool, three sources: - kind="blank": empty slide clips you'll populate with add_elements / generate_media. Pass `clips: [{title?, duration?}, ...]`. Note: create_project already creates clip 0; calling with N blank entries gives N+1 clips total. - kind="pptx": ext

Return the JSON schema for an element type's type_data. Call this before add_elements / update_elements when you don't already know the field shape for the element_type you're placing.

Add many elements across one or more clips in a single tool call. Replaces the per-element tool — always batch. Use after calling get_element_schema to confirm the type_data shape per element_type. Items within one call are applied in order; returns one result entry per input item so partial succes

Update many elements across one or more clips in a single tool call. Replaces the per-element tool — always batch. Each item can update position/timing fields alone, or type-specific fields via type_data (use get_element_schema in 'update' mode to see what's settable for an element_type). Items wit

Remove many elements across one or more clips in a single tool call. One entry per element ({clip_index, element_id}). Concurrency: parallel-safe (conflict domain: the individual element) — same as add_elements/update_elements. Each removal is a granular element_remove patch merged under a per-guid

Reorder the elements inside a clip. List position IS the z-index — later entries in `ordered_element_ids` render on top of earlier ones. You MUST pass the full set of element IDs currently in the clip. The handler rejects partial lists so a reorder can never silently drop an element. Get the curren

Remove an element or audio track from a project. - target="element": removes an element from a clip (requires clip_index + element_id) - target="audio": removes a music/SFX track (requires music_id — returned by add_audio) Concurrency: target='element' is element-scoped (conflict domain: the indivi

Add a music track or sound effect that plays as a project-level audio layer over all clips. Does NOT consume a clip slot. Use this for background music or a soundtrack that should play under the existing timeline. (For inserting an audio file as its own sequential clip with auto-transcription, use a

Mutate fields on an existing music/SFX track by id. Read existing tracks via `get_project.audio_tracks` — the per-entry shape there matches this tool's args, so you can flip a knob (volume, fades, timing, loop) and write it back without losing the track's id. Only fields you pass are changed; omitt

Set voiceover text and/or trigger speech generation for any number of clips in a single call. Each entry chooses its own action: - "set_text" — set transcript for a clip (clip_index + text) - "generate_speech" — async TTS for a clip (clip_id; returns immediately) - "set_and_generate" —

Run the agentic auto-sync pipeline against a clip with a source recording. Detects natural sync points (UI state changes, narrated steps) and inserts sync-marker nodes into the clip's transcript. Async: returns immediately with a status enum from the pre-flight; sync-marker nodes appear in the tran

Insert one sync marker on a clip's transcript. Use this when: - The user is explicit about WHERE the camera should pause / cut (e.g. "sync the word 'submit' to 4.2s of the demo"). - `auto_sync` ran but missed a step you care about. How matching works: - `word`: case-insensitive, punctuation-stripp

Upload one or more files to Clueso. Three modes — pick by client + where the file lives: 1. **file_name** — HOSTED upload, the default for any non-UI / programmatic upload (Claude Code, Cursor, Claude Desktop, scripts). Returns an upload URL on Clueso's OWN base domain + a ready-to-run curl that st

Fetch all files the user uploaded via the hosted upload page. Returns one mcp_upload_id per file — pass each to the appropriate tool (add_clips, add_article_media, etc.). Call this once after the user confirms they are done uploading; the token covers all files they dropped on the page.

Generate an AI image or canvas-code-based animation directly into a clip. - kind="image": text-to-image. Pass `prompt`. Optional: `style_id` (from find type='image_gen_style_packs'), `reference_image_url` or `mcp_upload_id` for image-to-image grounding. - kind="animation": canvas-code animation ren

Estimate voiceover duration for one or many clips at once (~150 words/minute). Pass an array of voiceover texts — one per clip. Returns durations in the same order, ready for add_clips.

Analyze an audio file. Modes: - transcript: Speech-to-text with word-level timestamps. Works on BOTH speech and sung lyrics — routes to a music-aware provider when content is detected as music. Use to get `words[{w,start_ms,end_ms}]` for caption timing, script editing, or word-level visual sync. Not

Get the article content as markdown. Screenshots appear as <SCREENSHOT {id}> placeholders. Returns the markdown text and a list of screenshot IDs.

Update article text content from markdown. Use <SCREENSHOT {id}> placeholders to position screenshots. Screenshots in the markdown are kept. Screenshots removed from markdown are deleted. Order in markdown defines final order. Get the current article first with get_article, modify the markdown, then

Add a screenshot or GIF to the article. Returns a screenshot_id to place in the article via update_article using `<SCREENSHOT screenshot_id>`. - kind="image": pass `timestamp` to capture a frame from the project's base video, OR pass `mcp_upload_id` (from the upload tool) to attach an uploaded imag

Update an article image/GIF (screenshot), or inspect its current state. - Provide one or more of `zoom_factor`, `crop`, `shapes` to change metadata. - Pass `render=true` (with no other updates) to fetch the current details without mutating. To DELETE an article image/GIF: call `update_article` with

Create a new clueprint (reusable video template). A clueprint is a structured file directory with design notes, composition rules, and screenshots that can be used to generate videos. Use human-readable folder categories: design/ (colors, typography, backgrounds, animation), rules/ (composition, vo

Fetch clueprint data. Use `include` to control how much you pull back: - include="metadata": just the clueprint's name/description/tags/visibility/thumbnail. - include="tree": metadata + the full file tree (path, mime_type, and size per entry). Call this first when exploring an unfamiliar clueprint.

Update a clueprint's metadata and/or file contents in one call. Metadata fields (`name`, `description`, `tags`, `visibility`, `thumbnail_path`) are applied as a patch — only the fields you pass change. Pass at least one to update metadata. `files` is a list of file mutations: - Write text: `{ path

Set the voiceover voice for every clip in a project. Use this to apply a clueprint's voice (read `voiceover.voice.name` and `voiceover.voice.engine` from the clueprint source data), or to switch all clips to a specific voice in one call. The voice is looked up by name + engine; lookup is case-insen

Post a review comment on a project, attributed to "Clueso AI". Use this to leave feedback, suggestions, or notes — either at the project level (no clip_id) or pinned to a specific clip with an optional timestamp inside that clip.

Create a screen-recording clip in a project. Creates blank placeholder clips, registers job entities, and sends the job to AVS. The blank clips this tool creates are placeholders; they become video clips when processing completes, so removing one loses that scene. Article placeholders are also inse