Composing a scene

Read the scene schema once before your first edit (picsart_scene_capabilities with sections ["schemaSummary"], then ["schema:<Name>"] for each definition you need, never ["schema"] whole), then build and change the scene with picsart_scene_patch. For a first scene, the quick-merge-and-export recipe (picsart_scene_recipe) holds a working tool-call sequence to start from.

Media

A layer declares its file once in assets as { id, type: "video", uri: <url> } and points at it by id: content: { kind: "media", assetId: "<id>", fit, trim }. The scene document has no assetType field and no video kind, and an assetId holding a URL is unknown_asset_ref. Keep each layer's trim in its own source's seconds, with BOTH in and out. Skip dead ranges: trim around them rather than speeding through them.

Audio

Voice-over plays as audio layers (content: { kind: "audio", assetId, trim: { in, out } }), each with its layer's start at the moment it is heard. A step's line starts 0.15 s after its panel appears, so the picture lands first. Every trim needs BOTH in and out; a trim with only in is a missing_field error. Mute a recording's own track (muted: true on its media content) unless its sound is being kept. If the scene schema ever lists no audio layer, say so and stop — do not export a silent video and do not invent a mix.

Fonts

Fonts are declared assets. Declare the font once in assets ({ id, type: "font", uri }) and reference that id as font.family in every text and caption style; a family name the scene does not declare fails to resolve at export. If a font cannot be found or does not resolve, name it to the user; never swap in another font without saying so.

Name the weight in the face, not in font.weight. font.weight renders only where the scene is resolved natively; a runtime that draws a translated scene ignores it and draws the face font.family names at its own weight (validate_scene warns font_weight_no_op). For bold text, use a bold face, such as a catalog key like acumin-pro-bold, or a declared font asset of that weight, and leave weight out.

The face must draw every character. A face that lacks a character draws nothing or a box in its place, and no font tool says which scripts a face covers. For words in basic Latin, most faces will do. For accents or another script (Cyrillic, Greek, Arabic, Devanagari, Chinese, Japanese, Korean …), prefer a face whose name names that script, or search by the name of a family made for it. Then prove it on the first frame that carries the rarest characters; if any is missing, pick another face, build again, and tell the user which face you used.

Overlays

An overlay never blinks. When a caption, a title or a sticker follows another in the same place, start it where the last one ends, and never let an overlay's opacity drop to 0 for a frame or two: a gap that short reads as a blink.

Transitions

When a panel replaces the one before it, a hard cut is fine and keeps the energy; a soft seam ('crossfade', 0.3–0.5 s) suits a change of layout. Check the live catalog with picsart_scene_capabilities (sections: ["transitions"]) before naming any other transition.

Reusable parts

When you build a custom character or a part the user may want to adjust, declare root parameters for the knobs they will want (pose, expression, timing, strength): plain names in their terms, tight min/max (not 0..4000), a default, a group per body part or concern, a description. A draggable point is type: "vec2" with frame: "composition", or frame: {"layer": "<id>"}. Motion goes in root actions whose parameters tracks key only number, boolean, text, color, vec2 or vec3 parameters, with no $eval (scene-animation-reference, references/named-actions.md). picsart_scene_tune (see motion-design-craft) tunes what is declared, plus root layers' position.