export

Files (5)

• SKILL.md
• package.json
• export.mjs · scripts/
• lib.mjs · scripts/
• selfcheck.mjs · scripts/

SKILL.md (first lines)

# demo:export

Two exports from one composed demo. Film with demo:capture, cut with demo:compose, then:

```
compose out/<name>.mp4 ──┐
compose work/*.plan.json ┼─▶ export.mjs readme ──▶ demo.gif + demo.webp + poster.png
                         │                         picture.html, bundle.json
capture takes/<ch>/      │
  events.json (marks) ───┼─▶ export.mjs interactive ──▶ index.html (self-contained)
  cfr/%05d.png (2x) ─────┘                               steps.json
```

## Run

```bash
S="$SKILL_DIR"   # this skill's own directory
node "$S/scripts/export.mjs" readme      my.config.json   # compose/export/readme/
node "$S/scripts/export.mjs" interactive my.config.json   # compose/export/interactive/
npm --prefix "$S" run check                               # self-check, ~48 s
```

`my.config.json` is the same file demo:compose ran on: the export reads the segment order, the
plans in `<out>/work/`, the final `<out>/out/<name>.mp4` and the takes it points at. Run it after
`concat.sh`. On the compose skill's ferry example (`examples/ferry/`), after its quick start:

```bash
node "$S/scripts/export.mjs" readme ferry.config.json && node "$S/scripts/export.mjs" interactive ferry.config.json
```

Exit status is 2 for a bad command line (an unknown option, a value out of range), 1 for any
other failure; every warning and error names its fix. ffmpeg is the config's `ffmpeg`, as in
demo:compose, else `$FFMPEG`, else `/usr/bin/ffmpeg`, else the one on PATH.

## readme: GIF, WebP, poster, snippet

| option | default | |
|---|---|---|
| `--width` | 960 | output width in px (160 to 4096); height keeps the demo's aspect |
| `--fps` | 15 | frame rate of the GIF and WebP (1 to 50) |
| `--quality` | 90 | gifski quality to start from (1 to 100) |
| `--budget` | 5 | size limit in MB for each of the GIF, WebP and poster |
| `--from` / `--to` | picked | loop range in seconds of the final mp4; must hold a whole spotlight |
| `--out` | `<out>/export/readme` | |

**The loop.** One chapter, 8 to 12 s, starting and ending between spotlights so no spotlight is
cut: each runs from its fade-in to the end of its fade-out, and the loop must hold all of it or
none. It leads 1.2 s before its first spotlight (the camera move into it is in the loop) and
tails 0.6 s after its last. Compose crossfades close spotlights (one fades out as the next fades
in), so a stretch that would start or end inside such an overlap is skipped; a chapter made only
of crossfades longer than 12 s has no loop, and the export says to pass `--from`/`--to`.
Candidates score by spotlights held, closeness to 10 s, the seam (mean luma difference between
the first and last frame) and the motion at either end (luma change over the first and last
1/15 s), so the restart neither jumps nor stops mid zoom. A `--from`/`--to` that cuts a
spotlight, or holds none, is refused before anything is encoded.

**GIF** via gifski when installed (libimagequant, temporal dithering). Without it the export
warns once and uses ffmpeg `palettegen=stats_mode=diff` + `paletteuse=dither=bayer:bayer_scale=3`,
coarser on gradients. Install: `brew install gifski` or `cargo install gifski`. Over budget,
the export steps gifski's quality down by 10 to 60 (the ffmpeg palette has no quality knob), then
width down by 160 to 640 (or to `--width`, when that is smaller), then fails. The WebP and the
poster are held to the same budget. The snippet carries the size the GIF came out at, read from
its header, so a square demo gets a square `<img>`. On the
ferry loop the ffmpeg fallback is 5.024 MB at 960 px, just over budget, so it steps to 800 px:
3.868 MB, 18.0 s.

**WebP** via ffmpeg's `libwebp_anim` when the build has it, else `img2webp` (libwebp's own
tool, the `webp` package). Ubuntu's ffmpeg 6.1 has libwebp; Homebrew's ffmpeg 9 does not, so
there `img2webp` makes it (q75, method 4). With neither, the snippet offers the GIF only and
says so. Encoders merge unchanged frames into longer ones, so a 151-frame loop holds 111 WebP
and 140 GIF frames and still plays 10.07 to 10.12 s.

**Poster**: the loop's last spotlight, fully lit: after both the cut-out's fade-in and its
label's (compose starts the label at the mark minus 0.1 x pace and runs it 0.3 x pace), before
its fade-out.

**Snippet** (`picture.html`), paste into a README or page beside the three files:

```html
<picture>
  <source media="(prefers-reduced-motion: reduce)" srcset="poster.png">
  <source type="image/webp" srcset="demo.webp">
  <img src="demo.gif" width="960" height="540" alt="The live board: Next sailing runs late, Six car spaces left, Four sailings, status each">
</picture>
```

The alt text is the chapter title and the labels the loop shows.

Measured on the ferry example (30.2 s final, 1280x720), gifski 1.34, libwebp 1.6, defaults:

| | ffmpeg 6.1 (libwebp) | ffmpeg 9 + img2webp |
|---|---|---|
| loop picked | departures, 5.492 to 15.508 s | same |
| demo.gif | 3.369 MB (gifski q90, 960 px) | same |
| demo.webp | 1.152 MB | 1.212 MB |
| poster.png | 0.101 MB, at 13.358 s | 0.109 MB |
| wall time | 16.0 s | 13.9 to 16.5 s |

The loop holds 3 spotlights in 10.0 s (151 frames at 15 fps). Its ends move 0.89 (luma change,
of 255, summed over both ends); ends placed mid camera move on this demo measure 6 to 25, so
the motion weight (0.5) costs such a loop 3 to 12 points against 10 per spotlight held.

## interactive: click-through walkthrough

| option | default | |
|---|---|---|
| `--payoff` | last step | label (prefix) of the step that shows the payoff; linted |
| `--inline` | `auto` | `yes` embeds the images, `no` writes them beside the page; `auto` embeds up to 12 MB |
| `--out` | `<out>/export/interactive` | |

**Steps.** One per mark in demo order (every mark has a rect and a label), plus each click or
type cue with a target (demo:capture records the clicked or typed-into element's rect and the
camera box on each). A type beat is filmed as a click into the field then the type cue; the two
make one step at the click's frame and rect (the field before it widened or hid). Cue steps are
labelled from the target's accessible name and role as demo:capture recorded them: "Open Fares"
for a link, "Click Save" otherwise, "Type in Search" for a field; takes filmed before names were
recorded read "Click here" and "Type here". Cues that point at nothing are not steps, each case said in a
warning: no `rect` at all (the take predates demo:capture recording targets: re-film it),
`rect: null` (the target had no box when filmed: display:none or zero size), or a rect wholly

From stevengonsalvez/ainb-toolkit, MIT.

More from stevengonsalvez/ainb-toolkit