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.
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.