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.
- package/PROMPT.md +25 -1
- package/ROADMAP.md +1 -1
- package/dist/{chunk-DTD35LPT.js → chunk-F6QI6QJY.js} +60 -2
- package/dist/chunk-QVYHYC7T.js +88 -0
- package/dist/cli.js +10 -9
- package/dist/index.cjs +70 -3
- package/dist/index.d.cts +4 -2
- package/dist/index.d.ts +4 -2
- package/dist/index.js +14 -3
- package/dist/scene-cli.js +1 -1
- package/dist/stage-browser/browser.d.ts +144 -5
- package/dist/stage-browser/stage.js +5 -5
- package/dist/stage-export.cjs +67 -1
- package/dist/stage-export.d.cts +5 -1
- package/dist/stage-export.d.ts +5 -1
- package/dist/stage-export.js +11 -1
- package/dist/stage.cjs +286 -22
- package/dist/stage.d.cts +146 -7
- package/dist/stage.d.ts +146 -7
- package/dist/stage.js +268 -9
- package/dist/{svg-import-Djj2q7Pc.d.cts → svg-import-5_oTbEJR.d.cts} +2 -2
- package/dist/{svg-import-Djj2q7Pc.d.ts → svg-import-5_oTbEJR.d.ts} +2 -2
- package/dist/{video-CcHW1qhV.d.cts → video-BSwNJZkn.d.cts} +25 -1
- package/dist/{video-CcHW1qhV.d.ts → video-BSwNJZkn.d.ts} +25 -1
- package/examples/_teaching/categorical-tail-loss.ts +3 -3
- package/examples/_teaching/teaching-byte-diff.ts +3 -3
- package/examples/_teaching/teaching-routed-transfer.ts +3 -3
- package/examples/_teaching/teaching-token-history.ts +2 -2
- package/examples/_teaching/teaching-weighted-vector.ts +3 -3
- package/examples/films/attention.ts +5 -4
- package/examples/films/fourier-epicycles.ts +5 -2
- package/examples/films/pythagoras.ts +2 -2
- package/examples/films/taylor-series.ts +3 -2
- package/package.json +1 -1
- 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",
|
|
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
|