vizmatic 0.7.1 → 0.7.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/PROMPT.md +25 -1
  2. package/ROADMAP.md +1 -1
  3. package/dist/{chunk-DTD35LPT.js → chunk-F6QI6QJY.js} +60 -2
  4. package/dist/chunk-QVYHYC7T.js +88 -0
  5. package/dist/cli.js +10 -9
  6. package/dist/index.cjs +70 -3
  7. package/dist/index.d.cts +4 -2
  8. package/dist/index.d.ts +4 -2
  9. package/dist/index.js +14 -3
  10. package/dist/scene-cli.js +1 -1
  11. package/dist/stage-browser/browser.d.ts +144 -5
  12. package/dist/stage-browser/stage.js +5 -5
  13. package/dist/stage-export.cjs +67 -1
  14. package/dist/stage-export.d.cts +5 -1
  15. package/dist/stage-export.d.ts +5 -1
  16. package/dist/stage-export.js +11 -1
  17. package/dist/stage.cjs +286 -22
  18. package/dist/stage.d.cts +146 -7
  19. package/dist/stage.d.ts +146 -7
  20. package/dist/stage.js +268 -9
  21. package/dist/{svg-import-Djj2q7Pc.d.cts → svg-import-5_oTbEJR.d.cts} +2 -2
  22. package/dist/{svg-import-Djj2q7Pc.d.ts → svg-import-5_oTbEJR.d.ts} +2 -2
  23. package/dist/{video-CcHW1qhV.d.cts → video-BSwNJZkn.d.cts} +25 -1
  24. package/dist/{video-CcHW1qhV.d.ts → video-BSwNJZkn.d.ts} +25 -1
  25. package/examples/_teaching/categorical-tail-loss.ts +3 -3
  26. package/examples/_teaching/teaching-byte-diff.ts +3 -3
  27. package/examples/_teaching/teaching-routed-transfer.ts +3 -3
  28. package/examples/_teaching/teaching-token-history.ts +2 -2
  29. package/examples/_teaching/teaching-weighted-vector.ts +3 -3
  30. package/examples/films/attention.ts +5 -4
  31. package/examples/films/fourier-epicycles.ts +5 -2
  32. package/examples/films/pythagoras.ts +2 -2
  33. package/examples/films/taylor-series.ts +3 -2
  34. package/package.json +1 -1
  35. package/dist/chunk-3LQLKLGH.js +0 -79
package/PROMPT.md CHANGED
@@ -11,6 +11,8 @@ Vizmatic requires Node.js 20 or newer. MP4 and WebM also need FFmpeg.
11
11
  npm install vizmatic
12
12
  ```
13
13
 
14
+ For pnpm 11, allow esbuild's install script with `allowBuilds: { esbuild: true }` in the root `pnpm-workspace.yaml`.
15
+
14
16
  ## Films
15
17
 
16
18
  Start from a template, or write the function yourself. Templates are `explainer`, `equation`, `architecture`, `chart`, and `deck`.
@@ -51,6 +53,8 @@ Rules of the engine:
51
53
  - `s.play(...)` writes animation and moves time forward. `s.wait(seconds)` holds. `s.at(time, build)` authors at another time.
52
54
  - A `dynamic(() => ...)` drawing rebuilds on every frame. Read `value.value` inside it to drive anything.
53
55
  - `morph(a, b)` leaves `b` on stage and `a` hidden. Later code refers to `b`.
56
+ - A `duration` on `s.play` stretches every animation to fill it, and a `duration` inside one of those animations has no effect. For different lengths, leave it off `s.play`, set it on each animation, and use `delay` for an offset: `s.play(fadeOut(oldText, { duration: 0.15 }), delay(fadeIn(newText, { duration: 0.25 }), 0.1))`. Inside a `s.play` that has a duration, use `seq(fadeOut(oldText), fadeIn(newText))`.
57
+ - Use `font: 'text-serif'` for sentences, labels, and numbers. Use `font: 'serif'` only for short titles at a large size.
54
58
  - Colors are look tokens such as `'blue'`, `'yellow'`, `'ink'`, and `'dim'`, so a film renders in every look.
55
59
  - Run `vizmatic objects` and `vizmatic looks` to see what the installed version offers.
56
60
 
@@ -64,7 +68,11 @@ npx vizmatic film intro.ts --frame 3,6.5,12 --width 1280 --out stills
64
68
  npx vizmatic film intro.ts --out dist/films --look midnight,paper --quality high
65
69
  ```
66
70
 
67
- `vizmatic check` samples the moments where the film comes to rest. It reports `film.off_canvas`, `film.text_overlap`, `film.text_crossed`, and `film.missing_glyph`, each with times, a `box` in canvas pixels, and a `stage` center in authoring coordinates. Fix every error, then open the stills and look at them. `vizmatic preview intro.ts` opens a live player with a timeline for a person to review.
71
+ `vizmatic check` samples the moments where the film comes to rest. It reports `film.off_canvas`, `film.text_overlap`, `film.text_crossed`, and `film.missing_glyph`, each with times, a `box` in canvas pixels, and a `stage` center in authoring coordinates. Fix every error, then open the stills and look at them. `vizmatic preview intro.ts` opens a live player with a timeline for a person to review. The [Studio](https://bvolpato.github.io/vizmatic/studio.html) is a visual film editor in the browser for a person who wants to edit by hand.
72
+
73
+ The check does not look at motion, so a crossfade where two sentences overlap and a blank gap between two pictures both pass it. Add `--motion` to inspect every frame: `npx vizmatic check intro.ts --motion --json`. It reports a problem that appears only in motion as a warning, and 0.2 seconds or more with nothing visible as `film.blank`. Judge each warning, because the check cannot tell a collision from one picture that replaces another. `--content-top <px>` sets where the content starts, so that a heading that stays up does not hide a blank.
74
+
75
+ `--audio narration.wav` adds sound, padded or trimmed to the film's length, so hold until the voice ends. `s.caption(text, seconds)` writes a WebVTT file beside the video and draws nothing into the picture. MP4 output is H.264 with settings that QuickTime can play. To join a clip to a film without encoding it again, encode the clip with `filmEncoderSettings(quality)` from `vizmatic/stage/export`.
68
76
 
69
77
  Motion guidance:
70
78
 
@@ -73,6 +81,20 @@ Motion guidance:
73
81
  - Give color a meaning and keep it. A quantity keeps its color from its first appearance to its last.
74
82
  - Use chapters. They mark the player's timeline and are the steps of a presentation.
75
83
 
84
+ ### Lessons
85
+
86
+ When a film must teach a topic, [lessons.md](https://bvolpato.github.io/vizmatic/references/lessons.md) has the full method. In short:
87
+
88
+ - Put accuracy first, then completeness, clarity, and brevity. There is no target length, so keep every passage that teaches.
89
+ - Finish the script before the film. Teach the problem, then the mechanism, then the limits. Keep one worked example throughout.
90
+ - Compute every number in the film, and check it with `assert`. The voice and the screen use the same values and the same rounding.
91
+ - Keep each title true for as long as it is visible. List every text block with its visible times, and read each one against the picture and the voice.
92
+ - Change pictures cleanly. Old text drops under about 25% opacity before new text reaches it, and something stays on screen through the change.
93
+ - A person must watch the film at full speed with sound before it is published. You cannot do this, so say that it has not happened.
94
+ - Use the computed states from `vizmatic` where they fit: `weightedVectorState`, `categoricalSampling`, `planTeachingRoutedTransfer`, `byteDifferenceState`, and `tokenHistoryState`. Show the limits of each. `check` and `film` accept this import, and `preview` refuses it because it runs in the browser. A project with a checked canvas host can use the same constructions through `createTeachingCanvas(painter)`.
95
+
96
+ Read a finished film before you write a similar one. `examples/films/` in the package holds them with full source, and the [Films](https://bvolpato.github.io/vizmatic/films.html) page plays them.
97
+
76
98
  ## Figures
77
99
 
78
100
  Create `frame.tsx`. `Scene` title and subtitle are optional.
@@ -134,3 +156,5 @@ After creating a visual, report:
134
156
  - which looks or themes rendered
135
157
  - whether `vizmatic check` passed
136
158
  - any overflow or layout fixes made
159
+ - for a film, which stills you opened, and whether you scanned the motion
160
+ - anything you could not verify, including that nobody has watched the film with sound
package/ROADMAP.md CHANGED
@@ -15,7 +15,7 @@ This page states what Vizmatic can do now and what comes next. Vizmatic aims to
15
15
  - `fromSvg` and `fromComponent`, which turn any SVG or TSX figure into shapes that films can animate.
16
16
  - Export to MP4 and WebM with BT.709 color, GIF with a shared palette, PNG, and SVG. Frames rasterize on worker threads with a memory limit, with optional motion blur.
17
17
  - `vizmatic new`, `preview`, `check`, `film`, `looks`, and `objects`. Preview reloads on save and keeps the playhead.
18
- - `vizmatic check` for films: off-canvas marks, overlapping text, and strokes through text, with times and bounding boxes as JSON.
18
+ - `vizmatic check` for films: off-canvas marks, overlapping text, and strokes through text, with times and bounding boxes as JSON. `--motion` inspects every frame for collisions and blank gaps between pictures.
19
19
  - The Studio, which builds and exports a film in the browser.
20
20
 
21
21
  ### Figures
@@ -1470,10 +1470,39 @@ function sampleAnimationFrames(animation, options = {}) {
1470
1470
  // src/video.ts
1471
1471
  import { spawn } from "child_process";
1472
1472
  import { randomUUID } from "crypto";
1473
- import { chmod, mkdir as mkdir2, open, rename, rm, stat } from "fs/promises";
1473
+ import { chmod, mkdir as mkdir2, open, rename, rm, stat, writeFile as writeFile2 } from "fs/promises";
1474
1474
  import { basename, dirname as dirname2, join as join2, resolve } from "path";
1475
1475
  import { Resvg as Resvg2 } from "@resvg/resvg-js";
1476
1476
  import parseCssColor from "parse-css-color";
1477
+ function chapterMetadata(title, chapters, duration) {
1478
+ const escape = (value) => value.replace(/[\\=;#]/g, (c) => `\\${c}`).replace(/\r?\n/g, " ");
1479
+ const marks = chapters.filter((chapter) => Number.isFinite(chapter.time) && chapter.time < duration).map((chapter) => ({ title: chapter.title, time: Math.max(0, chapter.time) })).sort((a, b) => a.time - b.time);
1480
+ if (marks.length > 0) marks[0].time = 0;
1481
+ let out = ";FFMETADATA1\n";
1482
+ if (title) out += `title=${escape(title)}
1483
+ `;
1484
+ marks.forEach((mark, index) => {
1485
+ const end = index + 1 < marks.length ? marks[index + 1].time : duration;
1486
+ out += `[CHAPTER]
1487
+ TIMEBASE=1/1000
1488
+ START=${Math.round(mark.time * 1e3)}
1489
+ END=${Math.round(end * 1e3)}
1490
+ title=${escape(mark.title)}
1491
+ `;
1492
+ });
1493
+ return out;
1494
+ }
1495
+ function captionsToSrt(captions, duration) {
1496
+ const stamp = (seconds) => {
1497
+ const ms = Math.round(seconds * 1e3);
1498
+ const pad = (value, size = 2) => String(value).padStart(size, "0");
1499
+ return `${pad(Math.floor(ms / 36e5))}:${pad(Math.floor(ms / 6e4) % 60)}:${pad(Math.floor(ms / 1e3) % 60)},${pad(ms % 1e3, 3)}`;
1500
+ };
1501
+ return captions.filter((cue) => cue.t1 > 0 && cue.t0 < duration && cue.t1 > cue.t0 && cue.text.trim().length > 0).sort((a, b) => a.t0 - b.t0).map((cue, index) => `${index + 1}
1502
+ ${stamp(Math.max(0, cue.t0))} --> ${stamp(Math.min(duration, cue.t1))}
1503
+ ${cue.text.trim()}
1504
+ `).join("\n");
1505
+ }
1477
1506
  var MAX_STDERR_CHARS = 8192;
1478
1507
  var COLOR_FILTER = "scale=in_range=pc:out_range=tv:out_color_matrix=bt709:flags=lanczos+accurate_rnd+full_chroma_int,format=yuv420p,setparams=range=tv:color_primaries=bt709:color_trc=bt709:colorspace=bt709";
1479
1508
  var COLOR_TAGS = ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709", "-color_range", "tv"];
@@ -1687,12 +1716,37 @@ async function renderRgbaVideo(renderFrame, options) {
1687
1716
  "-i",
1688
1717
  "pipe:0"
1689
1718
  ];
1719
+ let inputs = 1;
1720
+ let audioInput = -1;
1690
1721
  if (options.audioPath) {
1691
1722
  if (options.audioOffset) args.push("-ss", String(options.audioOffset));
1692
1723
  args.push("-i", resolve(options.audioPath));
1724
+ audioInput = inputs++;
1725
+ }
1726
+ const sidecars = [];
1727
+ let metadataInput = -1, captionInput = -1;
1728
+ if (codec === "h264") {
1729
+ const chapters = options.chapters ?? [];
1730
+ if (options.title || chapters.length > 0) {
1731
+ const path = join2(outputDirectory, `.${basename(outputPath)}.${randomUUID()}.tmp.ffmeta`);
1732
+ await writeFile2(path, chapterMetadata(options.title, chapters, schedule.duration), { mode: 384 });
1733
+ sidecars.push(path);
1734
+ args.push("-f", "ffmetadata", "-i", path);
1735
+ metadataInput = inputs++;
1736
+ }
1737
+ const srt = captionsToSrt(options.captions ?? [], schedule.duration);
1738
+ if (srt) {
1739
+ const path = join2(outputDirectory, `.${basename(outputPath)}.${randomUUID()}.tmp.srt`);
1740
+ await writeFile2(path, srt, { mode: 384 });
1741
+ sidecars.push(path);
1742
+ args.push("-f", "srt", "-i", path);
1743
+ captionInput = inputs++;
1744
+ }
1693
1745
  }
1694
1746
  args.push("-map", "0:v:0");
1695
- if (options.audioPath) args.push("-map", "1:a:0", "-af", `asetpts=PTS-STARTPTS,apad,atrim=duration=${seconds}`);
1747
+ if (options.audioPath) args.push("-map", `${audioInput}:a:0`, "-af", `asetpts=PTS-STARTPTS,apad,atrim=duration=${seconds}`);
1748
+ if (captionInput >= 0) args.push("-map", `${captionInput}:0`, "-c:s", "mov_text", "-metadata:s:s:0", "language=eng");
1749
+ if (metadataInput >= 0) args.push("-map_metadata", String(metadataInput), "-map_chapters", String(metadataInput));
1696
1750
  args.push("-frames:v", String(schedule.count), "-t", seconds, "-vf", COLOR_FILTER);
1697
1751
  if (codec === "vp9") {
1698
1752
  args.push("-c:v", "libvpx-vp9", "-crf", String(crf), "-b:v", "0", "-deadline", "good", "-cpu-used", "2", "-row-mt", "1", "-threads:v", String(threads));
@@ -1716,6 +1770,7 @@ async function renderRgbaVideo(renderFrame, options) {
1716
1770
  child = spawn(ffmpegPath, args, { stdio: ["pipe", "ignore", "pipe"] });
1717
1771
  } catch (error) {
1718
1772
  await rm(tempPath, { force: true });
1773
+ for (const path of sidecars) await rm(path, { force: true });
1719
1774
  throw error;
1720
1775
  }
1721
1776
  child.stderr?.on("data", (chunk) => {
@@ -1817,6 +1872,7 @@ async function renderRgbaVideo(renderFrame, options) {
1817
1872
  throw error;
1818
1873
  } finally {
1819
1874
  await rm(tempPath, { force: true });
1875
+ for (const path of sidecars) await rm(path, { force: true });
1820
1876
  }
1821
1877
  }
1822
1878
 
@@ -3644,6 +3700,8 @@ export {
3644
3700
  sampleAnimationFrame,
3645
3701
  analyzeAnimationCadence,
3646
3702
  sampleAnimationFrames,
3703
+ chapterMetadata,
3704
+ captionsToSrt,
3647
3705
  videoFrameSchedule,
3648
3706
  renderAnimationVideo,
3649
3707
  renderRgbaVideo