@shotstack/cli 0.10.0 → 0.12.0

package/skills/shotstack/references/motion.md

@@ -1,119 +1,98 @@
-# Motion language — the house vocabulary
+# Motion on Shotstack
 
-A small, closed set of timing, easing and stagger values that **every** animated clip should share. Composing motion from these tokens — instead of inventing a new easing and duration per clip — is what makes a multi-clip edit feel like one production instead of eight unrelated effects. Reach for these before hardcoding a `duration`, an `ease`, or a delay.
+What can move in an edit, on which layer, and how much control each layer gives you. Timing, easing, travel and rhythm are design choices for the piece; this file covers the mechanics.
 
-> The values are video-paced for Shotstack's **second-based** timeline (most UI-motion guidance is frame-based). The GSAP/CSS easings below stand in for spring physics, which the render engine doesn't expose.
+There are two kinds of motion. **Built-in motion** (clip transitions, effects and keyframes, and `rich-text` animation) takes fixed options from the schema and needs care when combined on an existing asset. **`html5`** takes any seekable animation.
 
-## The tokens
+## Time
 
-### Duration scale (seconds)
+- **The timeline is in seconds.** Clip `start`/`length`, keyframe `start`/`length` and GSAP `duration` are all seconds. Convert frame-based specs with the output frame rate (`output.fps`): at 25 fps one frame is 0.04 s.
+- **An `html5` clip captures its animation for the clip's `length`,** measured from the clip's start. Animation that runs past the end is cut; animation that finishes early holds its last state.
 
-| Token | Seconds | Use for |
-|---|---|---|
-| `instant` | 0.2 | micro shifts, near-imperceptible feedback |
-| `fast` | 0.33 | **exits**, small moves |
-| `base` | 0.6 | **the default entrance** — ~80% of reveals |
-| `slow` | 0.8 | large entrances, hero moves |
-| `slower` | 1.0 | full-scene transitions |
-| `hold` | 1.5 | minimum settled hold before a clip ends |
-
-Most entrances are `base` (0.6 s). Exits are deliberately faster than entrances — get out of the way faster than you came in.
+## What each layer can move
 
-### Easing — one house curve, no overshoot by default
-
-| Where | Entrance / settle | Exit |
+| Layer | What moves | Control |
 |---|---|---|
-| **html5 GSAP** | `ease: 'power3.out'` | `ease: 'power2.in'` |
-| **html5 CSS** | `cubic-bezier(0.16, 1, 0.3, 1)` | `cubic-bezier(0.3, 0, 0.8, 0.2)` |
-
-`power3.out` / `cubic-bezier(0.16,1,0.3,1)` is the **house ease** — a confident "fast then settle" that reads like a heavily-damped spring with **no bounce**. Use it for anything the eye tracks (position, scale, blur). Never use raw `linear` / `'none'` for motion the eye follows; `linear` is only correct for a continuous drift (grain, marquee, a constant-speed ticker).
-
-**Overshoot is opt-in, not default.** A gentle `back.out(1.4)` (GSAP) is reserved for **one** "hero" element per scene where a pop is intended — a logo sting, a headline punch. Calm is the default; energetic is fine when it *earns* it. Never sprinkle bounce across every element.
-
-### Stagger — one value
-
-`0.13 s` (≈ 4 frames at 30 fps) between siblings in any cascade — words, list items, grouped reveals. One value everywhere; present but never frantic. In GSAP: `stagger: 0.13`. In CSS: `animation-delay` steps of `0.13s` (`0s, 0.13s, 0.26s, …`).
+| Clip `transition` | the whole clip, in and out | `fade` `reveal` `wipe*` `slide*` `carousel*` `shuffle*` `zoom`, each with `Slow`/`Fast` variants. Timing and easing are engine-fixed. |
+| Clip `effect` | a Ken Burns drift on an image or video | `zoomIn` `zoomOut` `slideLeft` `slideRight` `slideUp` `slideDown`, each with `Slow`/`Fast` |
+| Clip keyframes | `scale`, `opacity`, `offset.x`/`.y`, `transform.rotate.angle`, `transform.skew.x`/`.y`, an asset's `volume`, a video's `speed` | Tween arrays with your own `start` and `length`; `interpolation` and `easing` from fixed lists (below) |
+| `rich-text` `animation` | the text's entrance | `preset` + `duration` + `style` + `direction`; easing is engine-fixed |
+| `html5` | anything inside the clip | any seekable GSAP, anime.js, Lottie or CSS animation, any easing, per-element timing. Rules in [`html5.md`](html5.md). |
 
-### Travel & restraint
+### rich-text animation
 
-- **Travel small:** translate **12–24 px**, not 80. The eye should feel the motion, not be dragged by it. Blur reveals: `10 px → 0`. Scale reveals: `0.92 → 1` (below ~0.85 is dramatic-zoom territory — avoid unless intended).
-- **One focal element per moment.** If two things compete, stagger them. Don't animate everything at once.
-- **Let it settle.** After a reveal lands, hold it (a trailing `gsap.to({}, { duration: <hold> })` or enough clip `length`) before the clip ends. Never cut a reveal the instant it arrives.
+| Preset | Example |
+|---|---|
+| fade in | `{ "preset": "fadeIn", "duration": 0.6 }` |
+| rise + fade | `{ "preset": "ascend", "duration": 0.6, "direction": "up" }` |
+| slide in | `{ "preset": "slideIn", "duration": 0.6, "direction": "up" }` |
+| word-by-word cascade | `{ "preset": "shift", "duration": 0.6, "style": "word", "direction": "up" }` |
+| typewriter | `{ "preset": "typewriter", "duration": 0.8, "style": "character" }` |
 
-## The three motion layers
+Schema constraints (`@shotstack/schemas` → `RichTextAnimation`): `preset` ∈ `fadeIn · slideIn · typewriter · ascend · shift · movingLetters`; `duration` 0.1–30 s; **`style` (`word`/`character`) applies only to `typewriter` and `shift`** (ignored on the others); `direction` is **required** for `slideIn`, `ascend`, `shift`, `movingLetters`. Rich-text `animation` is **entrance-only**: exits use the clip `transition.out`. For control over easing, per-character timing or exits, use `html5`.
 
-Shotstack exposes motion at three levels of control. Use the tokens at whichever level fits; reach down a level only when you need more control.
+### Clip keyframes
 
-| Layer | Control | Where the tokens apply |
-|---|---|---|
-| 1 — **clip `transition` / `effect`** | coarse (whole-clip in/out; only `Slow`/`Fast` variants) | pick `fade`, `slide*`, `zoom`; `Slow` ≈ `slow`, default ≈ `base`, `Fast` ≈ `fast` |
-| 2 — **`rich-text` `animation`** | medium (`preset` + `duration` + `style` + `direction`) | set `duration` from the scale; `style:"word"` gives the staggered cascade |
-| 3 — **`html5` GSAP / CSS** | full (any property, any easing) | the full vocabulary below — durations, the house ease, `0.13` stagger |
+- `interpolation` is `linear` (the default), `bezier` or `constant`. `easing` takes effect with `bezier`.
+- `easing` is `ease`, `easeIn`, `easeOut`, `easeInOut`, or `easeIn` / `easeOut` / `easeInOut` followed by `Quad`, `Cubic`, `Quart`, `Quint`, `Sine`, `Expo`, `Circ` or `Back` (for example `easeOutCubic`, `easeInOutBack`).
+- To match an `html5` clip's GSAP ease: `easeOutQuad` ≈ `power1.out`, `easeOutCubic` ≈ `power2.out`, `easeOutQuart` ≈ `power3.out`.
 
-### Layer 2 — rich-text animation, tokenised
+### Combining built-in motion on an existing asset
 
-`animation.preset` maps onto the choreography names; set `duration` from the scale:
+- Keyframes move the whole rendered clip; a `rich-text` preset animates the text inside it. A slide preset plus an `offset` keyframe moves the text twice, so animate each property one way per clip.
+- Keyframe times are relative to the clip's `start`, and a tween that runs past the clip's `length` is cut off.
+- Footage, images and logos are scaled by `fit` first, and keyframe `scale` multiplies that, so a large scale on a low-resolution source shows its pixels.
 
-| Intent | `rich-text` animation |
-|---|---|
-| fade in | `{ "preset": "fadeIn", "duration": 0.6 }` |
-| rise + fade (the workhorse) | `{ "preset": "ascend", "duration": 0.6, "direction": "up" }` |
-| slide in | `{ "preset": "slideIn", "duration": 0.6, "direction": "up" }` |
-| word-by-word cascade | `{ "preset": "shift", "duration": 0.6, "style": "word", "direction": "up" }` |
-| typewriter | `{ "preset": "typewriter", "duration": 0.8, "style": "character" }` |
+## Easing available in html5
 
-Schema constraints (`@shotstack/schemas` → `RichTextAnimation`): `preset` ∈ `fadeIn · slideIn · typewriter · ascend · shift · movingLetters`; `duration` 0.1–30 s; **`style` (`word`/`character`) applies only to `typewriter` and `shift`** (ignored on the others); `direction` is **required** for `slideIn`, `ascend`, `shift`, `movingLetters`. Rich-text `animation` is **entrance-only** — exits use the clip `transition.out` (Layer 1). Easing on the presets is engine-fixed; for full easing control, drop to html5 (Layer 3).
+- **GSAP:** `none`, `power1`–`power4`, `sine`, `circ`, `expo`, `back(overshoot)`, `elastic(amplitude, period)`, `bounce` and `steps(n)`, each as `.in`, `.out` or `.inOut`.
+- **CSS:** any `cubic-bezier()`, `steps()` or `linear(…)` point list, on `@keyframes`, transitions and `Element.animate()`.
 
-## Choreography recipes (html5 / GSAP)
+## Recipes
 
-Pure, seekable GSAP — obey [`html5.md`](html5.md) (no `setTimeout`/`rAF`/`Date.now`/`gsap.call()`; size the clip to the content). Each recipe is a named choreography helper you compose rather than reinventing.
+Syntax starting points, deliberately different in feel. Build each scene on one top-level timeline and place tweens with GSAP's position parameter (`0`, `'<'`, `'-=0.2'`, labels) rather than `delay`.
 
 ```js
-// entryFadeRise — THE workhorse: rise 12px + fade, house ease, base duration
-gsap.from('.el', { opacity: 0, y: 12, duration: 0.6, ease: 'power3.out' });
+const tl = gsap.timeline();
 
-// entryFade — presence only (overlays, avatars)
-gsap.from('.el', { opacity: 0, duration: 0.6, ease: 'power3.out' });
+// settle: rise and fade into place
+tl.from('#title', { opacity: 0, y: 24, duration: 0.6, ease: 'power3.out' }, 0);
 
-// entryScale — calm scale-up
-gsap.from('.el', { opacity: 0, scale: 0.92, duration: 0.6, ease: 'power3.out' });
+// blur reveal: opacity, blur and rise off one tween
+tl.from('#sub', { opacity: 0, y: 16, filter: 'blur(10px)', duration: 0.6, ease: 'power3.out' }, 0.3);
 
-// blurReveal — opacity + blur + rise off ONE tween (one progress, many channels)
-gsap.from('.el', { opacity: 0, y: 16, filter: 'blur(10px)', duration: 0.6, ease: 'power3.out' });
+// pop: overshoot on arrival
+tl.from('#badge', { opacity: 0, scale: 0.6, duration: 0.5, ease: 'back.out(2.2)' }, 0.8);
 
-// wordStagger — each word rises in sequence (wrap words in <span>)
-gsap.from('.word', { opacity: 0, yPercent: 120, duration: 0.6, ease: 'power3.out', stagger: 0.13 });
+// slam: big travel, hard snap
+tl.from('#hit', { opacity: 0, x: -600, skewX: -18, duration: 0.45, ease: 'expo.out' }, 1.2);
 
-// heroReveal — the ONE place a pop is allowed (≤1 per scene)
-gsap.from('.hero', { opacity: 0, y: 16, scale: 0.97, duration: 0.8, ease: 'back.out(1.4)' });
+// character cascade: wrap each character in a <span class="c">
+tl.from('#word .c', { opacity: 0, yPercent: 110, rotation: 12, duration: 0.5, ease: 'power4.out', stagger: 0.03 }, 1.6);
 
-// exitFadeFall — fade + drop, faster, ease-in (an exit doesn't settle)
-gsap.to('.el', { opacity: 0, y: 8, duration: 0.33, ease: 'power2.in' });
-```
+// elastic settle
+tl.from('#price', { scale: 0, duration: 1.1, ease: 'elastic.out(1, 0.45)' }, 2.0);
 
-**Entrance → hold → exit, on one timeline:**
+// exit, overlapping the next beat
+tl.to('#title, #sub', { opacity: 0, y: -12, duration: 0.33, ease: 'power2.in' }, '-=0.1');
 
-```js
-const tl = gsap.timeline();
-tl.from('.el', { opacity: 0, y: 12, duration: 0.6, ease: 'power3.out' })  // in (base)
-  .to({},        { duration: 1.5 })                                       // hold
-  .to('.el',     { opacity: 0, y: 8, duration: 0.33, ease: 'power2.in' }); // out (fast)
+// ambient loop: a drift that runs for the rest of the clip
+tl.to('#glow', { opacity: 0.4, duration: 1.6, ease: 'sine.inOut', repeat: -1, yoyo: true }, 0);
 ```
 
 ### CSS equivalents (no JS)
 
 ```css
-/* house ease entrance */
 .el { animation: rise 0.6s cubic-bezier(0.16, 1, 0.3, 1) both; }
-@keyframes rise { from { opacity: 0; transform: translateY(12px); } to { opacity: 1; transform: none; } }
+@keyframes rise { from { opacity: 0; transform: translateY(24px); } to { opacity: 1; transform: none; } }
 
-/* staggered siblings — 0.13s steps */
-.w:nth-child(1){animation-delay:0s}.w:nth-child(2){animation-delay:.13s}.w:nth-child(3){animation-delay:.26s}
+/* staggered siblings */
+.w:nth-child(1){animation-delay:0s}.w:nth-child(2){animation-delay:.08s}.w:nth-child(3){animation-delay:.16s}
 ```
 
-## Brand kit — set the palette once, re-skin everything
+## Brand kit through merge fields
 
-Don't hardcode hex and font per snippet. Declare the brand as top-level `merge[]` fields and reference the tokens in every clip's `html`/`css`/`js` — one edit re-skins the whole video — brand tokens applied once, via Shotstack merge:
+`merge` find/replace runs over every string in the edit, including `html5` `html`, `css` and `js`. Declare the brand once as top-level fields and reference them in every clip, and one edit re-skins the whole video:
 
 ```json
 "merge": [
@@ -129,23 +108,8 @@ Don't hardcode hex and font per snippet. Declare the brand as top-level `merge[]
 .cta   { background: {{accent}}; }
 ```
 
-`merge` find/replace runs over the whole edit, including `html`/`css`/`js` strings, so `{{accent}}` resolves everywhere. Keep one accent and use it sparingly — a headline word, a number, a CTA, one glow — everything else neutral. **Colour is earned, never sprinkled.**
-
-## Motion checklist
-
-Before rendering anything animated:
-
-1. **Durations from the scale?** (`0.6` in, `0.33` out — not `0.45`, `0.7`, `1.2`.)
-2. **House ease, not linear?** `power3.out` / `cubic-bezier(0.16,1,0.3,1)` for tracked motion.
-3. **Overshoot only on one hero element**, if at all.
-4. **Stagger is `0.13`**, applied via `stagger` / `animation-delay`.
-5. **Travel 12–24 px; scale ≥ 0.92.** Restraint over flash.
-6. **One focal element per moment;** competing elements staggered.
-7. **It holds before it cuts** (settled `hold`, not an instant exit).
-8. **Brand colours via `merge[]`**, accent used sparingly.
-
 ## See also
 
-- [`html5-snippets.md`](html5-snippets.md) — ready-made clips that already follow these tokens
-- [`html5.md`](html5.md) — the html5 sandbox rules these obey (seekable-only, sizing, fonts)
-- `shared/agent-core.md` → "Motion language" — the compact token summary (shared with the MCP server)
+- [`html5.md`](html5.md) — the html5 sandbox: seekable animation only, sizing, fonts, preloaded libraries
+- [`html5-snippets.md`](html5-snippets.md) — ready-made clips to remix
+- `shared/agent-core.md` → "Motion" — the compact summary (shared with the MCP server)

package/skills/shotstack/references/onboarding.md

@@ -42,8 +42,8 @@ e-commerce app full of product images answers question 2).
   (`references/asset-library.md`) and motion-graphic snippets
   (`references/html5-snippets.md`), matched to their stated use case.
 - Use their brand where it exists: colours, fonts and logos from the project
-  or their site rather than an invented look. Follow the house motion
-  language (`references/motion.md`).
+  or their site rather than an invented look. See `references/motion.md`
+  for what each layer can animate.
 - If they chose "many": add merge fields (`{{ placeholder }}`) for the parts
   that vary per video, and show one render with sample values.
 - Loop: compose, then `shotstack validate`, then `shotstack render edit.json

package/skills/shotstack/shared/agent-core.md

@@ -11,17 +11,17 @@ Don't invent property names or enum values. The Shotstack schema is published
 - <https://shotstack.io/docs/guide/llms-full.txt> — single-file LLM-friendly version of the full guide + reference.
 - <https://github.com/shotstack/oas-api-definition/tree/main/schemas> — raw OpenAPI YAML, source of truth.
 
-CSS naming conventions (`alignment`, `vertical: "center"`) **do not** apply. The spec uses precise names that often differ from web/CSS instincts:
+The `rich-text` asset's styling fields look like CSS but aren't: CSS naming conventions (`alignment`, `vertical: "center"`) **do not** apply to them, or to clip properties. The spec uses precise names that often differ from web/CSS instincts. (An `html5` asset's `css` is ordinary CSS.)
 
-| You'd guess (wrong) | API uses (right) |
-|---|---|
-| `alignment` | `align` |
-| `align: "center"` (string on rich-text asset) | `align: { "horizontal": "center", "vertical": "middle" }` (object) |
-| `align.vertical: "center"` | `align.vertical: "middle"` |
-| `font.name` | `font.family` |
-| `duration` | `length` |
-| `transitions: [...]` (array) | `transition: { in, out }` (object) |
-| `fit: "cover"` (CSS instinct: scale+crop maintaining aspect) | `fit: "crop"` — Shotstack's `cover` STRETCHES without maintaining aspect ratio |
+| You'd guess (wrong) | API uses (right) | On |
+|---|---|---|
+| `alignment` | `align` | `rich-text` |
+| `align: "center"` (a string) | `align: { "horizontal": "center", "vertical": "middle" }` (object) | `rich-text` |
+| `align.vertical: "center"` | `align.vertical: "middle"` | `rich-text` |
+| `font.name` | `font.family` | `rich-text` |
+| `duration` | `length` | clip |
+| `transitions: [...]` (array) | `transition: { in, out }` (object) | clip |
+| `fit: "cover"` (CSS instinct: scale+crop maintaining aspect) | `fit: "crop"` — Shotstack's `cover` STRETCHES without maintaining aspect ratio | clip |
 
 When the API rejects a property, the error message names the field — fix and retry. Don't guess twice.
 
@@ -89,11 +89,16 @@ Clips on the same track must not have overlapping `start`/`length` ranges — ov
 
 Sequential clips (one finishes, the next starts) **can** share a track — `"start": "auto"` chains them. A cross-fade needs two tracks with a small time overlap and a `transition` on each.
 
+<!-- surface:cli -->
 **Validate before you render:** `shotstack validate <file>` catches same-track overlaps — plus unloaded fonts, non-public `src` URLs, and wrong property names/enums — offline, no API key, no credits.
+<!-- /surface -->
 
 ## Clip motion & rich-text fields (cheatsheet)
 
-Compose from this rather than round-tripping the full schema — these are the values renders actually use. (`api.edit.json` stays authoritative; `shotstack validate` checks against it.)
+Compose from this rather than round-tripping the full schema — these are the values renders actually use.
+<!-- surface:cli -->
+`api.edit.json` stays authoritative; `shotstack validate` checks against it.
+<!-- /surface -->
 
 **Clip-level (wraps any asset):**
 
@@ -132,16 +137,17 @@ Compose from this rather than round-tripping the full schema — these are the v
 
 For motion beyond this (kinetic type, value reveals, shine sweeps, grain, pulsing CTAs) reach for `html5` — see [`references/html5-snippets.md`](../references/html5-snippets.md).
 
-## Motion language (house tokens)
+## Motion
 
-Compose motion from a **closed set of tokens** so a multi-clip edit feels like one production, not eight unrelated effects. **Don't invent a new easing or duration per clip.** Full recipes (GSAP/CSS, choreography, brand kit) in [`references/motion.md`](../references/motion.md).
+Timing, easing and rhythm are yours to design. Built-in motion takes fixed options from the schema; `html5` takes any seekable animation. Detail and recipes in [`references/motion.md`](../references/motion.md).
 
-- **Durations (seconds):** `instant 0.2 · fast 0.33 · base 0.6 · slow 0.8 · slower 1.0 · hold 1.5`. Entrances default to **`base` (0.6)**; **exits are faster** (`fast`).
-- **One house ease, no overshoot:** html5 GSAP `power3.out` (in) / `power2.in` (out); CSS `cubic-bezier(0.16, 1, 0.3, 1)`. Never raw `linear` for tracked motion. A gentle `back.out(1.4)` is reserved for **one** hero element per scene — calm is the default.
-- **One stagger:** `0.13s` between siblings (GSAP `stagger: 0.13`; CSS `animation-delay` steps).
-- **Restraint:** translate 12–24 px (not 80), scale ≥ 0.92, one focal element per moment, let a reveal settle (`hold`) before it cuts.
-- **rich-text `animation`** (entrance-only — exits use the clip `transition.out`): set `duration` from the scale (e.g. `0.6`); `preset:"ascend"` + `direction:"up"` is the rise-and-fade workhorse; for a word cascade use `preset:"shift"` + `style:"word"` + `direction:"up"` (`style` works only on `typewriter`/`shift`; `direction` is required for `slideIn`/`ascend`/`shift`/`movingLetters`).
-- **Brand once:** put palette/font in top-level `merge[]` (`{{ink}}`, `{{accent}}`, `{{font}}`) and reference them in every clip — one edit re-skins the whole video. Accent used sparingly.
+- **Seconds, not frames:** convert frame-based specs with `output.fps`.
+- **Clip level, fixed options:** `transition` in/out (engine-fixed timing, `Slow`/`Fast` variants), `effect` (Ken Burns drift) and keyframe tweens on `scale`, `opacity`, `offset`, `rotate`, `skew`, `volume` and `speed` (see Keyframes above). Keyframe `interpolation` is `linear`, `bezier` or `constant`, and `easing` comes from a fixed list (`easeOutCubic`, `easeInOutBack`, …).
+- **Combining on an existing asset:** keyframes move the whole clip while a `rich-text` preset animates the text inside it, so animate each property one way per clip. Keyframe `scale` multiplies `fit`, so a large scale on a low-resolution source shows its pixels.
+- **rich-text `animation`** is entrance-only (exits use the clip `transition.out`) with engine-fixed easing. `style` works only on `typewriter`/`shift`; `direction` is required for `slideIn`/`ascend`/`shift`/`movingLetters`.
+- **`html5`** gives full control: any seekable GSAP, anime.js, Lottie or CSS animation, any easing, per-element timing.
+- **To music:** measure the track before timing anything to it, then write cuts and motion in bars. Method in [`references/beat-sync.md`](../references/beat-sync.md).
+- **Brand once:** palette and font as top-level `merge[]` fields (`{{ink}}`, `{{accent}}`, `{{font}}`) resolve inside `html5` `html`/`css`/`js` too, so one edit re-skins the whole video.
 
 ## Positioning & coordinates
 
@@ -208,7 +214,9 @@ Top-level `merge[]` (sibling of `timeline`/`output`, NOT a clip property) is a s
 
 **Checking merge results:** pass `?data=true&merged=true` on the status request to see the merged Edit JSON in the response — useful for debugging unresolved placeholders.
 
+<!-- surface:cli -->
 **Validate caveat:** `shotstack validate` checks `html5` JS syntax **before** merge resolution. A `{{TOKEN}}` inside a JS string literal (e.g. `color: "{{ACCENT}}"`) is valid JS and passes. A `{{TOKEN}}` in JS *code* position (not inside a string) may fail validation pre-merge but work at render time post-merge — keep merge fields inside string literals to avoid false positives.
+<!-- /surface -->
 
 ## Asset types
 
@@ -222,8 +230,8 @@ Use only the **current** asset types; the deprecated ones still parse but should
 | `image` | Static image — `jpg`, `png`, `webp`, `gif`, `bmp`, `tiff` — or AI-generated from a `prompt`. |
 | `audio` | Audio clip placed at a specific time on the timeline, or AI-generated speech or music from a `prompt`. |
 | `rich-text` | Styled text overlay with full typography control. **Use this instead of `text`/`html`/`title`.** |
-| `svg` | Vector graphics from raw SVG markup: `src` starts with `<svg`, never a URL or `data:` URI (the render fails). See `references/svg.md`. |
-| `html5` | Self-contained HTML/CSS/JS page rendered in an iframe (motion graphics, charts, animated overlays). Preloads gsap/d3/anime/lottie. See `references/html5.md`. **Never use the deprecated `html` asset.** |
+| `svg` | Vector graphics from raw SVG markup: `src` starts with `<svg`, never a URL or `data:` URI (the render fails). See **`svg` assets** below. |
+| `html5` | Self-contained HTML/CSS/JS page rendered in an iframe (motion graphics, charts, animated overlays). Preloads gsap with its plugins (SplitText, DrawSVG, MorphSVG, MotionPath, Flip and more), d3, anime and lottie. See `references/html5.md`. **Never use the deprecated `html` asset.** |
 | `rich-caption` | Word-level animated captions sourced from audio, video, or subtitle files. See `references/caption.md`. |
 | `luma` | Luma matte for masking effects. |
 
@@ -244,6 +252,29 @@ For background music, **use an `audio` asset on its own track** with `length: "e
 | `timeline.soundtrack` | `audio` asset on its own track with `length: "end"` |
 | `text-to-image`, `image-to-video`, `text-to-speech` | `image`, `video` or `audio` with `prompt` and `model` (below) |
 
+### `svg` assets
+
+`src` **is the SVG markup itself**, starting with `<svg`. Never a URL and never a data URI (`data:image/svg+xml;…`, base64 or URL-encoded): those fail to parse, so Studio shows an empty placeholder and the rendered video leaves the shape out. Write colours as plain `#hex`, not `%23`. `data:` URIs belong inside `html5` assets only.
+
+Every `src` must include `xmlns="http://www.w3.org/2000/svg"`, a `viewBox`, and `width` and `height` in pixels. Without them the renderer can't size or place the shape.
+
+```json
+{
+  "asset": {
+    "type": "svg",
+    "src": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 200 200\" width=\"200\" height=\"200\"><circle cx=\"100\" cy=\"100\" r=\"90\" fill=\"#142033\" stroke=\"#F2C14E\" stroke-width=\"6\"/></svg>"
+  },
+  "start": 0,
+  "length": 3,
+  "width": 200,
+  "height": 200
+}
+```
+
+- **Supported:** `<path>`, `<rect>`, `<circle>`, `<ellipse>`, `<line>`, `<polygon>`, `<polyline>`, `<g>`, with `fill`, `fill-opacity`, `stroke`, `stroke-width`, `stroke-opacity` and `transform`.
+- **Unsupported:** `<text>` (use `rich-text`), `<image>` (use `image`), `<animate>`/`<animateTransform>` (animate the clip instead; only the first frame renders), `<foreignObject>`, most `<filter>`s, and external `<use>` references.
+- A plain coloured box behind text doesn't need SVG: `rich-text` has `background.color`, `opacity` and `borderRadius`. Use SVG for shapes rich-text can't draw, such as badges, rings, dividers and speech bubbles.
+
 ### AI-generated assets
 
 Set `prompt` and `model` on an `image`, `video` or `audio` asset and it is generated at render time. `options` configures the model, and a `src` you set is only a preview placeholder that the generated file replaces. For speech, the prompt is the words to speak.
@@ -252,10 +283,17 @@ Set `prompt` and `model` on an `image`, `video` or `audio` asset and it is gener
 { "asset": { "type": "video", "prompt": "Slow dolly across a rain-soaked neon street at night", "model": "seedance-2.0-text-to-video", "options": { "resolution": "720p" } }, "start": 0, "length": 5 }
 ```
 
-The models endpoint (`GET /models`) lists each model, whether the account can use it, and the JSON Schema for its `options`. `POST /generate/quote` takes the same body as `POST /generate` and returns its cost in credits without charging. Options outside that schema are rejected. To animate a still, use an image-to-video model and put the image URL in `options.startSrc` (`inputSrc` on the original image-to-video models).
+The models endpoint (`GET /models`) lists each model, whether the account can use it, and the JSON Schema for its `options`. `POST /generate/quote` takes the same body as `POST /generate` and returns its cost in credits without charging.
+
+Options outside that schema are rejected. To animate a still, use an image-to-video model and put the image URL in `options.startSrc` (`inputSrc` on the original image-to-video models).
 
 Generation is billed per asset **even on the stage endpoint**, which is otherwise free. Renders containing AI assets take longer, because the render waits for each generation.
 
+**Music.** Use the user's own track when they have one. Otherwise offer a track generated for this video, written for its mood, tempo and length. The stock library is a dozen tracks shared by every video that falls back on it, so use it only when no music model is available or the user declines.
+<!-- surface:cli -->
+`shotstack models` shows whether this key can generate music; quote the track with `--quote` before generating it, as for any asset. Without a key, use a library track and tell the user once that after `shotstack login` you can generate music made for this video.
+<!-- /surface -->
+
 ## The design ladder — escalate from rich-text to html5
 
 One overlay is a `rich-text` job. **Several videos "in different styles" is not** — making them all `rich-text` ships one look eight times. Match the asset to the ambition:
@@ -264,9 +302,9 @@ One overlay is a `rich-text` job. **Several videos "in different styles" is not*
 |---|---|---|
 | 1 — type & layout | `rich-text` | Titles, lower-thirds, kickers, captions, price/CTA pills. Fast and reliable; the right default for static styled text. |
 | 2 — shapes | `svg` | Colour panels, rules, badges, frames, geometric accents behind or around type. |
-| 3 — motion graphics | `html5` | Kinetic type, value reveals, shine sweeps, animated gradients, film grain, masked reveals, data-driven overlays — anything that should *move* beyond a `transition` or a Ken-Burns `effect`. gsap / anime / d3 / lottie are preloaded. See [`references/html5.md`](../references/html5.md) and the copy-paste clips in [`references/html5-snippets.md`](../references/html5-snippets.md). |
+| 3 — motion graphics | `html5` | Kinetic type, value reveals, shine sweeps, animated gradients, film grain, masked reveals, data-driven overlays — anything that should *move* beyond a `transition` or a Ken-Burns `effect`. gsap and its plugins, anime, d3 and lottie are preloaded. See [`references/html5.md`](../references/html5.md), the effects palette in [`references/html5-effects.md`](../references/html5-effects.md), and the copy-paste clips in [`references/html5-snippets.md`](../references/html5-snippets.md). |
 
-**When the brief asks for a *range*, deliberately spread across the ladder.** A strong set: a couple of clean `rich-text` studio cuts, one or two `svg` colour-block promos, and several `html5` pieces carrying the real motion (kinetic headline, value reveal, shine-swept CTA, grain-graded teaser). Reserve the elaborate `html5` treatments for the hero / hype cuts where motion sells the product. If every clip in a "variety" brief is `rich-text`, you have not delivered variety.
+**When the brief asks for a *range*, deliberately spread across the ladder.** A strong set: a couple of clean `rich-text` studio cuts, one or two `svg` colour-block promos, and several `html5` pieces carrying the real motion (kinetic headline, value reveal, shine-swept CTA, grain-graded teaser). If every clip in a "variety" brief is `rich-text`, you have not delivered variety.
 
 ## Fonts
 
@@ -293,7 +331,11 @@ Paste the **url** into `timeline.fonts[].src`, paste the **family** into `asset.
 | Anton (display) | `1Ptgg87LROyAm0K08i4gS7lu` | `https://fonts.gstatic.com/s/anton/v27/1Ptgg87LROyAm0K08i4gS7lu.ttf` |
 | Playfair Display (serif, variable) | `nuFiD-vYSZviVYUb_rj3ij__anPXPTvSgWE_-xU` | `https://fonts.gstatic.com/s/playfairdisplay/v40/nuFiD-vYSZviVYUb_rj3ij__anPXPTvSgWE_-xU.ttf` |
 
-Variable fonts cover the full weight range (100–900) from a single URL — set `font.weight` on the clip. For a font not listed: copy an entry **verbatim** from the Studio SDK catalogue (~400 fonts) at <https://github.com/shotstack/shotstack-studio-sdk/blob/main/src/core/fonts/google-fonts.ts>, or open the font on <https://fonts.google.com>, view the CSS, and copy the exact `.ttf` URL from the `@font-face` `src`. Never hand-edit the version or hash segments.
+Variable fonts cover the full weight range (100–900) from a single URL — set `font.weight` on the clip. Poppins, Bebas Neue and Anton aren't variable: the listed URL is the 400 weight.
+
+For a font not listed: copy an entry **verbatim** from the Studio SDK catalogue (~400 fonts) at <https://github.com/shotstack/shotstack-studio-sdk/blob/main/src/core/fonts/google-fonts.ts>, or open the font on <https://fonts.google.com>, view the CSS, and copy the exact `.ttf` URL from the `@font-face` `src`. Never hand-edit the version or hash segments.
+
+Never invent or hand-edit a font URL. If a font isn't listed and you can't copy its exact entry, use the closest listed font.
 
 ### Usage example
 
@@ -319,7 +361,10 @@ Variable fonts cover the full weight range (100–900) from a single URL — set
 }
 ```
 
-Use the `family` column from the table above: the URL's filename without `.ttf`, matched ignoring case. The family name stored inside the font file also matches, but it isn't always the name on Google Fonts (Space Grotesk's file calls itself `Space Grotesk Light`), so the filename is the safe choice. A `font.family` that matches nothing renders in Roboto with no error. The exception is a lone entry in `timeline.fonts[]`, which is used whatever `font.family` says, so a wrong name only shows once a second font is added. `shotstack validate` warns on any `font.family` that isn't a built-in or a loaded filename.
+Use the `family` column from the table above: the URL's filename without `.ttf`, matched ignoring case. The family name stored inside the font file also matches, but it isn't always the name on Google Fonts (Space Grotesk's file calls itself `Space Grotesk Light`), so the filename is the safe choice. A `font.family` that matches nothing renders in Roboto with no error. The exception is a lone entry in `timeline.fonts[]`, which is used whatever `font.family` says, so a wrong name only shows once a second font is added.
+<!-- surface:cli -->
+`shotstack validate` warns on any `font.family` that isn't a built-in or a loaded filename.
+<!-- /surface -->
 
 ## Top 5 mistakes
 
@@ -331,4 +376,7 @@ Use the `family` column from the table above: the URL's filename without `.ttf`,
 
 ## Per-topic deep dives
 
-For details beyond this core guide (rich-caption presets, SVG constraints, full font URL list, troubleshooting), see the `references/` directory in the Shotstack CLI repo or fetch the topic-specific docs from `https://shotstack.io/docs/guide/llms-full.txt`.
+For details beyond this core guide (rich-caption presets, SVG constraints, full font URL list, troubleshooting), fetch the topic-specific docs from `https://shotstack.io/docs/guide/llms-full.txt`.
+<!-- surface:cli -->
+The `references/` directory in the Shotstack CLI repo has the same detail.
+<!-- /surface -->