moda-video-motion

moda-video-motion

<!-- moda:banner -->

PREREQUISITE — load moda-core once per session (step-0, write contract, free/metered map). Already loaded? Skip ahead. If you cannot load it, the non-negotiables: run moda doctor --json before anything; moda brand list before creating; writes that pin a revision use your last read's — on stale_revision, re-read and retry once (it heals); send the canvas link the moment it exists; stuck or failed? moda ask "<question>" — free and fast, never guess.

<!-- /moda:banner -->

Sizes and defaults

Piece	Size	--category	Export
Landscape motion / stinger	1920×1080	animation	--format mp4 --page N
Vertical post, story, reel	1080×1920	animation	mp4 (gif for a loop)
Square animated post	1080×1080	animation	mp4 or gif
Animated banner ad	the ad's exact size	animation	gif
Shader-fill background	any canvas	any	mp4/gif — it freezes in stills

Five facts that decide most of the work:

• Keyframes and clip sequencing apply ONLY on --category animation; on any other canvas every motion call is dropped with a warning. Animated shader fills move anywhere.
• Static exports (png/jpeg/pdf/pptx) of animation and video-filled nodes render BLANK or frozen — deliver mp4/gif, and say so if a still is requested.
• mp4/gif REQUIRE --page N: one animated page per file. A page with no animation rejects typed no_animation — the honest answer is a still + the link.
• One stitched film from many scenes: moda export CANVAS_REF --format mp4 --scope sequence renders all visible pages of a multi-page animation canvas as ONE video, in order, transitions included — no --page, mp4 only, and the 18000-frame / 600 s mp4 ceiling covers the WHOLE film (600 s at 30 fps). The editor's export panel has the same "sequence" mode as the interactive alternative. A canvas with a persisted Main Edit timeline exports it with --scope main_edit (mp4 only, page-less like sequence). --fps picks the rate (mp4 24|30|60 default 30, gif 10|12|15|24 default 12); 60 fps halves the longest exportable mp4 film (300 s; a gif is capped at 9000 frames / 300 s).
• Everything in this recipe is unmetered: iteration costs nothing.

Recipe — motion on a canvas

1. moda canvas create --name "[Piece]" --intent "[one-line brief]" --size [WxH] --pages 1 --category animation --brand [KIT] — send the link immediately.
2. Author the still frame FIRST — real type, brand geometry, layout: moda canvas markup [CANVAS_REF] --file - --page [PAGE_ID] (references/markup.md). Motion on a bad frame is a bad piece that moves.
3. moda canvas screenshot [CANVAS_REF] — fix the frame before animating.
4. Add motion: moda canvas edit [CANVAS_REF] --file motion.js — a motion.page(...) program with tweens, effects, staggers and recipes. Read references/motion-recipes.md FIRST: its opening "motion model" section is the five rules that decide whether the motion is correct (rest state, one track per target, what blend makes keyframes mean, why endMs is not a snap-back point, how an endless loop is authored), and the named recipes — logo sting, animated stat, kinetic type, shader background — follow it. Author from that file; don't probe.
5. Draft-judge the movement: moda export [CANVAS_REF] --format gif --page [N] -o draft.gif and look at it. A screenshot shows one frozen frame — it cannot tell you whether the motion works.
6. Deliver: live link FIRST, then moda export [CANVAS_REF] --format mp4 --page [N] -o [piece].mp4. Read warnings[].

Recipe — footage under real type (timeline compositing)

1. Get the clip into team files: moda file upload [clip.mp4], or reuse the durable file_… a generated render returned (moda-video-clip owns generation).
2. Animation canvas at the delivery size, then place the clip with <video src="file_…" width="1920" height="1080" fit="cover"/> via moda canvas markup [CANVAS_REF] --file - --page [PAGE_ID] — the clip is a fill; layer type and brand marks above it.
3. Sequence and trim in moda canvas edit [CANVAS_REF] --file cut.js (t.video(node, { startMs }); trim/rate/loop via update() — references/edit-code.md).
4. moda export [CANVAS_REF] --format mp4 --page [N] -o [piece].mp4, then read warnings[]: server mp4 muxes audible clip audio, and audio_source_dropped names anything that did not survive. Relay it — never a silent loss.

Examples

• "an animated banner ad, 300×250" → motion recipe at the ad's exact size → gif.
• "a stinger from our logo" → motion recipe, recipe-rise + a shader backdrop.
• "make this post move" → import/rebuild the frame on an animation canvas, then animate.
• "cut these two clips together with our headline over them" → compositing recipe.
• "a video from these 5 photos" → compositing recipe: place, sequence, export mp4.

Errors

Any typed error → load moda-core and read its recovery reference. Edit programs are atomic — a failure means NOTHING applied: re-read, fix the program, re-run. no_animation on export means the page has no motion yet.

Make it recurring

The weekly animated post → moda-automate; a stinger or lower-third you will reuse on every future piece → moda-templates.

See also: moda-video — the lane fork, generated clips, cost boundaries · moda-core — the contract, recovery, everything Moda can do.

References

Doc	Load when
references/motion-recipes.md	ALWAYS before authoring motion — the motion model, then the named deliverables (logo sting, teaser, animated ad)
references/edit-code.md	before writing an edit program: batches, revisions, warnings
references/video.md	the timeline API, canvas video placement, export rules — jump to "The motion timeline API"; the long first half is the generated-clip model roster, which this lane does not need