Clueso

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 current list via get_clip — the order it returns is exactly the order this takes. Works on grouped clips. Elements keep their group; moving a group's members together moves the whole group relative to everything else. The one thing a group cannot do is render in two pieces, so an order that puts a non-member BETWEEN two members of the same group is rejected and names the group — put the group's elements next to each other, or take the element out of the group first with update_elements(group).

Write a JavaScript program that calls this server's other tools. You have the whole language: loops, arithmetic, functions, conditionals, and values carried from one call into the next — all running next to the tools instead of across the conversation. Use it whenever code says the thing more directly than a sequence of separate calls would, which is often. COMPUTE, don't hand-write. Anything you would otherwise work out in your head and type as literals is better computed here — eased keyframe tracks, staggered start times, grid coordinates, derived palettes, positions from measured text widths. This is usually what makes motion look right: sample a curve at ten points and emit the values, rather than guessing four. THE STDLIB IS LOADED: anim (interpolate, spring, stagger, cues), ease, math, vec, rng, noise, color, scale, layout (row, column, grid, split, place, inset), shape, path, camera, field. `native` turns their values into editable elements (effects over a recording, captions, translatable copy; visuals themselves are pages): native.box(rect) and native.text(rect, {align, valign, ...type_data}) place elements from layout rects; native.tween(start, duration, from, to, {ease: "power3.out"}) gives two keyframes an editor can drag; native.keys(start, end, (t) => props) samples a spring or any curve; native.merge(...lists) combines tracks; native.hex(colour). Signatures: get_design_guide({select: ['stdlib', 'stdlib.<module>', 'stdlib:<words>']}). const cards = layout.row({ x: 160, y: 380, w: 1600, h: 300 }, [{}, {}, {}], { gap: 48 }); add_elements({ project_id, defaults: { clip_index: 0, element_type: "rectangle" }, elements: cards.map((r, i) => ({ ...native.box(r), type_data: { backgroundColor: "#1E1A26" }, keyframes: native.tween(1.2 + anim.stagger(i, 3, { each: 0.12, from: "center" }), 0.5, { opacity: 0, positionY: r.y + 40 }, { opacity: 100, positionY: r.y }, { ease: "back.out" }) })) }); DON'T COMMENT THE SCRIPT. Nobody reads it — it runs once a…

Set the voiceover voice for every clip in a project, or only for the clips in `clip_ids`. 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. When the user names specific clips, pass their ids in `clip_ids` so the other clips keep their voice. The voice is looked up by name (case-insensitive; a saved voice's code also works), preferring `voice_engine`. Never guess a name: a name that matches nothing applies the workspace default and returns `matched: false` with a note. Then pick a real voice with find(type='voices'), re-apply, and tell the user. `engine_substituted: true` means the named voice exists only on another engine and was applied there. Common engines: 'eleven' (ElevenLabs), 'cartesia', 'google'. ElevenLabs voices use the latest voice generation unless `voice_version` says otherwise; a voice the workspace saved keeps its saved version. Leave it unset; pass "legacy" ONLY when the user explicitly asks for the legacy/older voice generation.

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. Exception: a question, results card, form, or any element with a clickaction stays whole in the left clip (trimmed to end at the split), so it is never asked or paused on twice. Voiceover transcript and transcribed words are split proportionally. Concurrency: whole-project mutation (conflict domain: the entire project) — serialize. Do not run it in parallel with ANY other mutation on the same project_id, including element/voiceover edits; run them one at a time. (Mutations to different projects run in parallel freely.)

Switch the active workspace. The choice sticks for this client until you change it again — including across reconnects — so every later call operates in the new workspace. Use find(type='workspaces') to see available options.

Read and edit the workspace's translation glossary and translation rules (Settings → Translation). Every translation in the workspace follows them: captions translate, translated videos and articles. Use it when the user says how a term must be translated, that a product or brand name must stay untranslated, or how translations into a language should read (tone, formality). Do NOT hand-edit translated captions or text for this instead: the next translation repeats the mistake. Glossary terms: `original` (source text) → `translated` (the original itself keeps it as is), for `languages` (codes or names; omit for every language), optionally `case_sensitive`. Rules: ONE per language: `prompt` (instructions the translator follows), optional `title` and `examples` [{original, translation}]. Changes are WORKSPACE-WIDE and apply to translations made after them: tell the user when you add or change one, and translate again (captions action "translate") what should pick them up. action: • list — {terms: [{term_id, original, translated, languages, case_sensitive}], term_count, rules: [{rule_id, title, language, prompt, examples}]}; `language` keeps what applies to it, `query` filters terms by text (at most 200 terms per reply) • set_term — add a term or change one. An existing term is not overwritten: you get error "entry_exists" with `current`; show the user both, confirm, then call again with replace: true. Several terms with the same original → error "several_terms": pass the `term_id` you mean. • remove_term — delete the term with this `original` (exact text) or `term_id` • set_rule — set `language`'s rule; an existing one needs replace: true after the user confirmed (same "entry_exists" reply) • remove_rule — delete `language`'s rule Editing needs an editor or admin role, and saving needs a plan with the translation glossary (Enterprise); a refusal says which: tell the user, don't retry.

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. Keep each <EMBED {id}> placeholder unchanged, or what it stands for is deleted. Get the current article first with get_article, modify the markdown, then call this with the article_version of the article you edited (from get_article, or from your last add_article_media / update_article_media / update_article on it). If the article changed since, the update is refused: read it again and redo the change.

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 markdown that omits the `<SCREENSHOT id>` reference. Unreferenced media is pruned server-side on save. There is no separate delete tool — the markdown IS the source of truth for what's present.

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; omitted fields are preserved. To delete a track entirely, use `remove_from_project(target='audio')` instead.

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?, voiceover_volume?, video_styling?, after_clip?, subtitle_settings? } - duration: sets the clip's length WITHOUT rescaling anything (unlike generating speech, which rescales the whole clip). A shrink clamps every end_time past the new end to it; a grow carries an element that ended at the old end to the new end and leaves the rest where they were. A placed trim animation keeps its animation_duration: it holds its last frame on a grow and is cut on a shrink; only a stretch animation placed to fit keeps filling its window at the same speed. Keyframes keep their timestamps. Each clip's result lists what moved as extended / clamped. - voiceover_volume: 0-100. This is how you make a clip SILENT — set 0 to mute the narration while keeping the text and its word timings. get_clip and get_project report the current value, so read it before muting to restore it later. There is no "delete voiceover" tool; muting is the supported way. - background_color: hex (keeps the existing pattern/image, changes color). background: replaces the whole background — a full object from find(type='backgrounds'), or any image/video: { src (URL or upload id), media_type?: 'image'|'video' (inferred), color?, padding? (% around the footage, 0-100), border_radius? (px), shadow? (0-100), volume? (a video's audio, 0-100, default 100) }. - transition: { type, duration, direction?, color?, bezier? }, or null to remove. Set on the OUTGOING clip — the transition plays at the END of clip_index, into the next clip. Types: circleWipe, rainbowWipe, cornerWipe, stack, colorWipe, dissolve, pushPull, fadeToColor, flip. Directions: rainbowWipe/cornerWipe take topLeft|topRight|bottomLeft|bottomRight; colorWipe left|right; stack…

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, content }` - Write binary: `{ path, content, encoding: "base64" }` - Write from URL: `{ path, source_url }` (presigned URL, e.g. from get_clip with save=true) - Delete: `{ path, content: null }` You can mix writes and deletes in a single call. Existing files at the same path are overwritten. `brand_locked`: true keeps the clueprint's own colors, fonts and logos for projects in this workspace; false (the default) re-skins them to each project's brand kit. Only this workspace's clueprints; a community clueprint is always re-skinned. `decisions` records the build-time choices create_clueprint left pending, after you ask the user: animation_modes / image_modes ({id: mode}), voiceover_policies ({source_clip_id: policy}), split_decision, slide_count_strategy, allowed_element_types, the *_by_role variants for all-slides sources ({role: ...} from the *_by_role groups), and finalize_layout_texts: true (once every layouts/<NN>-<slug>/layout.md exists). Each applies on its own; failures come back in decision_errors.

Update many elements across one or more clips in a single tool call. Replaces the per-element tool — always batch. SEND LESS, GET BACK LESS. `defaults` carries what every item shares (clip_index, element_type, and type_data entries like font_setting or alignment) so you send it once instead of per item; each item overrides any key it sets. `returning` declares what comes back, the way `select` shapes a get_clip read — omit it for a sensible default, or pass [] for just the counts. defaults: { clip_index: 1, element_type: 'text', type_data: { font_setting: {...} } } returning: [] → { total, succeeded, failed }, plus error codes + element ids if any returning: ['layout'] → + the measured text fit per element returning: ['qa.codes'] → + the clip audit with prose stripped from non-errors (any returning value → error findings regardless; only warnings are opt-in) 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 within one call are applied in order; partial success is fine. Interactive elements (question/results/form): options and form fields sent WITHOUT an id keep the id of the stored one with the same text/label, so reordering is safe; the merged result is re-checked (answer key, jump targets, logic options). On a text or shape, type_data.clickaction: null removes its click action; a partial clickaction keeps the stored wait_for_click/wait_at. You do NOT need clip_index here — an element_id is unique within the project, so the server locates the clip itself. Pass it only as a hint; a wrong one is corrected rather than rejected. Grouping: pass `group: "<name>"` to move an element into a named group (created on demand), or `group: ""` to pull it back out to the clip root. Several items sharing a name collect into one group — the way to tidy loose elements into units the user can move or hide together. Grouping…

Transform, keyframe, rename, nest or lock GROUPS. A group moves, scales, rotates and fades as ONE unit, without touching any child's stored position — which is how you get a camera push instead of building the target layout twice and crossfading it. Address by `group_id`, never by name. Ids come from get_clip, or from the `group_id` that add_elements/update_elements hands back when you pass `group`. An unknown id is an error, never a silent create. There is no add_groups: a group is CREATED by putting elements in one — `add_elements(group: "hero-card")` — which also returns its id. That is not a shortcut; a group's pivot comes from its children's bounding box, so an empty group has no geometry to transform. The shortest path, in one script: const clip = get_clip({ project_id, clip_index: 2, select: ["groups"] }); const byName = new Map(clip.groups.map(g => [g.name, g.id])); update_groups({ project_id, items: [{ clip_index: 2, group_id: byName.get("hero-card"), anchor_px: [960, 540], keyframes: [ { timestamp: 0, scaleX: 1, scaleY: 1 }, { timestamp: 1.2, scaleX: 2.4, scaleY: 2.4, offsetX: -400, offsetY: -120, interpolation: "easeOut" }, ], }]}); Units are canvas pixels, as everywhere else: `offset_px`, `blur_px` and `anchor_px` are pixels; `scale` is a multiplier; `rotation`/`rotate` are degrees; `opacity` is 0-100. `anchor_px` is the pivot everything rotates and scales about. Give it as a point on the canvas — the server converts it to a fraction of the group's child bounding box and reports back both that fraction and the box, so you can check it. Default is the box's centre. Set it when you want a push that favours one corner. Because it is stored as a fraction of the members' box, adding or removing members moves the pivot on the canvas; set `anchor_px` again after changing a transformed group's membership. Only fields you pass are changed. `keyframes: []` CLEARS every track; omitting `keyframes` leaves them…

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="" (or "root"). Aspect ratio: pass any "W:H" (positive integers). The canvas is fit inside 1920×1080 keeping the ratio, so element pixel coordinates use the resulting canvas. Common values: - "16:9" → 1920×1080 (landscape, YouTube/web — default) - "9:16" → 608×1080 (portrait — TikTok/Reels/Shorts) - "1:1" → 1080×1080 (square — Instagram feed) - "3:4" → 810×1080 (portrait card) - "4:5" → 864×1080 (portrait — Instagram feed) Element coordinates are stored as fractions of the canvas, so existing elements reflow to the new canvas automatically — no element coordinates are rewritten. Brand kit: brand_kit_id sets the kit this project is built with (an id from find(type='brand_kits')); 'default' returns it to following the workspace default kit. It changes the kit get_design_guide({project_id}) returns; elements already placed keep their colors, fonts and logos until you edit them. The reply's brand_kit is {id, name, follows_default}. Only workspace editors and admins can change it. Tags: add_tags / remove_tags change the project's tags (the home page Tags menu and filter), by NAME. Adding a name the workspace doesn't have creates it; existing names match ignoring case. List them with find(type='tags'). Only workspace editors and admins can change tags. To tag many projects, loop update_project over their ids in run_script. When tags are given, the reply also has tags (the project's full list after the change), created_tags and not_found_tags (remove_tags names the workspace doesn't have). Concurrency: whole-project mutation (conflict domain: the entire project) — serialize. Do not run it in parallel with ANY other mutation on the same project_id, including element/voiceover edits; run them one at a time. (Mutations to different projects run in parallel freely.)

Upload one or more files to Clueso. Pick a mode by client + where the file lives: 0. **files** — ChatGPT only: files the user attached in the conversation. ChatGPT fills each entry (download_url + file_id) itself; pass the attachments here rather than asking the user to re-upload. Returns one mcp_upload_id per file. 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 streams a single local file to it; Clueso relays the bytes to storage server-side. The PUT targets the base domain — NOT cloud storage directly — so it works on desktop/agent clients that can't reach or are blocked from S3. Requirement: the client must be able to PUT bytes to the Clueso base domain (run the returned curl, or any HTTP PUT). The agent (or the user at a shell prompt) runs the curl. Prefer this whenever there's no human at a browser. **file_names** (without request_hosted_upload) is the same for many files in ONE call: a token and URL per name plus ONE `curl` that sends them all. Run it from the folder the names are relative to (for edit_animation `upload_ids`, the page site's root, names like 'index.html' or 'js/scene.js'). 2. **file_url**: Pass a public https URL. Server fetches and stages the file. Returns mcp_upload_id immediately. Use when the file is already on the open web — no user interaction needed. 3. **request_hosted_upload** (UI mode — use ONLY when a human should pick files in a browser: many files at once, or a host with no shell / no PUT capability): Returns a single upload_token + upload_page URL. Share the link with the user; they open it in a new browser tab, drop their files, click Done. Then call check_uploads(upload_token) to retrieve all mcp_upload_ids. Call once for all files. Hosted uploads cover any number of files per call: one call issues one upload_token, and that token covers every file the user drops…

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 (returns immediately; wait: true blocks until it lands) - "set_and_generate" — set text and kick off TTS in one entry (+ text) Emotion tags: put ElevenLabs emotion/audio tags in square brackets in the text, e.g. "[excited] And it just works." or "[whispers] Here's the trick." — the voice performs them and they're never spoken or shown. Use them sparingly, before the phrase they colour. Pauses: <pause:1.5s> in the text is exact silence of that length, anywhere including the very start (a lead-in before the first word) and the very end (a hold after the last); word timings account for it, and get_clip's voiceover_text shows existing pauses the same way, so keep them when you rewrite. Unlike the [pause] emotion tag, which is a performed beat of no set length. Sizing a script: narration runs roughly 2–2.5 words per second depending on the voice — size the script to the target length, generate the voiceover, then read the real clip durations back (get_clip, once `busy` is empty) before timing visuals. Address a clip the same way as everywhere else: `clip_index`. Pass `clip_id` instead if you already have it — it survives clips being inserted or reordered mid-build — but you never need both; whichever you omit is looked up once for the whole call. Entries within one call are applied in order. Returns one result object per input entry. All text-set actions land in ONE save; the TTS for generate/set_and_generate runs async per clip after. Sync points: if get_clip's `voiceover_text` for the clip contains `<SYNC_MARKER N>` tokens (a screen recording's on-screen actions), your new text must carry every one of them, each exactly once and in order, placed where that action is narrated. Otherwise the entry is refused and nothing is…