trace-avatar-render 0.1.4 → 0.1.6
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/CHANGELOG.md +14 -1
- package/README.md +14 -1
- package/dist/{chunk-2ASNE3WF.js → chunk-ZNHFXKD3.js} +79 -11
- package/dist/chunk-ZNHFXKD3.js.map +1 -0
- package/dist/cli.js +13 -4
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +186 -162
- package/dist/index.js +5 -1
- package/package.json +1 -1
- package/dist/chunk-2ASNE3WF.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,19 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
## 0.1.
|
|
3
|
+
## 0.1.6 (unreleased)
|
|
4
|
+
|
|
5
|
+
- **Cards between scenes** (`Capture.cards` in `finish()`; `withCards`, `cardFrames`): a card shown for its time at a
|
|
6
|
+
moment of the capture, in the title and end cards' look, fading in and out. A narrated card lasts as long as its
|
|
7
|
+
line. For pitch videos: the problem, the result and the ask on cards, between the app's scenes.
|
|
8
|
+
|
|
9
|
+
## 0.1.5 (12 Nov 2026)
|
|
10
|
+
|
|
11
|
+
- **Several shapes from one capture**: `--out file.mp4@1:1` (`OutSpec.canvas` in `render()` and `finish()`) gives
|
|
12
|
+
that output its own canvas, over `--canvas`. A 16:9, a 1:1 and a 4:5 cut of one run need one capture, not three
|
|
13
|
+
(found making SpeedyMessaging's campaign videos: three captures took three times as long, and a Do it for me run
|
|
14
|
+
sent three test messages).
|
|
15
|
+
|
|
16
|
+
## 0.1.4 (11 Nov 2026)
|
|
4
17
|
|
|
5
18
|
- `--canvas 9:16|4:5|1:1|16:9|WxH` (`canvas` in `render()` and `finish()`): the app is composed onto a picture of that
|
|
6
19
|
shape, between safe margins on the background, for Reels, Stories and feeds.
|
package/README.md
CHANGED
|
@@ -31,7 +31,7 @@ Because the guide is known before it plays, the render can do what a screen reco
|
|
|
31
31
|
| | |
|
|
32
32
|
|---|---|
|
|
33
33
|
| `--url <url>` | the page the guide starts on (required) |
|
|
34
|
-
| `--out <file>` | `.gif` or `.mp4`, repeatable (required) |
|
|
34
|
+
| `--out <file>` | `.gif` or `.mp4`, repeatable (required); `<file>@<shape>` gives that output its own canvas (see `--canvas`), so one capture makes several shapes |
|
|
35
35
|
| `--mode overlay\|perform` | Show me (default) or Do it for me |
|
|
36
36
|
| `--allow-perform` | needed for Do it for me: it clicks and types in the app for real. **Use a sandbox account.** |
|
|
37
37
|
| `--width <px>` | output width (GIF default 800, MP4 the capture's) |
|
|
@@ -90,6 +90,13 @@ trace-avatar-render invoice.trace.json --url http://localhost:3000/app --brand a
|
|
|
90
90
|
--viewport 390x844 --scale 2 --captions burn --out invoice-reel.mp4
|
|
91
91
|
```
|
|
92
92
|
|
|
93
|
+
One capture, several feed shapes:
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
trace-avatar-render invoice.trace.json --url http://localhost:3000/app --brand acme.json --scale 2 \
|
|
97
|
+
--out invoice-wide.mp4@16:9 --out invoice-square.mp4@1:1 --out invoice-feed.mp4@4:5
|
|
98
|
+
```
|
|
99
|
+
|
|
93
100
|
Exit codes: 0 rendered, 1 the render failed, 2 wrong usage.
|
|
94
101
|
|
|
95
102
|
**MP4 needs ffmpeg** on the PATH (or `FFMPEG=/path/to/ffmpeg`): `brew install ffmpeg`, `apt install ffmpeg`. GIF
|
|
@@ -169,6 +176,12 @@ r.offsetMs + outputAt(r.segments, t); // where a moment of the capture lan
|
|
|
169
176
|
|
|
170
177
|
`render` rejects with a `RenderError` (with `.screenshot`) when the guide stalls, errors, or can't start.
|
|
171
178
|
|
|
179
|
+
`finish(capture, outputs, options)` makes the video from a capture you made yourself (a Playwright script of your
|
|
180
|
+
own, say). A capture can carry **cards between scenes**: `capture.cards = [{ t, ms, card: { title, url, logo, color },
|
|
181
|
+
step }]` shows each card for `ms` at source time `t`, fading in from the app and out to it. With narration, a card
|
|
182
|
+
whose `step` has a line lasts as long as that line (and 0.7 s more); put that step's event at `t + 1`, so the line
|
|
183
|
+
is spoken over the card. A card says its own words, so it gets no burned-in caption.
|
|
184
|
+
|
|
172
185
|
## How it works
|
|
173
186
|
|
|
174
187
|
```
|
|
@@ -908,6 +908,42 @@ function withHolds(segs, holds) {
|
|
|
908
908
|
}
|
|
909
909
|
return out;
|
|
910
910
|
}
|
|
911
|
+
function withCards(segs, cards) {
|
|
912
|
+
const marks = cards.map((c, card) => ({ src: c.t, ms: Math.round(c.ms), card })).filter((m) => m.ms > 0).sort((a, b) => a.src - b.src);
|
|
913
|
+
if (!marks.length) return segs.map((s) => ({ ...s }));
|
|
914
|
+
const out = [];
|
|
915
|
+
let k = 0;
|
|
916
|
+
for (const s of segs) {
|
|
917
|
+
if (s.hold) {
|
|
918
|
+
out.push({ ...s });
|
|
919
|
+
continue;
|
|
920
|
+
}
|
|
921
|
+
let from = s.from;
|
|
922
|
+
while (k < marks.length && marks[k].src <= s.to) {
|
|
923
|
+
const m = marks[k++];
|
|
924
|
+
const at = Math.max(from, m.src);
|
|
925
|
+
if (at > from) out.push({ from, to: at });
|
|
926
|
+
out.push({ from: at, to: at, hold: m.ms, card: m.card });
|
|
927
|
+
from = at;
|
|
928
|
+
}
|
|
929
|
+
if (s.to > from) out.push({ from, to: s.to });
|
|
930
|
+
}
|
|
931
|
+
const last = segs.length ? segs[segs.length - 1].to : 0;
|
|
932
|
+
for (; k < marks.length; k += 1) out.push({ from: last, to: last, hold: marks[k].ms, card: marks[k].card });
|
|
933
|
+
return out;
|
|
934
|
+
}
|
|
935
|
+
function cardFrames(segs, fps) {
|
|
936
|
+
const n = Math.max(1, Math.round(durationOf(segs) / 1e3 * fps));
|
|
937
|
+
return Array.from({ length: n }, (_, k) => {
|
|
938
|
+
let left = k * 1e3 / fps;
|
|
939
|
+
for (const s of segs) {
|
|
940
|
+
const len = lenOf(s);
|
|
941
|
+
if (left < len) return s.card;
|
|
942
|
+
left -= len;
|
|
943
|
+
}
|
|
944
|
+
return void 0;
|
|
945
|
+
});
|
|
946
|
+
}
|
|
911
947
|
function frameTimes(segs, fps) {
|
|
912
948
|
const n = Math.max(1, Math.round(durationOf(segs) / 1e3 * fps));
|
|
913
949
|
return Array.from({ length: n }, (_, k) => sourceAt(segs, k * 1e3 / fps));
|
|
@@ -1380,6 +1416,8 @@ var LEAD_MS = 500;
|
|
|
1380
1416
|
var TITLE_MS = 1500;
|
|
1381
1417
|
var END_MS = 2e3;
|
|
1382
1418
|
var FADE_MS = 300;
|
|
1419
|
+
var CARD_PAD_MS = 700;
|
|
1420
|
+
var CLOSING_CARD_MS = 1500;
|
|
1383
1421
|
function cardOf(v, fallback) {
|
|
1384
1422
|
if (!v) return void 0;
|
|
1385
1423
|
if (v === true) return fallback;
|
|
@@ -1485,12 +1523,19 @@ repair: ${n ? `${n} fix${n > 1 ? "es" : ""} (${ok} verified${outcome.passed ? ",
|
|
|
1485
1523
|
var base = (file) => file.replace(/\.[^./]+$/, "");
|
|
1486
1524
|
async function finish(cap, outs, o = {}) {
|
|
1487
1525
|
const frames = cap.frames.slice().sort((a, b) => a.t - b.t);
|
|
1488
|
-
const
|
|
1489
|
-
const
|
|
1490
|
-
const
|
|
1491
|
-
const
|
|
1526
|
+
const capCards = cap.cards ?? [];
|
|
1527
|
+
const firstCard = capCards.length ? Math.min(...capCards.map((c) => c.t)) : Infinity;
|
|
1528
|
+
const lastCard = capCards.length ? Math.max(...capCards.map((c) => c.t)) : -Infinity;
|
|
1529
|
+
const start = Math.min(Math.max(frames[0].t, cap.playAt - LEAD_MS), firstCard);
|
|
1530
|
+
const end = lastCard >= cap.stopAt - CLOSING_CARD_MS ? Math.min(cap.stopAt, lastCard + 1) : cap.stopAt;
|
|
1492
1531
|
const warnings = [];
|
|
1493
1532
|
const narr = o.narration?.lines.size ? o.narration : null;
|
|
1533
|
+
const cards = capCards.map((c) => {
|
|
1534
|
+
const line = c.step !== void 0 ? narr?.lines.get(c.step) : void 0;
|
|
1535
|
+
return { ...c, ms: Math.max(c.ms, line ? msOf(line.audio) + CARD_PAD_MS : 0) };
|
|
1536
|
+
});
|
|
1537
|
+
const cut = withCards(editList(cap.events, { start, end, maxWaitMs: o.cuts?.maxWaitMs ?? DEFAULT_MAX_WAIT_MS }), cards);
|
|
1538
|
+
const stamps = frames.map((f) => f.t);
|
|
1494
1539
|
let said = null;
|
|
1495
1540
|
let held = cut;
|
|
1496
1541
|
if (narr) {
|
|
@@ -1528,6 +1573,7 @@ async function finish(cap, outs, o = {}) {
|
|
|
1528
1573
|
const scale = cap.viewport ? srcW / cap.viewport.w : 1;
|
|
1529
1574
|
const frameStyle = o.frame ?? "none";
|
|
1530
1575
|
const canvas = o.canvas !== void 0 ? canvasOf(o.canvas) : void 0;
|
|
1576
|
+
const canvases = outs.map((x) => x.canvas !== void 0 ? canvasOf(x.canvas) : canvas);
|
|
1531
1577
|
const mark = o.watermark !== void 0 ? watermarkOf(o.watermark) : void 0;
|
|
1532
1578
|
const background = o.background ?? DEFAULT_BACKGROUND;
|
|
1533
1579
|
const burn = o.captions === "burn" || o.captions === "both";
|
|
@@ -1537,7 +1583,8 @@ async function finish(cap, outs, o = {}) {
|
|
|
1537
1583
|
segs: sg,
|
|
1538
1584
|
contentMs: ms,
|
|
1539
1585
|
cam: o.camera ? cameraPath(actionsOf(cap.events, sg, scale), { width: srcW, height: srcH, ...typeof o.camera === "object" && o.camera.zoom ? { zoom: o.camera.zoom } : {} }) : null,
|
|
1540
|
-
|
|
1586
|
+
// A card says its own words: no caption over it or after it.
|
|
1587
|
+
cues: o.captions ? stepCues(cap.events.map((e) => e.stepType === "card" ? { ...e, say: void 0 } : e), sg, ms) : []
|
|
1541
1588
|
};
|
|
1542
1589
|
};
|
|
1543
1590
|
const main = variant(segs);
|
|
@@ -1547,7 +1594,7 @@ async function finish(cap, outs, o = {}) {
|
|
|
1547
1594
|
const titleMs = o.cards?.title ? TITLE_MS : 0;
|
|
1548
1595
|
const endMs = o.cards?.end ? END_MS : 0;
|
|
1549
1596
|
const full = { x: 0, y: 0, w: srcW, h: srcH };
|
|
1550
|
-
const needLayers = frameStyle !== "none" ||
|
|
1597
|
+
const needLayers = frameStyle !== "none" || canvases.some(Boolean) || !!mark || burn && (cues.length > 0 || plain.cues.length > 0) || !!o.cards?.title || !!o.cards?.end || cards.length > 0;
|
|
1551
1598
|
const browser = needLayers ? await chromium2.launch() : null;
|
|
1552
1599
|
let layers = null;
|
|
1553
1600
|
const outputs = [];
|
|
@@ -1560,19 +1607,32 @@ async function finish(cap, outs, o = {}) {
|
|
|
1560
1607
|
for (const [n, out] of outs.entries()) {
|
|
1561
1608
|
mkdirSync(dirname3(out.file) || ".", { recursive: true });
|
|
1562
1609
|
const fps = out.fps ?? (out.format === "gif" ? 12 : 30);
|
|
1563
|
-
const layout = layoutOf(srcW, srcH, out.width ?? (out.format === "gif" ? 800 : void 0), frameStyle,
|
|
1610
|
+
const layout = layoutOf(srcW, srcH, out.width ?? (out.format === "gif" ? 800 : void 0), frameStyle, canvases[n]);
|
|
1564
1611
|
const v = out.format === "gif" ? plain : main;
|
|
1565
1612
|
const { cam, segs: segs2, contentMs: contentMs2 } = v;
|
|
1566
1613
|
const cues2 = v.cues;
|
|
1567
1614
|
const times = frameTimes(segs2, fps);
|
|
1568
1615
|
const picks = pickFrames(stamps, times);
|
|
1569
|
-
const art = await artFor(layers, layout, { frameStyle, background, cues: burn ? cues2 : [], urls: [...new Set(cap.events.map((e) => e.url).filter(Boolean))], titles: cap.titles ?? {}, cards: o.cards, mark });
|
|
1616
|
+
const art = await artFor(layers, layout, { frameStyle, background, cues: burn ? cues2 : [], urls: [...new Set(cap.events.map((e) => e.url).filter(Boolean))], titles: cap.titles ?? {}, cards: o.cards, mid: cards.map((c) => c.card), mark });
|
|
1617
|
+
const cardAt = cards.length ? cardFrames(segs2, fps) : [];
|
|
1570
1618
|
const nTitle = Math.round(titleMs * fps / 1e3);
|
|
1571
1619
|
const nEnd = Math.round(endMs * fps / 1e3);
|
|
1572
1620
|
const nFade = Math.max(1, Math.round(FADE_MS * fps / 1e3));
|
|
1573
1621
|
const total = nTitle + picks.length + nEnd;
|
|
1574
1622
|
let last = null;
|
|
1575
1623
|
const content = (k) => {
|
|
1624
|
+
const c = cardAt[k];
|
|
1625
|
+
if (c === void 0) return app(k);
|
|
1626
|
+
const img = art.mid[c];
|
|
1627
|
+
let s = k;
|
|
1628
|
+
while (s > 0 && cardAt[s - 1] === c) s -= 1;
|
|
1629
|
+
let e = k;
|
|
1630
|
+
while (e + 1 < cardAt.length && cardAt[e + 1] === c) e += 1;
|
|
1631
|
+
if (k - s < nFade && s > 0 && cardAt[s - 1] === void 0) return crossfade(app(s - 1), img, (k - s + 1) / nFade);
|
|
1632
|
+
if (e - k < nFade && e + 1 < picks.length && cardAt[e + 1] === void 0) return crossfade(img, app(e + 1), 1 - (e - k) / nFade);
|
|
1633
|
+
return img;
|
|
1634
|
+
};
|
|
1635
|
+
const app = (k) => {
|
|
1576
1636
|
const t = k * 1e3 / fps;
|
|
1577
1637
|
const i = picks[k];
|
|
1578
1638
|
const rect = cam ? cam(t) : full;
|
|
@@ -1699,7 +1759,7 @@ async function finish(cap, outs, o = {}) {
|
|
|
1699
1759
|
durationMs: Math.round(contentMs + titleMs + endMs),
|
|
1700
1760
|
offsetMs: titleMs,
|
|
1701
1761
|
rawMs: Math.round(end - start),
|
|
1702
|
-
segments: segs.map((s) => ({ from: rel(s.from), to: rel(s.to), ...s.hold ? { hold: s.hold } : {} })),
|
|
1762
|
+
segments: segs.map((s) => ({ from: rel(s.from), to: rel(s.to), ...s.hold ? { hold: s.hold } : {}, ...s.card !== void 0 ? { card: s.card } : {} })),
|
|
1703
1763
|
events: cap.events.map((e) => ({ ...e, t: rel(e.t) })),
|
|
1704
1764
|
outputs,
|
|
1705
1765
|
...poster ? { poster } : {},
|
|
@@ -1727,7 +1787,7 @@ function badgeAt(W, H, w, h, at = "bottom-right") {
|
|
|
1727
1787
|
return { x: at.endsWith("left") ? m : W - w - m, y: at.startsWith("top") ? m : H - h - m };
|
|
1728
1788
|
}
|
|
1729
1789
|
async function artFor(layers, layout, o) {
|
|
1730
|
-
const art = { base: null, captions: /* @__PURE__ */ new Map() };
|
|
1790
|
+
const art = { base: null, captions: /* @__PURE__ */ new Map(), mid: [] };
|
|
1731
1791
|
if (!layers) return art;
|
|
1732
1792
|
if (o.frameStyle !== "none" || layout.canvas) {
|
|
1733
1793
|
art.base = /* @__PURE__ */ new Map();
|
|
@@ -1740,6 +1800,7 @@ async function artFor(layers, layout, o) {
|
|
|
1740
1800
|
}
|
|
1741
1801
|
if (o.cards?.title) art.title = await layers.card(layout, { ...o.cards.title, background: o.background });
|
|
1742
1802
|
if (o.cards?.end) art.end = await layers.card(layout, { ...o.cards.end, background: o.background });
|
|
1803
|
+
for (const c of o.mid ?? []) art.mid.push(await layers.card(layout, { ...c, background: o.background }));
|
|
1743
1804
|
if (o.mark) {
|
|
1744
1805
|
const img = await layers.badge(o.mark.text, { fontPx: Math.max(11, Math.round(Math.min(layout.width, layout.height) * 0.024)), ...o.mark.logo ? { logo: o.mark.logo } : {} });
|
|
1745
1806
|
const { x, y } = badgeAt(layout.width, layout.height, img.width, img.height, o.mark.at);
|
|
@@ -1752,6 +1813,11 @@ async function artFor(layers, layout, o) {
|
|
|
1752
1813
|
art[k] = d;
|
|
1753
1814
|
}
|
|
1754
1815
|
}
|
|
1816
|
+
art.mid = art.mid.map((c) => {
|
|
1817
|
+
const d = copy(c);
|
|
1818
|
+
overlay(d, img, x, y, art.badge.alpha);
|
|
1819
|
+
return d;
|
|
1820
|
+
});
|
|
1755
1821
|
}
|
|
1756
1822
|
return art;
|
|
1757
1823
|
}
|
|
@@ -1921,6 +1987,8 @@ export {
|
|
|
1921
1987
|
sourceAt,
|
|
1922
1988
|
outputAt,
|
|
1923
1989
|
withHolds,
|
|
1990
|
+
withCards,
|
|
1991
|
+
cardFrames,
|
|
1924
1992
|
frameTimes,
|
|
1925
1993
|
pickFrames,
|
|
1926
1994
|
actionsOf,
|
|
@@ -1960,4 +2028,4 @@ export {
|
|
|
1960
2028
|
cached,
|
|
1961
2029
|
voiceOf
|
|
1962
2030
|
};
|
|
1963
|
-
//# sourceMappingURL=chunk-
|
|
2031
|
+
//# sourceMappingURL=chunk-ZNHFXKD3.js.map
|