volito 0.1.0 → 0.3.0

package/README.md

@@ -1,12 +1,32 @@
-# Volito
-
-**Brand-aware, voice-synced motion graphics as code — for developers and AI agents.**
+<p align="center">
+  <a href="https://volito.dev"><img src=".github/assets/banner.jpg" alt="Volito: motion graphics, from one sentence. Motion graphics as code for developers and AI agents, by MONARC PRO." width="100%"></a>
+</p>
+
+<h1 align="center">Volito</h1>
+
+<p align="center"><strong>Brand-aware, voice-synced motion graphics as code — for developers and AI agents.</strong></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/volito"><img src="https://img.shields.io/npm/v/volito?color=2433e8&label=npm" alt="npm version"></a>
+  <a href="https://github.com/monarcpro/volito/actions/workflows/ci.yml"><img src="https://github.com/monarcpro/volito/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/engine-MIT-dfff4f?labelColor=15140f" alt="Engine licence: MIT"></a>
+  <a href="https://volito.dev/docs"><img src="https://img.shields.io/badge/docs-volito.dev-ff6a3d?labelColor=15140f" alt="Docs on volito.dev"></a>
+</p>
+
+<p align="center">
+  <a href="https://volito.dev">Website</a> ·
+  <a href="https://volito.dev/docs">Docs</a> ·
+  <a href="https://volito.dev/docs/packs">Packs</a> ·
+  <a href="https://volito.dev/docs/agents">For agents</a> ·
+  <a href="https://www.npmjs.com/package/volito">npm</a> ·
+  <a href="CHANGELOG.md">Changelog</a>
+</p>
 
 By [MONARC STUDIOS](https://monarcpro.app), the team behind MONARC PRO. Volito is the motion graphics engine
 inside the [MONARC PRO](https://monarcpro.app) video editor, opened up; the name is Latin for “to flutter”.
 Every graphic is a small program — `function frame(t, $)` returns the SVG of one frame — so it is
 readable, diffable, seekable to any frame, and something an AI agent can write and fix. It ships with
-96 ready-made graphics in ten packs (3D, maps, transitions and kinetic type among them), 36 brand styles,
+107 ready-made graphics in twelve packs (3D, maps, transitions, kinetic type, interactive UI and filter effects among them), 36 brand styles,
 sixteen animated patterns, a CLI, a Node API, a browser player and an MCP server, and renders to ProRes 4444 or HEVC with alpha, WebM, MP4, GIF, PNG frames or SVG.
 
 - **One design, every brand.** Items draw with colour roles and faces, not fixed colours: pass one of 36
@@ -16,10 +36,18 @@ sixteen animated patterns, a CLI, a Node API, a browser player and an MCP server
 - **On the voice.** Give a transcript and text lands on the words that say it.
 - **Drops onto footage.** Overlays render with real alpha for Premiere, Resolve, Final Cut, After
   Effects and CapCut.
+- **Sounds like it moves.** `--sound` gives any render a sound track Volito synthesises itself — a pop for
+  every spring, a whoosh for every move across the frame, ticks for letters, a hit for a slam, a bed in a
+  key — and a program can design its own cues beside its frames.
 - **Agent-native.** An MCP server gives Claude Code, Cursor and other agents tools to find, preview (as an
   image they can see), check and render graphics — or to write their own.
 - **Many scripts.** Latin, Latin Extended, Vietnamese, Cyrillic, Greek and Devanagari (Hindi), shaped properly.
 
+<p align="center">
+  <img src=".github/assets/intro.gif" alt="A 10-second Volito intro: kinetic type, the logo dropping in, an extruded 3D wordmark and an end card" width="420"><br>
+  <sub>This intro is a Volito program: kinetic type, a 3D wordmark and an end card, rendered in Node.</sub>
+</p>
+
 ```bash
 npx volito render lower-third \
   --prop name="Priya Sharma" --prop role="Product designer" \
@@ -39,7 +67,9 @@ stills, contact sheets and PNG frames do not. WebM needs an ffmpeg built with li
 
 ## The packs
 
-96 graphics in ten packs. Every one takes any brand style and any aspect, and every part of it takes any move.
+<img src=".github/assets/packs.jpg" alt="96 graphics in 10 packs: a render from each of Essentials, Broadcast, Social, Data, 3D, Transitions, Annotate, Type, Backdrops and Promo" width="100%">
+
+107 graphics in twelve packs. Every one takes any brand style and any aspect, and every part of it takes any move.
 
 | Pack | Items |
 | --- | --- |
@@ -53,6 +83,8 @@ stills, contact sheets and PNG frames do not. WebM needs an ffmpeg built with li
 | **Type** (10) | Kinetic type: `typewriter` · `word-swap` (a word that keeps changing) · `split-flap` · `marquee` (tilted scrolling bands) · `echo` · `liquid-fill` · `decode` · `word-by-word` · `key-phrase` (marker on *marked* words) · `stack` (editorial) |
 | **Backdrops** (9) | Moving grounds: `pattern` (any of the sixteen) · `aurora` · `tiles` (Bauhaus field) · `retro-grid` (synthwave) · `blobs` (lava goo) · `gradient` · `starfield` · `bokeh` · `topo` |
 | **Promo** (8) | `sale-badge` (starburst) · `price-card` (counts down, strike, click) · `coupon` (copy the code) · `offer-countdown` (D:H:M:S) · `features` (checklist) · `cta` (button and cursor) · `launch` · `ribbon` (crossing tapes) |
+| **UI** (5) | Interactive states (see *Interactive states*): `button` (idle, hover, press, loading, done) · `toggle` · `like` (rolling count) · `loader` (success or failure) · `bell` (badge, read) |
+| **Effects** (6) | SVG filters, no GPU: `grain` (film grain, re-rolled every film frame) · `light-leak` · `glass` (frosted card over drifting colour) · `chromatic` (channels split and snap) · `warp` (liquid ripple settling) · `neon` (flickers on) |
 
 `volito info <item>` lists every prop. To see them all live, serve this package's folder and
 open `examples/gallery.html`.
@@ -103,6 +135,50 @@ Maps use Natural Earth's countries (177, packed into 30 KB): `worldMap($, { cent
 flat (Equal Earth), `worldGlobe(S, …)` puts them on a 3D globe, and `worldFind("UK")` finds one by name,
 short name or ISO number. `volito api` documents both.
 
+## Sound design
+
+Every render can carry sound, and Volito makes it the way it makes pictures: from code, from nothing. No
+sample library, no files to find. `--sound` reads the graphic's own motion — every part's move leaves a
+mark — and gives each its sound: a spring pops, a move across the frame whooshes (louder the further it
+travels), letters tick, a typewriter types, a slam hits, a glitch zaps, a burst sparkles. `--bed Dm` lays
+a pad under it in a key, and it steps back under every hit on its own.
+
+```bash
+volito render logo-sting --prop wordmark=VOLITO --sound --bed Dm --format mp4 --out sting.mp4
+volito sound lower-third --prop name="Priya Sharma" --out priya.wav     # the track alone, with its cue list
+```
+
+A program designs its own sound beside its frames — `function sound($)` runs once with the same `$`
+(`$.dur`, `$.beat`, `$.at(word)`, `$.data`), so cues land on the same beats the picture uses:
+
+```js
+function sound($) {
+  return {
+    cues: [
+      { at: 0.2, kind: "riser", dur: 1.1 },
+      { at: $.beat("in", 1.3), kind: "hit", level: 1.1 },
+      { at: 1.5, kind: "shimmer", dur: 1.2, pan: 0.3 },
+      { at: -0.6, kind: "ding", note: "A5", level: 0.6 },   // negative counts from the end
+    ],
+    bed: { key: "D", mode: "minor", from: 0.8, to: -0.4, level: 0.5 },
+    auto: false,   // true adds the motion's own cues on top
+  };
+}
+```
+
+| Kind | |
+| --- | --- |
+| `whoosh` `swell` `riser` `fall` | air past, soft air rising, a climb into a moment, the fall after it |
+| `hit` `stamp` `sub` `pop` | an impact, a heavy slam, a low drop, a bubble pop |
+| `tick` `click` `type` `scratch` | one letter or step, a UI click, keys for a while, pencil on paper |
+| `shimmer` `ding` `zap` | sparkle, a bell (`note: "A5"`), a glitch |
+| `tone` `chord` | a note, the bed's chord — for a sting that resolves |
+
+Each cue takes `at`, `dur`, `level` (0–2), `pitch` (semitones), `pan` (-1…1) and `seed`. The track is
+stereo 48 kHz, limited, with a room; `--sound-out track.wav` writes it alone for an editor's timeline
+beside a ProRes overlay. MP4 and HEVC carry AAC, ProRes carries PCM, WebM carries Opus; PNG and GIF carry
+none. `volito api` prints the whole sound reference.
+
 ## CLI
 
 ```bash
@@ -117,6 +193,49 @@ volito render banner --prop headline="Doors open at 9" --format webm --out banne
 volito check ./my-graphic.js                  # run it at every aspect, report problems
 ```
 
+### Graphic specs
+
+Any set of options can be saved as a spec: one JSON file for one graphic that every command takes in place
+of an item. Keep it in your repo, review it, hand it to an agent; options on the command line win over it.
+
+```bash
+volito spec lower-third --prop name="Priya Sharma" --style ember --aspect 9:16 --out priya.volito.json
+volito validate priya.volito.json            # its props, parts, files and aspect against the item
+volito render priya.volito.json --prop role="Founder"
+volito schema                                # the JSON Schema (also at https://volito.dev/schema/graphic.v1.json)
+```
+
+```json
+{
+  "$schema": "https://volito.dev/schema/graphic.v1.json",
+  "volito": 1,
+  "item": "essentials/lower-third",
+  "props": { "name": "Priya Sharma", "role": "Product designer" },
+  "style": "./DESIGN.md",
+  "aspect": "9:16",
+  "motion": { "name": { "in": "typewriter" } },
+  "mood": "elegant",
+  "seed": 4,
+  "sound": { "bed": "Dm" },
+  "render": { "format": "mov", "out": "renders/priya.mov" }
+}
+```
+
+Paths inside a spec (a DESIGN.md, a `program`, a transcript, image props) are relative to the spec file.
+`program` points at your own `frame(t, $)` file, or `code` holds it inline. `volito bundle priya.volito.json`
+packs the spec and those files into one `priya.volito` that every command takes, anywhere.
+
+### Review before you render
+
+```bash
+volito review lower-third --prop name="Priya Sharma" --aspect 9:16
+```
+
+The check at each aspect, then what the frames show: when the graphic settles, how long it holds still and
+when it leaves (with a warning when the entrance is slow or the hold too short for its words), how much of
+an overlay sits under Reels', Shorts' and TikTok's interface at 9:16, and a contact sheet per aspect in
+`volito-review/<item>/` with a `review.md`.
+
 | Option | |
 | --- | --- |
 | `--prop name=value` | a prop (repeat). Lists: `"a; b; c"`. Chart rows: `"Label: 42; Other: 17"` |
@@ -130,6 +249,7 @@ volito check ./my-graphic.js                  # run it at every aspect, report p
 | `--motion part.setting=value` | how a part moves (repeat; `*` for every part) — see *Motion without limits* |
 | `--mood m` · `--seed n` · `--speed x` | a choreography, a new take per seed, faster or slower |
 | `--beat in=0.4 --beat out=-0.6` | move the entrance and exit (negative counts from the end) |
+| `--sound` · `--bed Dm` · `--sound-level x` · `--sound-out file.wav` | a sound track synthesised by Volito (see *Sound design*), a pad in a key, its level, the track alone |
 | `--packs <dir>` | more packs (also `VOLITO_PACKS`) |
 | `--format mov\|webm\|mp4\|hevc\|gif\|png` | for `render`; `png`/`svg` for `still` |
 
@@ -144,10 +264,14 @@ volito check ./my-graphic.js                  # run it at every aspect, report p
 
 ## AI agents (MCP)
 
+<img src=".github/assets/agents.jpg" alt="An agent adds the Volito MCP server, then calls motion_list, motion_preview, motion_check and motion_render to make a lower third in 16:9 and 9:16" width="100%">
+
 ```bash
-claude mcp add volito -- npx -y volito mcp
+npx volito init          # adds the server for Claude Code, Cursor and VS Code, and the skill
+npx volito doctor        # what is ready: Node, FFmpeg formats, fonts, each agent's setup
 ```
 
+Or by hand: `claude mcp add volito -- npx -y volito mcp`, `codex mcp add volito -- npx -y volito mcp`, and for
 Cursor, Windsurf and other MCP clients:
 
 ```json
@@ -162,11 +286,14 @@ Cursor, Windsurf and other MCP clients:
 | `motion_preview` | a contact sheet as an image — the agent sees how it moves and whether text fits |
 | `motion_still` | one frame as an image |
 | `motion_check` | errors and warnings at every aspect |
-| `motion_render` | render to a file and return its path |
+| `motion_render` | render to a file and return its path (`sound: true` muxes a synthesised track, `bed: "Dm"` a pad) |
+| `motion_sound` | the graphic's sound alone as a .wav, with its cue list |
 | `motion_moves` | every move, ease, idle, hit and mood the `motion` settings take |
+| `motion_validate` | check a Graphic spec (inline or a file) against its item before rendering |
+| `motion_review` | timing, 9:16 platform safe zones and a contact sheet per aspect, measured before rendering |
 | `motion_api` | the program API and the motion kit, for writing new graphics |
 
-Every tool takes an `item` or your own `code`, plus `motion`, `mood`, `seed` and `speed`. A ready-made agent skill is in `skill/SKILL.md` — copy it
+Every tool takes an `item`, your own `code` or a `spec` file, plus `motion`, `mood`, `seed` and `speed`. A ready-made agent skill is in `skills/volito/SKILL.md` — `npx volito init` installs it for Claude Code, `npx skills add monarcpro/volito` for other agents, or copy it
 to `~/.claude/skills/volito/` for Claude Code.
 
 ## Node API
@@ -203,6 +330,64 @@ The player runs each program in a sandboxed Web Worker and draws through the sam
 renderer, so what plays on the page is what renders. Fonts load from `base` (the package's own
 `fonts/` on jsDelivr by default); serve the package's `fonts/` and `dist/registry.json` to stay offline.
 
+### `<volito-player>`
+
+The same player as an HTML element, with controls and aspect tabs. One script, no build step:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/volito/dist/player.js"></script>
+
+<volito-player item="essentials/lower-third"
+  props='{"name":"Ada Lovelace","role":"First programmer"}'
+  brand="cobalt" aspects="all" controls autoplay loop></volito-player>
+```
+
+Or `import "volito/player"` in a bundled app. Each tab lays the item out again for that aspect, not a
+crop. It loads when it nears the screen, pauses off screen and in a hidden tab, and does not autoplay
+for readers who prefer reduced motion.
+
+| Attribute | What it does |
+| --- | --- |
+| `item` | `pack/id` or an id (or set the `program` property to your own `frame(t, $)` code) |
+| `props` | the item's props as JSON |
+| `brand` | a built-in style; the `brand` property also takes DESIGN.md text. `accent`, `accent2`, `ink`, `paper`, `mode` override colours |
+| `aspect` · `aspects` | the aspect shown (`16:9`, `9:16`, `1:1`, `4:5`, `WIDTHxHEIGHT`) · the tabs to offer (`all` or a list) |
+| `duration` `speed` `mood` `seed` `motion` `beats` | as on the CLI; `motion` takes `part.setting=value` separated by `;` |
+| `controls` `autoplay` `loop` | play/pause, a scrubber and the time; start when shown; play again at the end |
+| `playback-rate` · `range-start` `range-end` | play faster or slower · play only `[start, end)` seconds |
+| `poster` · `posters` | an image until the first frame · per-aspect images as JSON |
+| `ground` | behind a transparent graphic: `footage` (default), `checker`, `none` or a colour |
+| `background` | a colour drawn into the frame itself |
+| `base` · `loading` · `resolution` | where `fonts/` and `dist/registry.json` live · `eager` to load at once · the canvas's longest side (1920) |
+
+Properties and methods: `play()`, `pause()`, `seek(t)`, `load()`, `currentTime`, `duration`, `paused`,
+`ended`, `ready`, `playbackRate`, `props`, `brand`, `aspect`, `options` (anything else a build takes:
+`words`, `media`, `beats`), `program`, `warnings` and `player` (the `MotionPlayer` underneath). Events,
+none of which bubble: `ready`, `play`, `pause`, `ended`, `timeupdate` (about ten a second),
+`durationchange`, `aspectchange`, `warnings` and `error`. Style it with CSS custom properties
+(`--volito-accent`, `--volito-stage`, `--volito-max-height`, …) or `::part()`; Space, ←/→ (a frame,
+Shift for a second), Home and End work when it has focus. `examples/player.html` shows each of these.
+
+
+#### Interactive states
+
+A graphic can be a live UI element: its timeline cut into named states that page events and your code
+switch between. Every item in the `ui` pack declares its own, so this works with no setup:
+
+```html
+<volito-player item="ui/button" aspect="1000x500" ground="none" props='{"label":"Get started"}'></volito-player>
+<script type="module">
+  const button = document.querySelector("volito-player");
+  button.addEventListener("statechange", (e) => console.log(e.detail.to)); // enter → idle → hover → press → loading
+  await fetch("/api/signup", { method: "POST" });
+  button.state = "done";                                                  // lands on the check
+</script>
+```
+
+Any graphic can have states: `states='{"idle":{"from":"idle","to":"hover","play":"loop"},…}'` (times are seconds or
+beat names; `play` is `once`, `loop` or `hold`; `next` hands a finished `once` on), and
+`on="pointerenter(idle): hover; pointerleave(hover): idle; click: press"` maps page events to them.
+
 ## Brand styles
 
 36 built in. MONARC PRO's: `ember`, `cream`, `mono`, `neon`, `pop`, `studio`, and the explainer art
@@ -338,6 +523,12 @@ faces (`src/fonts-extra.ts`), styles (`src/styles-extra.ts`) and patterns (`src/
 - The engine: [MIT](LICENSE).
 - The MONARC packs: the [MONARC Packs License](PACKS-LICENSE.md). Use them in any video, personal or
   commercial, with no attribution required. Don't resell them as templates.
-- The fonts: each family's SIL Open Font License, in `fonts/licenses/`.
+- The fonts: each family's SIL Open Font License, in `fonts/licenses/` of the installed package
+  (`pnpm build` writes that folder in a checkout).
+
+## Contributing
+
+Issues and pull requests are welcome: [CONTRIBUTING.md](CONTRIBUTING.md) covers the setup, the tests and
+how items and packs are written. Report security problems privately, as [SECURITY.md](SECURITY.md) says.
 
 Made by [MONARC STUDIOS](https://monarcpro.app), the team behind [MONARC PRO](https://monarcpro.app).

package/dist/browser.d.ts

@@ -215,6 +215,33 @@ interface MotionConfig {
 /** "name.in=pop", "in=pop" (every part), "*.ease=bouncy", or a JSON object → overrides. */
 declare function parseMotionArgs(args: string[]): MotionInput;
 
+/**
+ * Interactive states for <volito-player>: a graphic's timeline cut into named stretches — idle, hover,
+ * press, loading, success — that page events and code switch between. Each state plays its stretch once
+ * (then stays on its last frame, or moves on to `next`), loops it, or holds one frame. Times are seconds or
+ * the item's beat names, so an item that names its beats ("hover", "press") declares its states in
+ * item.json and works with no setup:
+ *
+ *   "states": { "idle": { "from": "idle", "to": "hover", "play": "loop" },
+ *               "hover": { "from": "hover", "to": "press", "play": "once" },
+ *               "press": { "from": "press", "to": "loading", "play": "once", "next": "loading" } },
+ *   "on": "pointerenter(idle): hover; pointerleave(hover): idle; click: press"
+ *
+ * Pure functions: parsed and resolved here, played by the element.
+ */
+declare const STATE_PLAYS: readonly ["once", "loop", "hold"];
+type StatePlay = (typeof STATE_PLAYS)[number];
+interface StateDef {
+    /** Where the stretch starts: seconds, a beat name, "start" or "end". Default: the start. */
+    from?: number | string;
+    /** Where it ends: seconds, a beat name, "start" or "end". Default: the end. */
+    to?: number | string;
+    /** once: play it and stay on its last frame (or go to `next`); loop: repeat it; hold: show `from` and stay. */
+    play?: StatePlay;
+    /** The state to go to when a `once` stretch finishes. */
+    next?: string;
+}
+
 /**
  * Packs and items: the library format. A pack is a folder of items that share a look and a
  * helper file; an item is one motion graphic — `item.json` (what it is, the props it takes,
@@ -292,6 +319,13 @@ interface ItemManifest {
     libs?: LibraryName[];
     /** Faces whose glyphs 3D text is built from: brand roles ("display") or specs ("Anton:400"). Default: display. */
     faces3d?: string[];
+    /**
+     * Interactive states for <volito-player>: named stretches of the timeline (beat names or seconds), each
+     * played once, looped or held — { "idle": { "from": "idle", "to": "hover", "play": "loop" }, … }.
+     */
+    states?: Record<string, StateDef>;
+    /** The page events that switch states by default: "pointerenter(idle): hover; click: press". */
+    on?: string;
 }
 interface PackManifest {
     format: number;
@@ -488,7 +522,14 @@ declare class MotionPlayer {
     private opts;
     private built;
     private worker;
-    private css;
+    private env;
+    /** Every face the package has (fonts/faces.json), and the files the worker has loaded. */
+    private all;
+    private loaded;
+    private readonly css;
+    private widening;
+    private gone;
+    private lastT;
     private raf;
     private started;
     private offset;
@@ -503,7 +544,15 @@ declare class MotionPlayer {
     /** The time shown now, seconds. */
     get time(): number;
     get program(): TitleProgram;
+    private get base();
     private load;
+    private startWorker;
+    /** The faces a frame draws with. */
+    private facesOf;
+    /** The @font-face rules for a set of faces, as data: URLs; one string per set, made once. */
+    private cssOf;
+    /** A frame drew with a face the worker lacks (so measured without it): restart it with that face, then redraw. */
+    private widen;
     private report;
     /** Change props, style, aspect or duration; the frame redraws. */
     update(opts: Partial<PlayerOptions>): Promise<void>;