Morpha

Add an audio overlay (mp3/m4a/wav/ogg) scheduled at a frame-aligned start. The asset must already be uploaded (upload_audio, create_upload_link, or the editor); pass the upload's returned `filename`, and its `name` as the track's label. 30 fps; convert seconds with frames = round(s * 30). Plays in the editor preview and is mixed into the MP4 export.

Build a caption track from pre-timed lines (e.g. derived from transcribe_clip's word timings). mode "line-sync" (default) creates one text layer per line, each shown only during its [startFrame, endFrame) window via hold-eased opacity keyframes — the active-line karaoke read; mode "static" makes a single layer with all lines joined. `style` picks a preset look. Lines default to a lower-third band. The caption layers are always wrapped in a "captions" group so they don't clutter the layers list. Returns the created text element ids plus `groupElementId` (the captions group).

Add or overwrite a colour keyframe on a fill track. Targets a leaf (shapes.<id>, image.<id>, video.<id>, group.<id>). The canvas backdrop is the pinned is_background image_layer (the literal 'background.canvas' is accepted as a synonym for its element id). The value is a Fill — adjacent keyframes crossfade stop-by-stop. 30 fps; frame is 0-indexed.

Draw an editable arrow / curved line — a stroked quadratic bezier with an arrowhead. Specify the two endpoints (x1,y1)→(x2,y2) in canvas pixels; `bend` pushes the midpoint perpendicular (px, 0 = straight line, positive/negative curves either way). `color` #rrggbb, `stroke_width` px, `arrow_head` none|end|both (default end). Use this for callout arrows (e.g. swooping into a link).

Add one hostname to the project's embed allowlist (the hostnames permitted to load the public <morpha-video> embed). Idempotent — re-adding an existing entry is a no-op. The origin is normalized to a bare lowercased hostname (scheme/port/path stripped). Morpha sends that website no request; any page on it may then load the project. Reference: https://morphareels.ai/docs/tools#addembedoriginorigin

Add an item from the user's Collection into a project as a self-contained COPY. Pass the destination `projectId`, plus the `sourceProjectId` + `elementId` of an item from list_collection. Copies that layer (a whole group brings its children) plus its image/clip/font bytes into the destination at fresh ids and its original canvas position — fully detached, so it is immediately yours to edit and nothing links back to the source (deleting or changing the source never affects this copy). The element must actually be in the source project's collection and you must be able to read that project. An open editor on the destination picks the copy up within a few seconds — no refresh needed. Returns { addedElementId, count }.

Add an image layer. The asset must already be uploaded (the editor's drag-drop, upload_image, create_upload_link, or POST /api/upload-asset/<projectId> with the raw bytes and an X-Upload-Name header). Every upload returns { filename, name }: pass `filename` (the stored file's id) here, and `name` as the layer's label. To duplicate an existing layer, reuse its filename — the editor auto-assigns a fresh id.

Add or overwrite a keyframe on a layer's animation track. For leaves (image/video/shape), x/y/rotation keyframes are ABSOLUTE canvas-space values: x and y are the layer centre's pixel position (canvas is 1080×1920), rotation is degrees. For groups, x/y keyframes are translation offsets applied around the group's frozen pivot, and rotation is the group's absolute angle. scale orbits the layer/pivot centre (1 = no change). opacity is 0..1. 30 fps. When a keyframe track is present on a property, it OVERRIDES the layer's static base value at every frame.

Add many keyframes to ONE element's ONE property in a single call, with an optional loop mode applied in the same call. The idiomatic form when every layer in a multi-element animation gets its own track (ripple dot pulse, snowflake fall, equaliser-bar wave). Factors elementId + property out of the loop body and folds set_track_loop in. Use set_keyframes_batch instead when you need to mix elements/properties in one atomic call.

Embed another of the user's projects ("a morpha") inside this one as a version-pinned band. The source's layers are inlined into the host as a collapsible group, re-keyed to fresh ids, pinned to one immutable version of the source. Pass the source project's id as source_morpha_id (and optionally a version label); the server resolves and inlines the pinned version. Editing the band's inner layers only affects THIS video — the change is local and never propagates back to the source. To pin the band to a different saved version, re-pin it from the editor's Inspector. describe_video marks an embedded band with morpha:true + source_morpha_id so you can tell it apart from a plain group.

Append a page to the project — works on any project, turning a single-page video into a multi-page one. Without duplicate_index a blank page is appended, sized to the project's canvas. With duplicate_index the page at that position is deep-copied (a fresh id is minted). There is no limit on page count. The new page becomes the active page; its index is returned. For several versions of one video (hooks, languages, a sheet's rows), make pages of one project with add_page and duplicate_index. Exporting gives one video per page, and pages have no limit. To edit the copies, select_page each one and describe_video for its element ids; to export them, use the editor's Videos option or renderVideo with page.

Add a shape layer. `kind` selects the primitive: rect | ellipse | triangle | star | pentagon | hexagon | arrow | heart | rounded-rect | diamond | parallelogram | trapezoid | semicircle | ring | pill | cross | heptagon | octagon | star-4 | star-6 | sparkle | burst | arrow-left | double-arrow | chevron | block-arrow-up | curve | lightning | speech-bubble | location-pin | checkmark | x-mark | shield | cloud | crescent | teardrop | banner. All are native vector shapes; never substitute an image layer for one. Default-positioned in canvas centre if x/y/w/h omitted.

Add or overwrite a speed-ramp (time-remap) keyframe on a video layer, for a rate that CHANGES over the clip. `frame` is a PROJECT-timeline frame and must sit on the clip (at or after its timeline_start_frame); the curve itself is anchored to the clip, so moving the clip carries the ramp with it and never changes its duration. For a constant slower/faster clip use set_clip_speed instead. `rate` is the playback rate at `frame`: 1 = real-time, 0.5 = half-speed, 2 = double-speed. Range: rate in [0.1, 8]. The ramp multiplies the layer's constant speed, and the clip's timeline length is derived from the resulting curve.

Create a new text layer — a first-class leaf that animates, groups, and z-orders exactly like an image or shape. The renderer draws live typeset text (multi-line, auto-fit to the box). Defaults: x/y = canvas centre, width 900, height 320, font_family "Hanken Grotesk", text_size derived from existing text layers (or ~10% of canvas height). Also accepts full type styling: font_weight (100-900), font_style (italic), text_transform, letter_spacing, line_height, text_align, text_autofit ("hug" default = box shrink-wraps the text at the fixed text_size, honouring literal newlines, so it can't re-wrap between preview and export — bake your own "\n" line breaks / "wrap"=fixed size + word-wrap to the box / "fit"=auto-size to fill the box, grows and shrinks / "shrink"=legacy shrink-only), text_valign (top/middle/bottom), an outline (stroke_width + stroke_color), and text_shadow. Returns the new layer's id + element id (text.<id>).

Add a layer to the user's reusable Collection. Pass ANY element id — a leaf (text.<id>, image.<id>, …) or a whole group.<id> (a lower-third, logo sting, brand intro). It then appears in the user's Collection (list_collection), where they — and, if this project is in a workspace, every teammate — can drop a self-contained COPY of it into any other project (add_from_collection). Copies are IMMUTABLE: adding copies the whole subtree + its asset bytes, so editing or deleting this source never changes a copy already placed elsewhere. Works on solo projects too (a personal Collection). Give the layer a clear name first (rename_layer / rename_group) — that name is what shows in the Collection.

Add a video layer. The clip must already be uploaded (the morphareels-sdk's client.addVideo, or the editor). An upload returns { filename, name }: pass `filename` (the stored clip's id) as `clip`, and `name` as the layer's label. To duplicate an existing layer, reuse its clip filename — the editor auto-assigns a fresh id.

Apply a canned animation preset to a layer.

Apply the same preset to a LIST of layers with a per-element startFrame offset — one call instead of N apply_preset calls. For diagonal pop-in grids, sequential list reveals, ring-pulse sweeps. The startFrame for entry i is `startFrame + i * stagger`. Order the elementIds in the visual order you want the animation to cascade.

Report whether a clip — or every video clip in the project, if `clip` is omitted — has been through the browser-side video-processing pipeline: proxy build, audio split, transcription, OCR (text regions). Processing never runs on the server. The preview proxy is mandatory: every processing run builds it (client.addVideo / client.processClip / client.processProject in the morphareels-sdk npm client, which drive local Chrome), and the Morpha editor builds any missing proxy for every page's clip when the project is opened. The other steps run through the same npm client or in the editor. Returns { ok: true, data: { clips: [{ clip, processed, steps: { proxy, audio_split, transcript, text_regions } }], allProcessed } }, where each step is 'ready' | 'pending' | 'running' | 'unavailable' | 'cancelled' | 'error'. 'cancelled' is a transcript the user stopped in the editor: it stays stopped across opens, and only the editor's Re-run starts it again. audio_split stays 'pending' until the user splits the clip's audio into its own track in the editor (Inspector → Audio → Split audio) or the SDK's audio_split step runs; it never gates `processed`, and an unsplit clip plays its own sound. Use it to know whether transcribe_clip / detect_text_regions will return data, and to surface an 'unprocessed' state to the user.

Create a new project and return its server-minted id. The id is an opaque v4 UUID assigned automatically — you never choose or name it; refer to the project by its `name`. By default this mints a fresh BLANK project (empty canvas, no layers) — creation is independent from cloning. Pass `fromProjectId` ONLY when you want to clone: the new project then copies that project's JSON, uploaded assets, and uploaded clips, and — like duplicate_project — FOLLOWS THE SOURCE'S workspace by default (cloning a team project stays in that team; a blank project is personal). Pass `workspaceId` (from list_workspaces) to place it in a specific workspace instead — requires an edit-capable role there — or null to force it into the caller's personal space. If the clone source lives in a workspace you can only view, the call FAILS rather than silently making a personal copy — pass workspaceId:null for a personal copy. The user's editor session won't auto-refresh — they'll need to reload to see the new project in the picker.

Put a file from the caller's own disk into a project: an image (.png/.jpg/.jpeg/.gif/.webp/.svg), an audio track (.mp3/.m4a/.wav/.ogg/.aac) or a font (.woff2/.woff/.ttf/.otf). Returns { uploadUrl, filename, name, command, expiresAt, maxBytes }. Run `command` from a shell (a curl line that PUTs the file's raw bytes to uploadUrl), then pass the returned `filename` (the file's id, never shown to a person) to add_image_layer, add_audio_overlay or set_custom_font. The link takes one file, stored under the id it was minted with, for 15 minutes; a second upload in that window replaces the first. The upload is checked as an editor drag-drop is: size cap (16 MB for an image or font, 50 MB for audio), SVG safety, storage quota. A client with no shell passes a public URL to upload_image or upload_audio instead. A video clip is not taken here, because its preview proxy is built on the caller's machine: use the morphareels-sdk's client.addVideo. Reference: https://morphareels.ai/docs/tools#createuploadlinkname

Create a new workspace (a shared team space) owned by the caller, and return it as { id, name, role, memberCount }. Use this when the user wants a new place to group projects — then move_project_to_workspace files projects into it, and create_project can place new ones there directly. The caller becomes its owner. Requires an account with an email (workspace membership is email-based), so a keyless identity cannot create one. Refuses with a conflict if the caller already owns a workspace with the same name, which is almost always a repeated request rather than a genuine second workspace. Refer to it by `name` when talking to the user, never the id.

Ripple-delete a time window [startFrame, endFrame) — remove that span and pull all later content earlier by delta = endFrame - startFrame (the NLE 'ripple delete' / 'close gap'). Shifts every keyframe, colour keyframe, marker, audio overlay, loop region, and start_at through the cut (a speed ramp is anchored to its clip and rides along unchanged), and is SOURCE-AWARE for video layers: a clip that straddles the cut is trimmed, and one whose interior is removed is SPLIT into two layers. Audio overlays interior to the cut are truncated at the seam (overlays have no source-in to bridge the gap). REFUSES to cut across a video layer that carries speed-ramp keyframes — remove them, or cut outside that layer's span, first. The composition length shrinks accordingly (an authored length loses only the overlap with its visible region). Frames are 0-indexed project-timeline frames at 30 fps; endFrame is exclusive and clamped to the composition length.

Remove the page at `index`. Fails on an out-of-range index or when only one page remains — a project must keep at least one page. The active page stays active; when the active page itself is deleted, active_index falls to the neighbouring page (the one that slid into its position, or the new last page).

Permanently delete a project: its JSON, shortlist, versions, uploaded assets, and uploaded clips. Requires edit access — the owner, a workspace editor/admin/owner, or a direct-share editor; anyone else gets the opaque not-found. Deleting the last remaining project is allowed. The user's editor session won't auto-refresh — if they were viewing the deleted project they'll need to reload.

Permanently delete one saved version (bookmark or auto-snapshot). Accepts the version's UUID `id` or the `v<N>` shorthand. The bookmark v<N> sequence keeps gaps — numbers never re-shuffle — so any external snippet referencing the deleted `v<N>` will fail to resolve afterwards. Idempotent: deleting a non-existent version is a no-op.

Structural OVERVIEW of the composition (the table of contents) — canvas size, duration, platform_safe_area (the part of the canvas TikTok / Reels UI and Instagram's feed crop leave visible: keep text, captions, logos and buttons inside it; null when nothing is covered or cropped), the backdrop summary, and a z-ordered tree (top of stack first) of every layer with its elementId, type, name, type label (filename/clip/text/kind), geometry (x/y/width/height), and which properties are animated. Does NOT include keyframe values or styles — those are unbounded. On a multi-page project the tree describes the ACTIVE page and the data carries a `pages` block ({ page_count, active_index, pages: [{ index, name, has_video }] }) — content tools target that active page; use select_page to switch which page they target, add_page / delete_page / reorder_pages to manage the pages. Start here, then call inspect_layers([elementId, …]) for full detail on the specific layers you'll change. Don't guess keyframe/style values from this overview.

Return the OCR text regions detected in a clip's video frames OR a still image asset. Pass either `clip` (a video.<id>.clip filename) or `image` (an image layer's filename) — not both. Video clips are sampled every 0.3s at upload time; images are OCR'd once. Results are cached in R2 next to the source. Returns { status: 'ready' | 'not-ready', frames: [{ frame, time, words: [{ text, x0, y0, x1, y1, confidence }] }], videoWidth, videoHeight }. For an image there's a single frame (frame 0); videoWidth/videoHeight are the image's pixel dimensions. Each `words` entry is one detected text line — `text` may hold several words, the box is axis-aligned, and `confidence` is 0–100. Coordinates are in the SOURCE pixel space (not canvas space). Use to know where titles / subtitles / lower-thirds are baked into the video or image so the Morpha title + intro graphics can be positioned to not collide.

Composition primitive: clone a leaf (image.<id> / video.<id> / shapes.<id> / text.<id>) `count` times, applying a cumulative per-step transform — copy i is offset by i·(dx,dy) px, rotated by i·d_rotation°, and scaled by d_scale^i. One call instead of dozens: a circle of stars (dx/dy + d_rotation), a row of chevrons (dx), a fractal (d_scale<1 + d_rotation), a staggered grid. Styles are copied; animate the result afterwards (e.g. group + a cycle-loop track for endless marching).

Duplicate an existing project into a brand-new one — a full copy of its layers, animations, styles, uploaded assets, and clips. Pass the SOURCE project's `projectId`; the copy gets a fresh id automatically (ids are opaque — never shown to the user). Defaults the copy's name to "<source name> copy" unless you pass `name`. WORKSPACE: the copy FOLLOWS THE SOURCE by default — a project in a workspace is copied into that SAME workspace, and a personal project stays personal. Pass `workspaceId` to override: a workspace id (from list_workspaces) to place the copy in a specific workspace (you need an edit-capable role there), or null to force the copy into your personal space. If the source lives in a workspace you can only VIEW, the call FAILS rather than silently making a personal copy — get an editor role there, or pass workspaceId:null. (Duplicating a project shared with you from a workspace you're NOT a member of lands in personal, since you can't be placed in that workspace.) The returned `workspaceId` tells you where it went. The user's editor won't auto-refresh — they reload to see the copy in the picker. For several versions of one video (hooks, languages, a sheet's rows), make pages of one project with add_page and duplicate_index. Exporting gives one video per page, and pages have no limit.

Fade a layer's opacity between two frames in one call.

Clear an authored composition length and return to AUTO-FIT — the comp length tracks the furthest content (keyframe / video window / audio end) again, with a 1-second floor. The inverse of set_duration. NOTE: headless (no loaded media) this can UNDER-fit when a video layer's source_out_frame is null — its natural length is unmeasurable, so it contributes only its start frame; the length self-corrects the next time the project is opened in the editor, where the real clip durations are known.

Freeze the picture at a frame: the clip is CUT there and a still of that frame is inserted between the halves, pushing everything after it later (the NLE 'frame hold'). This is how you hold a moment — play, freeze, continue. The still is an ordinary IMAGE layer showing that frame for `holdFrames` (default 150 = 5s at 30fps), so you resize, split, move or delete it like any other layer. `image` is the filename of a PNG of that frame, already uploaded to the project's assets — rendering one needs a browser, so capture and upload it first. The reply's `frozenSourceFrame` is the SOURCE frame that was frozen, which differs from `frame` on a retimed clip. `frame` must be strictly inside the clip.

Wrap sibling elements in a new group. USE THIS whenever several layers are one thing — a butterfly assembled from wings + body + antennae, an icon built from primitives, a card + its title + badge, a lower-third — and name the group what the thing is; a multi-shape object left as loose siblings is a defect the user has to clean up, and the group's name is their only handle on it. The group composes its x/y/scale/rotation/opacity onto its descendants (so one track flies/spins/fades the whole thing) and pivots rotate/scale at its (pivotX, pivotY), seeded to the centroid of its children at create time. The group's x/y track values are translation offsets applied around the pivot — groups have no static body of their own. All listed elementIds must currently share the same parent (root, or one existing group).

Full per-element drill-in — the 'open this layer' half of the browser. Returns each named element's COMPLETE record: all of its own fields plus its animation tracks (every keyframe), colour/fill tracks, track-loop (extrapolation) modes, and style. Pass the elementIds you read from describe_video; pull detail only for the handful of layers you're about to mutate, not the whole project.

List the user's reusable Collection — layers they added with add_to_collection (lower-thirds, logo stings, brand intros, or any single layer). Returns { items: [{ scope, workspaceId, sourceProjectId, sourceProjectName, ownerEmail, elementId, name, kind, childCount }] }. `scope` is "personal" (from the user's own solo projects) or "team" (from a workspace they belong to). Show the user each item's `name` (and its `sourceProjectName`); `sourceProjectId` + `elementId` feed add_from_collection to drop a self-contained COPY into another project. Works on a solo account (personal items always included); takes no arguments.

List available font families across every source the editor knows about (Google + Bunny + Fontshare + Fontsource + Velvetyne) PLUS the project's user-uploaded custom_fonts (surfaced as source: "custom"). Use this to discover families before set_layer_text / add_text_layer when you don't know what to pick. Returns { fonts: [{family, source, weights, italics}], total, returned, sources }. Filter via `q` (case-insensitive substring on family) and/or `source`; cap with `limit` (default 50, max 1000). Picking any returned family in font_family Just Works — the editor's loader dispatches to the right CSS/FontFace endpoint by source.

List projects as { id, name, editorUrl } entries. The id is what every other tool's `projectId` argument takes. `name` is the human-readable label shown in the editor's project picker ("Untitled" when no name has been set — ids are opaque and never shown to the user, so always refer to a project by its name). `editorUrl` is a tappable link that opens that project in the editor — offer it to the user (by name) when they want to look at one. By default lists the user's OWN personal projects (those not in any workspace). Pass `workspaceId` (from list_workspaces) to instead list the projects that live in that workspace — including teammates' — each with the owner's `ownerEmail`. Call this when the user asks "what projects do I have?" or hasn't named a project but you need to operate on one.