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 CHANGED
@@ -1,6 +1,19 @@
1
1
  # Changelog
2
2
 
3
- ## 0.1.4 (unreleased)
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 start = Math.max(frames[0].t, cap.playAt - LEAD_MS);
1489
- const end = cap.stopAt;
1490
- const cut = editList(cap.events, { start, end, maxWaitMs: o.cuts?.maxWaitMs ?? DEFAULT_MAX_WAIT_MS });
1491
- const stamps = frames.map((f) => f.t);
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
- cues: o.captions ? stepCues(cap.events, sg, ms) : []
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" || !!canvas || !!mark || burn && (cues.length > 0 || plain.cues.length > 0) || !!o.cards?.title || !!o.cards?.end;
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, canvas);
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-2ASNE3WF.js.map
2031
+ //# sourceMappingURL=chunk-ZNHFXKD3.js.map