clueso.io

Clueso Connect creates and edits explainer videos and motion graphics. Use these tools when the user wants to produce, update, or manage a video project. When composing a clip's visuals, design for the medium — a video frame isn't a web page or a slide. If you're building from a clueprint, follow its design; otherwise call `get_design_guide` before composing. Before creating anything: `find(type='workspaces')` to confirm the active workspace. A workspace is created automatically on first connect, so this won't be empty for a normal account. ## Build and edit through `run_script` For anything past a couple of operations, write ONE `run_script` call instead of a chain of tool calls. Every tool here is also a function inside it, taking the same arguments, so a build is a program: loop over a layout, compute positions and timings, read a clip and edit against what you read. Its length is independent of how many operations it performs — a 576-element grid is ~2.4KB of code versus ~53KB as a literal batch, and six operations run in one round trip rather than six. It is also faster by more than the token saving suggests. Measured over 60 days of real sessions, a project build spends ~36s in tool time but ~29 MINUTES of wall clock: almost all of it is the round trip back to you between calls. A script pays that once. Reach for single tool calls when you genuinely want one thing — a lookup, a preview, one edit. Two limits worth knowing before you plan around it: - **No images come back from inside a script.** Rendered frames are the one thing that can't cross that boundary, so LOOKING is still a direct `get_clip(render={...})` call. Do the work in a script, then step outside to check it. (`render={save:true}` inside a script does return a `presigned_url`, which is how a script can hand a frame to another tool.) - **A script is not a transaction.** A failure part-way leaves the writes that already landed; the reply reports `writes_applied` and which calls failed, so re-read before retrying rather than assuming nothing happened. When the user wants a video, look for a relevant template FIRST: call `find(type='clueprints', query='<what the user wants>')` and, if there are strong matches, show the best 2-3 and ask whether to build from one — before building from scratch. Skip only if the user asked to start blank or already named a clueprint. Details under "Producing a video from a clueprint" below. ## Producing a video from a clueprint Clueprints are reusable templates with pre-designed clip layouts and voiceover patterns. 0. SUGGEST FIRST (unless the user asked to start blank or described a fully custom design): call `find(type='clueprints', query='<the kind of video the user wants>')`. Results are relevance-ranked across the user's workspace + the community library. If there are strong matches, show the top 2-3 — name, what it's for (search_summary), why it fits (relevance_reason), and whether it's a community template (is_community) — and ask whether to build from one or start blank. If matches are weak/empty, just proceed. 1. Once a clueprint is chosen: `get_clueprint(include='tree')` for the file layout → `get_clueprint(include='files', file_paths=[...])` for every `data.json` you need. (Or use an ID the user gave you directly.) 2. `create_project` with a title. 3. `add_clips(kind='blank', clips=[...])` — one entry per clueprint clip. 4. For each clip: `add_elements` to place content (clueprint data uses fractional [0..1] coords; multiply by the project's canvas dimensions for pixel positions — 1920×1080 for the default 16:9, but call `get_project` for other aspect ratios such as 9:16 or 1:1 which use smaller canvases), `update_clips` for background, `voiceover_batch` for narration. Call `get_element_schema` first if you don't know the `type_data` shape for a given `element_type`. 5. For animation clips: `generate_media(kind='animation', prompt=...)` with a SPECIFIC prompt describing the exact UI elements, interaction sequence, timing feel, and visual style. Vague prompts produce bad output. (Full guide: resource `clueso://docs/animation-prompts`.) 6. For AI images: `generate_media(kind='image', prompt=..., style_id=...)`. Pick a style from `find(type='image_gen_style_packs')` — see resource `clueso://docs/generation-styles`. 7. For video clips with source recordings: run `auto_sync` BEFORE generating TTS so the voiceover paces against the demo. See resource `clueso://docs/sync-points`. 8. `get_clip(select=[], render={})` to preview, iterate. 9. Share the `projectUrl` (returned by `create_project`) when done. ## Authoring a NEW clueprint Structure it like a polished design document — never a code dump. - Folder layout: `README.md` (overview), `design/` (colors.md, typography.md, backgrounds.md, animation.md), `layouts/` (one .md per distinct clip layout, named by purpose not clip index — e.g. `title-slide.md`, not `clip-0.md`), `rules/` (composition.md, voiceover.md, editing.md), `screenshots/`. - Markdown only — no JSON or config files. - Every layout file MUST start with the rendered screenshot: ``. To capture: call `get_clip(select=[], render={save: true})` per clip, then `update_clueprint(files=[...])` with the returned `presigned_url` as `source_url`. - Set the clueprint thumbnail via `update_clueprint(thumbnail_path=...)` after screenshots exist. - Full authoring guide (folder details, anti-patterns, color-block syntax): resource `clueso://docs/clueprint-authoring`.