storyshot 0.1.0 → 0.3.1

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/src/check.mjs CHANGED
@@ -4,16 +4,17 @@ import YAML from 'yaml';
4
4
  import { loadConfig } from './config.mjs';
5
5
  import { gitIgnored } from './auth.mjs';
6
6
 
7
- const TOP = ['name', 'url', 'out', 'purpose', 'viewport', 'output', 'theme', 'music', 'voice', 'sfx', 'storageState', 'colorScheme',
7
+ const TOP = ['name', 'url', 'out', 'purpose', 'viewport', 'output', 'theme', 'music', 'voice', 'sfx', 'storageState', 'ignoreHTTPSErrors', 'intro', 'frame', 'pace', 'follow', 'colorScheme',
8
8
  'scrollOffset', 'captionPosition', 'highlight', 'stepNumbers', 'subtitles', 'chapters', 'clips', 'maxWait', 'setup', 'steps', 'end_card'];
9
- const STEP = ['caption', 'say', 'sayAt', 'duration', 'zoom', 'actions', 'hidden', 'sfx', 'highlight', 'captionPosition'];
9
+ const STEP = ['caption', 'say', 'sayAt', 'duration', 'zoom', 'actions', 'hidden', 'sfx', 'highlight', 'captionPosition', 'card', 'follow', 'doc'];
10
10
  const ZOOM = ['target', 'scale', 'start', 'end', 'ramp', 'offset'];
11
- const END = ['logo', 'title', 'subtitle', 'cta', 'duration', 'say'];
11
+ const END = ['logo', 'title', 'subtitle', 'cta', 'duration', 'say', 'kicker', 'bullets', 'image', 'think'];
12
12
  const TARGET = ['role', 'name', 'text', 'label', 'placeholder', 'alt', 'testId', 'css', 'exact', 'last', 'nth'];
13
- const OPTS = ['ms', 'offset', 'timeout', 'highlight'];
13
+ const OPTS = ['ms', 'offset', 'timeout', 'highlight', 'color', 'box'];
14
14
  const ACTIONS = {
15
15
  pause: 'number', wait: 'number', move: 'target', hover: 'target', click: 'target', dismiss: 'target', waitFor: 'target',
16
16
  waitForUrl: 'string', networkIdle: 'any', goto: 'string', scrollTo: 'target', scroll: 'any', type: 'type', drag: 'drag', press: 'any',
17
+ mark: 'mark', unmark: 'any', note: 'note', select: 'select',
17
18
  };
18
19
 
19
20
  const dist = (a, b) => {
@@ -68,8 +69,22 @@ export function check(file, { draft = false } = {}) {
68
69
  if (s.hidden && (s.caption || s.say)) warnings.push(`${where}: hidden steps are cut from the video, so caption/say are ignored`);
69
70
  if (!Array.isArray(s.actions ?? [])) errors.push(`${where}: actions must be a list`);
70
71
  for (const [j, a] of (s.actions ?? []).entries()) checkAction(a, `${where} action ${j + 1}`);
72
+ if (s.card) unknown(s.card, END, `${where} card`);
73
+ // tutorials: one thing per step, so the viewer can follow (and the narration can explain it)
74
+ const purpose = raw.purpose ?? 'pitch';
75
+ if ((purpose === 'tutorial' || purpose === 'course') && !s.hidden) {
76
+ const doing = (s.actions ?? []).filter((a) => a && ['click', 'type', 'drag', 'press', 'goto', 'select'].includes(Object.keys(a)[0]) && !(Object.keys(a)[0] === 'press' && /^(Enter|Tab)$/.test(String(Object.values(a)[0]))));
77
+ if (doing.length > 2) warnings.push(`${where}: does ${doing.length} things (${doing.map((a) => Object.keys(a)[0]).join(', ')}) in one step — in a ${purpose}, split it so each action gets its own explanation and the viewer can keep up`);
78
+ if (doing.length && !s.say) warnings.push(`${where}: does something but has no say: line — in a ${purpose}, tell the viewer what and why`);
79
+ const kinds = (s.actions ?? []).map((a) => a && Object.keys(a)[0]);
80
+ if (s.say && kinds.some((k) => k === 'scroll' || k === 'scrollTo') && !kinds.some((k) => ['mark', 'note', 'click', 'type', 'select', 'move', 'hover'].includes(k)) && !s.zoom) {
81
+ warnings.push(`${where}: scrolls and talks but points at nothing — on a dense page the viewer can't tell what you mean; \`mark\` or \`note\` the row or value the narration is about (the camera then zooms to it)`);
82
+ }
83
+ }
71
84
  }
72
85
  if (raw.end_card) unknown(raw.end_card, END, 'end_card');
86
+ if (raw.intro) unknown(raw.intro, END, 'intro');
87
+ if (raw.frame && typeof raw.frame === 'object') unknown(raw.frame, ['background'], 'frame');
73
88
  const todo = (fs.readFileSync(file, 'utf8').split('\n').map((l, i) => [l.replace(/#.*$/, ''), i + 1]).filter(([l]) => /\bTODO\b/.test(l)));
74
89
  for (const [, n] of todo) errors.push(`line ${n}: replace the TODO placeholder`);
75
90
 
@@ -85,6 +100,16 @@ export function check(file, { draft = false } = {}) {
85
100
  if (type === 'number' && typeof v !== 'number') errors.push(`${where}: ${kind} takes milliseconds, e.g. "${kind}: 800"`);
86
101
  if (type === 'string' && typeof v !== 'string') errors.push(`${where}: ${kind} takes a string`);
87
102
  if (type === 'target') target(v, `${where} (${kind})`);
103
+ if (type === 'mark' && typeof v !== 'string') target(v, `${where} (mark)`); // a string is a phrase to highlight
104
+ if (type === 'select') {
105
+ if (!v?.target || v?.option == null) errors.push(`${where}: select needs { target: <dropdown>, option: "visible text of the option" }`);
106
+ else target(v.target, `${where} (select.target)`);
107
+ }
108
+ if (type === 'note') {
109
+ if (!v?.target || !v?.text) errors.push(`${where}: note needs { target: <target>, text: "short label" }`);
110
+ else { target(v.target, `${where} (note.target)`); unknown(v, ['target', 'text', 'side', 'ms', 'timeout'], `${where} (note)`); }
111
+ if (v?.side && !['auto', 'left', 'right', 'top', 'bottom'].includes(v.side)) errors.push(`${where}: note side must be auto, left, right, top or bottom`);
112
+ }
88
113
  if (type === 'type') {
89
114
  if (typeof v === 'string' || typeof v === 'number') return;
90
115
  if (v?.text == null) errors.push(`${where}: type needs text — "type: hello" types into the focused element, "type: { target: <target>, text: hello }" clicks the target first`);
@@ -104,7 +129,7 @@ export function check(file, { draft = false } = {}) {
104
129
  let summary = '';
105
130
  if (cfg) {
106
131
  const visible = cfg.steps.filter((s) => !s.hidden);
107
- const says = visible.filter((s) => s.say).length + (cfg.endCard?.say ? 1 : 0);
132
+ const says = visible.filter((s) => s.say).length + (cfg.endCard?.say ? 1 : 0) + (cfg.intro?.say ? 1 : 0);
108
133
  if (cfg.voice && !says) warnings.push('voice is set but no step has a `say:` line');
109
134
  if (!cfg.voice && says) warnings.push('steps have `say:` lines but there is no `voice:` block, so they will not be spoken');
110
135
  if (!draft && cfg.voice && ['elevenlabs', 'openai'].includes(cfg.voice.provider)) {
@@ -126,7 +151,7 @@ export function check(file, { draft = false } = {}) {
126
151
  const fixed = visible.filter((s) => s.duration !== 'auto').reduce((a, s) => a + s.duration, 0);
127
152
  const auto = visible.filter((s) => s.duration === 'auto').length;
128
153
  const ec = cfg.endCard ? (cfg.endCard.duration === 'auto' ? null : cfg.endCard.duration) : 0;
129
- const length = auto ? `${fixed ? `${fixed.toFixed(1)}s fixed + ` : ''}${auto} steps timed to narration${cfg.endCard ? ' + end card' : ''}`
154
+ const length = auto ? `${fixed ? `${fixed.toFixed(1)}s fixed + ` : ''}${auto} steps timed to narration${cfg.endCard ? ' + end card' : ''}${cfg.intro ? ' + intro' : ''}`
130
155
  : `${fixed.toFixed(1)}s of steps${cfg.endCard ? ` + ${ec ?? 'auto'}s end card` : ''}${ec != null ? ` = ${(fixed + ec).toFixed(1)}s total` : ''}`;
131
156
  summary = `${cfg.name}: purpose ${cfg.purpose}, ${visible.length} visible steps, ${length}` +
132
157
  (cfg.voice ? `, voice ${cfg.voice.provider}` : '') + ` → ${cfg.out}`;
package/src/compose.mjs CHANGED
@@ -18,14 +18,21 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
18
18
  const { width: W, height: H, fps: FPS } = cfg.output;
19
19
  const K = tl.scale; // css px -> output px
20
20
  const ec0 = cfg.endCard;
21
- const END = !ec0 ? 0 : ec0.duration === 'auto' ? Math.max(1.0, (voiceLens.endCard ?? 0) + 0.6) : ec0.duration;
21
+ // a card with bullets needs time to read them: they appear one by one, then hold
22
+ const readTime = (c) => (c?.bullets?.length ? 1.6 + 0.4 * c.bullets.length + 0.6 * c.bullets.length : 0);
23
+ // `think: N` (question cards): after the question is read out, N seconds with a countdown bar
24
+ const cardLen = (c, voice, min) => (c.duration === 'auto' || c.duration == null ? Math.max(min, (voice ?? 0) + 0.9, readTime(c)) + (c.think ?? 0) : c.duration);
25
+ const END = !ec0 ? 0 : ec0.duration === 'auto' ? Math.max(1.0, (voiceLens.endCard ?? 0) + 0.6, readTime(ec0)) : ec0.duration;
26
+ const in0 = cfg.intro;
27
+ const INTRO = !in0 ? 0 : in0.duration === 'auto' ? Math.max(1.8, (voiceLens.intro ?? 0) + 0.8, readTime(in0)) : in0.duration;
28
+ const cards = []; // section cards: { i, t0, t1, card }
22
29
 
23
30
  // --- 1. segments (one per visible step), split into motion / waiting pieces ------------
24
31
  // Waiting (page loads, processing) is squeezed hard; cursor motion keeps a natural pace.
25
32
  // `duration: auto` plays motion in real time and makes the step as long as its narration
26
33
  // needs: extra time first shows more of the waiting, then holds the last frame.
27
34
  const segs = [], pieces = [];
28
- let acc = 0, afterHidden = false;
35
+ let acc = INTRO, afterHidden = false; // the intro card plays over the first frame
29
36
  for (const [i, s] of cfg.steps.entries()) {
30
37
  const r = tl.steps[i];
31
38
  if (s.hidden) { afterHidden = segs.length > 0; continue; }
@@ -45,10 +52,12 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
45
52
  const Wt = parts.filter((p) => p[2]).reduce((x, p) => x + p[1] - p[0], 0);
46
53
  let D, waitBudget, motionBudget, hold = 0;
47
54
  if (s.duration === 'auto') {
48
- const voiceNeed = voiceLens.steps[i] != null ? voiceLens.steps[i] + (s.sayAt ?? 0.15) + 0.4 : 0;
55
+ const voiceNeed = voiceLens.steps[i] != null ? voiceLens.steps[i] + (s.sayAt ?? 0.15) + cfg.pace.tail : 0;
49
56
  waitBudget = Math.min(Wt, cfg.maxWait);
50
57
  motionBudget = M;
51
- D = Math.max(M + waitBudget, voiceNeed, 0.8);
58
+ // a silent step holds its result too (docs GIFs: long enough to see it before the loop restarts)
59
+ const quiet = s.say ? 0 : cfg.clips.length ? 1.5 : cfg.pace.tail;
60
+ D = Math.max(M + waitBudget + quiet, voiceNeed, 0.8);
52
61
  let extra = D - M - waitBudget;
53
62
  const stretch = Math.min(extra, Wt - waitBudget);
54
63
  waitBudget += stretch; extra -= stretch;
@@ -58,6 +67,13 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
58
67
  waitBudget = M + Wt <= D ? Wt * D / (M + Wt) : M === 0 ? D : Math.min(Wt, Math.max(D - M, 0.15 * D));
59
68
  motionBudget = D - waitBudget;
60
69
  }
70
+ if (s.card) {
71
+ // a section card plays over the step's first frame, before the step
72
+ const C = cardLen(s.card, voiceLens.cards?.[i], 2.4);
73
+ pieces.push({ raw: [r.start, r.start], o0: acc, o1: acc + C });
74
+ cards.push({ i, t0: acc, t1: acc + C, card: s.card, thinkAt: C - (s.card.think ?? 0) - 0.3 });
75
+ acc += C;
76
+ }
61
77
  const g = { i, step: s, o0: acc, o1: acc + D, zoomBox: r.zoomBox, afterHidden, hold,
62
78
  motionSpeed: M && motionBudget ? M / motionBudget : 1, waitSpeed: Wt && waitBudget ? Wt / waitBudget : 1 };
63
79
  for (const [a, b, w] of parts) {
@@ -89,7 +105,7 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
89
105
  const t = n / FPS;
90
106
  while (pi + 1 < pieces.length && t >= pieces[pi].o1) pi++;
91
107
  const p = pieces[pi];
92
- const r = p.raw[0] + Math.min(1, (t - p.o0) / Math.max(1e-6, p.o1 - p.o0)) * (p.raw[1] - p.raw[0]);
108
+ const r = p.raw[0] + Math.min(1, Math.max(0, (t - p.o0) / Math.max(1e-6, p.o1 - p.o0))) * (p.raw[1] - p.raw[0]);
93
109
  while (fi + 1 < tl.frames.length && tl.frames[fi + 1].t <= r) fi++;
94
110
  fs.linkSync(path.join(cfg.work, 'raw', tl.frames[fi].file), path.join(SEQ, `${String(n).padStart(5, '0')}.jpg`));
95
111
  }
@@ -124,7 +140,33 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
124
140
  // --- 3. zoom keyframes: [time, zoom, [cx, cy]] in output px -------------------------------
125
141
  const C0 = [W / 2, H / 2];
126
142
  const kf = [[0, 1, C0]];
143
+ // follow camera: steps without a zoom of their own zoom in on the boxes their actions touched
144
+ // (clicks, typing, marks), and consecutive followed steps pan from one subject to the next
145
+ const { width: VW0, height: VH0 } = cfg.viewport;
146
+ const followOf = (g) => {
147
+ if (!cfg.follow || g.step.zoom || g.step.follow === false) return null;
148
+ const bs = (tl.steps[g.i].marks ?? []).map((m) => m.box).filter((b) => b && b.width < VW0 * 0.9);
149
+ if (!bs.length) return null;
150
+ const u = bs.reduce((a, b) => ({ x0: Math.min(a.x0, b.x), y0: Math.min(a.y0, b.y), x1: Math.max(a.x1, b.x + b.width), y1: Math.max(a.y1, b.y + b.height) }), { x0: 1e9, y0: 1e9, x1: -1e9, y1: -1e9 });
151
+ const w = u.x1 - u.x0 + 160, h = u.y1 - u.y0 + 140; // some context around the subject
152
+ const scale = Math.max(1, Math.min(cfg.follow.scale, VW0 / w, VH0 / h));
153
+ if (scale < 1.15) return null;
154
+ return { box: { x: u.x0, y: u.y0, width: u.x1 - u.x0, height: u.y1 - u.y0 }, scale };
155
+ };
156
+ let followEnd = -1;
127
157
  for (const g of segs) {
158
+ const f = followOf(g);
159
+ if (f) {
160
+ g.zoomBox = f.box;
161
+ const c = [(f.box.x + f.box.width / 2) * K, (f.box.y + f.box.height / 2) * K];
162
+ const move = Math.min(0.7, (g.o1 - g.o0) / 3);
163
+ g.zoomPeak = g.o0 + move + 0.1;
164
+ if (Math.abs(followEnd - g.o0) < 1e-3 && kf.at(-1)[1] === 1) kf.pop(); // pan straight from the previous subject
165
+ else kf.push([g.o0, 1, C0]);
166
+ kf.push([g.o0 + move, f.scale, c], [g.o1 - 0.6, f.scale, c], [g.o1, 1, C0]);
167
+ followEnd = g.o1;
168
+ continue;
169
+ }
128
170
  const z = g.step.zoom;
129
171
  const t = z?.target;
130
172
  if (t && typeof t === 'object' && typeof t.x === 'number' && typeof t.y === 'number' && !t.role && !t.css && !t.text) {
@@ -169,9 +211,13 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
169
211
  const z = z0 + (z1 - z0) * e, cx = c0[0] + (c1[0] - c0[0]) * e, cy = c0[1] + (c1[1] - c0[1]) * e;
170
212
  return { z, x0: Math.min(Math.max(cx - W / z / 2, 0), W - W / z), y0: Math.min(Math.max(cy - H / z / 2, 0), H - H / z) };
171
213
  };
214
+ // browser-window frame: the page is drawn at (FX, FY), FW x FH, inside a window on a backdrop
215
+ const even = (x) => 2 * Math.round(x / 2);
216
+ const FW = cfg.frame ? even(W * 0.86) : W, FH = cfg.frame ? even(H * 0.86) : H, BAR = cfg.frame ? Math.round(H * 0.034) : 0;
217
+ const FX = even((W - FW) / 2), FY = cfg.frame ? even((H - FH - BAR) / 2 + BAR) : 0, F = FW / W;
172
218
  const onScreen = (b, t) => {
173
219
  const v = view(t);
174
- return { x: (b.x * K - v.x0) * v.z, y: (b.y * K - v.y0) * v.z, w: b.width * K * v.z, h: b.height * K * v.z };
220
+ return { x: FX + (b.x * K - v.x0) * v.z * F, y: FY + (b.y * K - v.y0) * v.z * F, w: b.width * K * v.z * F, h: b.height * K * v.z * F };
175
221
  };
176
222
 
177
223
  // --- 4. captions + end card rendered as PNGs ----------------------------------------------
@@ -227,7 +273,9 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
227
273
  const other = want === 'top' ? 'bottom' : 'top';
228
274
  let pos = want;
229
275
  const hit = hits(want);
230
- if (hit && !hits(other)) {
276
+ if (hit && cfg.subtitles === 'burn' && other === 'bottom') {
277
+ warn(`step ${g.i + 1}: the caption covers ${hit.what}, and the bottom is kept for the burned-in subtitles — shorten the caption, or change the zoom`);
278
+ } else if (hit && !hits(other)) {
231
279
  pos = other;
232
280
  warn(`step ${g.i + 1}: the ${want} caption would cover ${hit.what}, so it was moved to the ${other}` + (explicit ? ` (despite captionPosition: ${explicit})` : '') + ` — set captionPosition: ${other} to make this explicit`);
233
281
  } else if (hit) warn(`step ${g.i + 1}: the caption covers ${hit.what} at both top and bottom — shorten the caption, or change the zoom`);
@@ -235,20 +283,80 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
235
283
  else captions.push({ text: g.step.caption, t: [g.o0, g.o1], pos, n });
236
284
  }
237
285
  for (const [i, c] of captions.entries()) await shot(bubble(c.text, c.n, c.pos), path.join(cfg.work, `cap${i}.png`), true);
238
- const ec = cfg.endCard;
239
- if (ec) {
240
- const logoPath = ec.logoFile ?? path.join(cfg.work, 'logo.png');
286
+ // Intro and end cards are short animations (logo pops, title rises, the highlight sweeps, a command
287
+ // CTA types itself out), rendered frame by frame by seeking the page's CSS animations.
288
+ const u = H / 1080;
289
+ const card = (c, logoPath, { thinkAt = 0 } = {}) => {
290
+ const image = c.imageFile && fs.existsSync(c.imageFile)
291
+ ? `<img class="a rise" src="data:image/${path.extname(c.imageFile).slice(1).replace('jpg', 'jpeg').replace('svg', 'svg+xml')};base64,${fs.readFileSync(c.imageFile).toString('base64')}" style="animation-delay:.4s;max-width:${W * 0.6}px;max-height:${H * 0.42}px;border-radius:${12 * H / 1080}px;box-shadow:0 ${12 * H / 1080}px ${36 * H / 1080}px rgba(15,23,42,.18)">` : '';
292
+ const think = c.think ? `<div class="a rise" style="animation-delay:${thinkAt.toFixed(2)}s;position:absolute;left:50%;bottom:${H * 0.1}px;transform:translateX(-50%);width:${W * 0.3}px;text-align:center;font-size:${26 * H / 1080}px;color:#64748b">
293
+ <div style="margin-bottom:${12 * H / 1080}px">Pause and think</div>
294
+ <div style="height:${8 * H / 1080}px;border-radius:99px;background:#e2e8f0;overflow:hidden"><div style="height:100%;background:${accent};transform-origin:left;animation:drain ${c.think}s linear ${thinkAt.toFixed(2)}s both"></div></div></div>
295
+ <style>@keyframes drain{from{transform:scaleX(1)}to{transform:scaleX(0)}}</style>` : '';
241
296
  const logo = fs.existsSync(logoPath)
242
- ? `<img src="data:image/${path.extname(logoPath).slice(1).replace('jpg', 'jpeg').replace('svg', 'svg+xml')};base64,${fs.readFileSync(logoPath).toString('base64')}" style="height:${Math.round(H * 0.09)}px">` : '';
243
- const u = H / 1080;
244
- await shot(`<body style="margin:0;width:${W}px;height:${H}px;${fontCss}
297
+ ? `<img class="a pop" src="data:image/${path.extname(logoPath).slice(1).replace('jpg', 'jpeg').replace('svg', 'svg+xml')};base64,${fs.readFileSync(logoPath).toString('base64')}" style="height:${Math.round(H * 0.09)}px">` : '';
298
+ const cmd = c.cta && /^\$?\s*(npx|npm|pnpm|yarn|bun|pip|pipx|uv|brew|curl|git|docker|cargo|go)\b/.test(c.cta);
299
+ const ctaText = String(c.cta ?? '').replace(/^\$\s*/, '');
300
+ return `<body style="margin:0;width:${W}px;height:${H}px;${fontCss}
245
301
  background:radial-gradient(${W * 0.62}px ${H * 0.65}px at 50% 40%,#ffffff 0%,#eef2f7 60%,#e2e8f0 100%);
246
302
  display:flex;flex-direction:column;align-items:center;justify-content:center;gap:${28 * u}px;text-align:center">
303
+ <style>
304
+ .a{animation-fill-mode:both;animation-timing-function:cubic-bezier(.2,.8,.2,1)}
305
+ .pop{animation-name:pop;animation-duration:.55s;animation-delay:.05s}
306
+ .rise{animation-name:rise;animation-duration:.6s}
307
+ .hl{background:linear-gradient(transparent 62%,${accent} 62%) no-repeat 0 0/0% 100%;animation:sweep .6s cubic-bezier(.4,0,.2,1) .75s both}
308
+ .type{display:inline-block;overflow:hidden;white-space:nowrap;vertical-align:bottom;width:0;animation:type ${(ctaText.length * 0.045).toFixed(2)}s steps(${ctaText.length || 1}) .8s both}
309
+ .caret{display:inline-block;width:.55em;height:1.1em;margin-left:.1em;vertical-align:-.15em;background:${accent};animation:blink 1s steps(1) .8s infinite}
310
+ @keyframes pop{from{opacity:0;transform:scale(.7)}to{opacity:1;transform:none}}
311
+ @keyframes rise{from{opacity:0;transform:translateY(${24 * u}px)}to{opacity:1;transform:none}}
312
+ @keyframes sweep{to{background-size:100% 100%}}
313
+ @keyframes type{to{width:${ctaText.length}ch}}
314
+ @keyframes blink{50%{opacity:0}}
315
+ </style>
316
+ ${c.kicker ? `<div class="a rise" style="font-size:${30 * u}px;font-weight:600;letter-spacing:.08em;text-transform:uppercase;color:#64748b">${esc(c.kicker)}</div>` : ''}
247
317
  <div style="display:flex;align-items:center;gap:${22 * u}px">${logo}
248
- ${ec.title ? `<span style="font-size:${92 * u}px;font-weight:600;letter-spacing:-.03em;color:${ink}">${esc(ec.title)}</span>` : ''}</div>
249
- ${ec.subtitle ? `<div style="font-size:${44 * u}px;color:#334155;letter-spacing:-.01em">${esc(ec.subtitle).replace(/\*\*(.+?)\*\*/g, `<span style="background:linear-gradient(transparent 62%,${accent} 62%)">$1</span>`)}</div>` : ''}
250
- ${ec.cta ? `<div style="margin-top:${18 * u}px;font-size:${38 * u}px;font-weight:600;color:#fff;background:${ink};padding:${20 * u}px ${46 * u}px;border-radius:${16 * u}px">${esc(ec.cta)}</div>` : ''}
251
- </body>`, path.join(cfg.work, 'endcard.png'), false);
318
+ ${c.title ? `<span class="a rise" style="animation-delay:.12s;font-size:${92 * u}px;font-weight:600;letter-spacing:-.03em;color:${ink}">${esc(c.title).replace(/\*\*(.+?)\*\*/g, '<span class="hl">$1</span>')}</span>` : ''}</div>
319
+ ${c.subtitle ? `<div class="a rise" style="animation-delay:.3s;font-size:${44 * u}px;color:#334155;letter-spacing:-.01em">${esc(c.subtitle).replace(/\*\*(.+?)\*\*/g, '<span class="hl">$1</span>')}</div>` : ''}
320
+ ${image}${think}
321
+ ${c.bullets?.length ? `<ol style="margin:${10 * u}px 0 0;padding:0;list-style:none;text-align:left;display:flex;flex-direction:column;gap:${18 * u}px">${c.bullets.map((b, k) =>
322
+ `<li class="a rise" style="animation-delay:${(0.6 + 0.4 * k).toFixed(2)}s;display:flex;align-items:center;gap:${20 * u}px;font-size:${38 * u}px;color:#1e293b">
323
+ <span style="flex:none;display:inline-flex;align-items:center;justify-content:center;width:${52 * u}px;height:${52 * u}px;border-radius:50%;background:${accent};color:${ink};font-weight:700;font-size:${28 * u}px">${k + 1}</span>
324
+ <span>${md(b, ink)}</span></li>`).join('')}</ol>` : ''}
325
+ ${!c.cta ? '' : cmd
326
+ ? `<div class="a rise" style="animation-delay:.45s;margin-top:${18 * u}px;font:500 ${36 * u}px ui-monospace,SFMono-Regular,Menlo,monospace;color:#e2e8f0;background:${ink};padding:${20 * u}px ${36 * u}px;border-radius:${16 * u}px;text-align:left;box-shadow:0 ${16 * u}px ${40 * u}px rgba(15,23,42,.25)"><span style="color:${accent}">$</span> <span class="type">${esc(ctaText)}</span><span class="caret"></span></div>`
327
+ : `<div class="a rise" style="animation-delay:.45s;margin-top:${18 * u}px;font-size:${38 * u}px;font-weight:600;color:#fff;background:${ink};padding:${20 * u}px ${46 * u}px;border-radius:${16 * u}px">${esc(c.cta)}</div>`}
328
+ </body>`;
329
+ };
330
+ const animate = async (html, seconds, dir) => {
331
+ fs.rmSync(dir, { recursive: true, force: true });
332
+ fs.mkdirSync(dir, { recursive: true });
333
+ await pg.setContent(`<html><head>${head}</head>${html}</html>`, { waitUntil: 'networkidle' }).catch(() => {});
334
+ await pg.evaluate(() => document.fonts.ready);
335
+ const n = Math.ceil(seconds * FPS) + 1;
336
+ for (let k = 0; k < n; k++) {
337
+ await pg.evaluate((ms) => document.getAnimations().forEach((a) => { a.pause(); a.currentTime = ms; }), (k * 1000) / FPS);
338
+ await pg.screenshot({ path: path.join(dir, `${String(k).padStart(4, '0')}.jpg`), type: 'jpeg', quality: 92 });
339
+ }
340
+ };
341
+ const ec = cfg.endCard;
342
+ if (ec) await animate(card(ec, ec.logoFile ?? path.join(cfg.work, 'logo.png')), END + 0.5, path.join(cfg.work, 'endcard'));
343
+ for (const [k, c] of cards.entries()) await animate(card(c.card, c.card.logoFile ?? '', { thinkAt: c.thinkAt }), c.t1 - c.t0, path.join(cfg.work, `card${k}`));
344
+ if (in0) await animate(card(in0, in0.logoFile ?? path.join(cfg.work, 'intro-logo.png')), INTRO, path.join(cfg.work, 'intro'));
345
+ if (cfg.frame) {
346
+ // backdrop + window (under the page) and the backdrop again with a rounded hole (over it, for the corners)
347
+ const bg = cfg.frame.background ?? `radial-gradient(${W * 0.7}px ${H * 0.8}px at 15% 0%, ${accent}66, transparent 70%), radial-gradient(${W * 0.7}px ${H * 0.8}px at 100% 100%, #6366f166, transparent 70%), linear-gradient(135deg, #1e293b, ${ink})`;
348
+ const R = Math.round(12 * u), host = new URL(cfg.url).host.replace(/^www\./, '') + new URL(cfg.url).pathname.replace(/\/$/, '');
349
+ const dot = (c) => `<span style="width:${13 * u}px;height:${13 * u}px;border-radius:50%;background:${c};display:inline-block"></span>`;
350
+ await shot(`<body style="margin:0;width:${W}px;height:${H}px;background:${bg};${fontCss}">
351
+ <div style="position:absolute;left:${FX}px;top:${FY - BAR}px;width:${FW}px;height:${FH + BAR}px;border-radius:${R}px;background:#fff;box-shadow:0 ${30 * u}px ${80 * u}px rgba(0,0,0,.45),0 0 0 1px rgba(255,255,255,.08)"></div>
352
+ <div style="position:absolute;left:${FX}px;top:${FY - BAR}px;width:${FW}px;height:${BAR}px;border-radius:${R}px ${R}px 0 0;background:#e8ebef;display:flex;align-items:center;border-bottom:1px solid #d5d9df">
353
+ <div style="display:flex;gap:${8 * u}px;margin-left:${16 * u}px">${dot('#ff5f57')}${dot('#febc2e')}${dot('#28c840')}</div>
354
+ <div style="position:absolute;left:50%;transform:translateX(-50%);font-size:${15 * u}px;color:#4b5563;background:#fff;border-radius:${8 * u}px;padding:${4 * u}px ${60 * u}px">${esc(host)}</div>
355
+ </div></body>`, path.join(cfg.work, 'frame-bg.png'), false);
356
+ const hole = encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}"><rect x="${FX}" y="${FY - BAR}" width="${FW}" height="${FH + BAR}" rx="${R}"/></svg>`);
357
+ await shot(`<body style="margin:0;width:${W}px;height:${H}px;background:transparent">
358
+ <div style="position:absolute;inset:0;background:${bg};-webkit-mask:linear-gradient(#000 0 0),url('data:image/svg+xml,${hole}');-webkit-mask-composite:xor;mask-composite:exclude"></div></body>`,
359
+ path.join(cfg.work, 'frame-fg.png'), true);
252
360
  }
253
361
  await browser.close();
254
362
 
@@ -258,17 +366,38 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
258
366
  `zoompan=z='${zExpr}':x='clip(${cxExpr}-iw/zoom/2,0,iw-iw/zoom)':y='clip(${cyExpr}-ih/zoom/2,0,ih-ih/zoom)'` +
259
367
  `:d=1:fps=${FPS}:s=${W}x${H},format=yuv420p${END ? `,tpad=stop_mode=clone:stop_duration=${END}` : ''}[v0];\n`;
260
368
  let last = 'v0', idx = 1;
369
+ if (cfg.frame) {
370
+ inputs.push('-loop', '1', '-t', `${TOTAL}`, '-framerate', `${FPS}`, '-i', path.join(cfg.work, 'frame-bg.png'),
371
+ '-loop', '1', '-t', `${TOTAL}`, '-framerate', `${FPS}`, '-i', path.join(cfg.work, 'frame-fg.png'));
372
+ graph += `[v0]scale=${FW}:${FH}:flags=lanczos[pg];[${idx}:v][pg]overlay=${FX}:${FY}[fb];[fb][${idx + 1}:v]overlay=0:0,format=yuv420p[vf];\n`;
373
+ last = 'vf'; idx += 2;
374
+ }
261
375
  for (const [i, c] of captions.entries()) {
262
376
  const a = c.t[0] + 0.1, b = c.t[1] - 0.1;
263
- inputs.push('-loop', '1', '-t', `${TOTAL}`, '-framerate', `${FPS}`, '-i', path.join(cfg.work, `cap${i}.png`));
264
- graph += `[${idx}:v]format=rgba,fade=in:st=${a.toFixed(3)}:d=0.15:alpha=1,fade=out:st=${(b - 0.15).toFixed(3)}:d=0.15:alpha=1[c${i}];\n` +
265
- `[${last}][c${i}]overlay=0:0:enable='between(t,${a.toFixed(3)},${b.toFixed(3)})'[v${idx}];\n`;
377
+ // each caption is an input only as long as it is on screen (decoding a looped PNG for the whole
378
+ // video, once per caption, made long tutorials take minutes to compose)
379
+ inputs.push('-loop', '1', '-t', `${(b - a + 0.1).toFixed(3)}`, '-framerate', `${FPS}`, '-i', path.join(cfg.work, `cap${i}.png`));
380
+ graph += `[${idx}:v]format=rgba,setpts=PTS-STARTPTS+${a.toFixed(3)}/TB,fade=in:st=${a.toFixed(3)}:d=0.15:alpha=1,fade=out:st=${(b - 0.15).toFixed(3)}:d=0.15:alpha=1[c${i}];\n` +
381
+ `[${last}][c${i}]overlay=0:0:eof_action=pass:enable='between(t,${a.toFixed(3)},${b.toFixed(3)})'[v${idx}];\n`;
266
382
  last = `v${idx++}`;
267
383
  }
384
+ for (const [k, c] of cards.entries()) {
385
+ inputs.push('-framerate', `${FPS}`, '-i', path.join(cfg.work, `card${k}`, '%04d.jpg'));
386
+ graph += `[${idx}:v]format=rgba,setpts=PTS-STARTPTS+${c.t0.toFixed(3)}/TB,fade=in:st=${c.t0.toFixed(3)}:d=0.25:alpha=1,fade=out:st=${Math.max(c.t0, c.t1 - 0.3).toFixed(3)}:d=0.3:alpha=1[sc${k}];\n` +
387
+ `[${last}][sc${k}]overlay=0:0:eof_action=pass:enable='between(t,${c.t0.toFixed(3)},${c.t1.toFixed(3)})'[v${++idx}];\n`;
388
+ last = `v${idx}`;
389
+ }
268
390
  if (ec) {
269
391
  const st = VIDEO - 0.25;
270
- inputs.push('-loop', '1', '-t', `${TOTAL}`, '-framerate', `${FPS}`, '-i', path.join(cfg.work, 'endcard.png'));
271
- graph += `[${idx}:v]format=rgba,fade=in:st=${st.toFixed(3)}:d=0.3:alpha=1[ec];\n[${last}][ec]overlay=0:0:enable='gte(t,${st.toFixed(3)})'[v${++idx}];\n`;
392
+ inputs.push('-framerate', `${FPS}`, '-i', path.join(cfg.work, 'endcard', '%04d.jpg'));
393
+ graph += `[${idx}:v]format=rgba,setpts=PTS-STARTPTS+${st.toFixed(3)}/TB,fade=in:st=${st.toFixed(3)}:d=0.3:alpha=1[ec];\n` +
394
+ `[${last}][ec]overlay=0:0:eof_action=repeat:enable='gte(t,${st.toFixed(3)})'[v${++idx}];\n`;
395
+ last = `v${idx}`;
396
+ }
397
+ if (in0) {
398
+ inputs.push('-framerate', `${FPS}`, '-i', path.join(cfg.work, 'intro', '%04d.jpg'));
399
+ graph += `[${idx}:v]format=rgba,fade=out:st=${Math.max(0, INTRO - 0.35).toFixed(3)}:d=0.35:alpha=1[in];\n` +
400
+ `[${last}][in]overlay=0:0:eof_action=pass[v${++idx}];\n`;
272
401
  last = `v${idx}`;
273
402
  }
274
403
  graph += `[${last}]trim=duration=${TOTAL},format=yuv420p[out]`;
@@ -285,6 +414,9 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
285
414
  // --- 6. preview contact sheet: one frame per step (at its zoom peak) + end card ------------
286
415
  // zoomed steps: at the zoom peak; others: late in the step, where its actions' result is visible
287
416
  const shots = segs.map((g) => ({ t: Math.min(g.o1 - 0.05, g.zoomPeak ?? g.o0 + (g.o1 - g.o0) * 0.8), label: `step ${g.i + 1} · ${g.o0.toFixed(1)}–${g.o1.toFixed(1)}s${g.step.zoom ? ' · zoom' : ''}`, caption: g.step.caption ?? '' }));
417
+ for (const c of cards) shots.push({ t: c.t0 + (c.t1 - c.t0) * 0.85, label: `card · ${c.t0.toFixed(1)}–${c.t1.toFixed(1)}s`, caption: c.card.title ?? '' });
418
+ shots.sort((a, b) => a.t - b.t);
419
+ if (in0) shots.unshift({ t: INTRO * 0.8, label: `intro · 0.0–${INTRO.toFixed(1)}s`, caption: '' });
288
420
  if (ec) shots.push({ t: VIDEO + END / 2, label: `end card · ${VIDEO.toFixed(1)}–${TOTAL.toFixed(1)}s`, caption: '' });
289
421
  const cells = shots.map((sh, k) => {
290
422
  const f = path.join(cfg.work, `pv${k}.jpg`);
@@ -311,18 +443,37 @@ export async function compose(cfg, { log = console.log, voiceLens = { steps: {},
311
443
  whooshes: dedupe([
312
444
  ...tl.navs.map(toOut).filter((t) => t != null && t > 0.2),
313
445
  ...segs.filter((g) => g.afterHidden).map((g) => g.o0),
446
+ ...(in0 ? [INTRO - 0.3] : []),
447
+ ...cards.flatMap((c) => [c.t0, c.t1 - 0.3]),
314
448
  ...(ec ? [VIDEO - 0.25] : []),
315
449
  ]),
316
450
  risers: segs.filter((g) => g.step.sfx === 'riser').map((g) => [g.o0, g.o1]),
317
451
  chimes: segs.filter((g) => g.step.sfx === 'riser' || g.step.sfx === 'chime').map((g) => g.o1),
318
452
  // narration: each line may run until the next one starts
319
453
  voice: [
454
+ ...(in0?.say ? [{ text: in0.say, start: 0.15, where: 'intro' }] : []),
455
+ ...cards.filter((c) => c.card.say).map((c) => ({ text: c.card.say, start: c.t0 + 0.15, where: `step ${c.i + 1} card` })),
320
456
  ...segs.filter((g) => g.step.say).map((g) => ({ text: g.step.say, start: g.o0 + (g.step.sayAt ?? 0.15), where: `step ${g.i + 1}` })),
321
457
  ...(ec?.say ? [{ text: ec.say, start: VIDEO + 0.05, where: 'end card' }] : []),
322
458
  ],
323
459
  };
460
+ events.voice.sort((a, b) => a.start - b.start);
324
461
  events.voice.forEach((v, k) => { v.until = events.voice[k + 1]?.start ?? TOTAL - 0.1; });
325
462
  fs.writeFileSync(path.join(cfg.work, 'events.json'), JSON.stringify(events, null, 1));
326
463
  log(segs.map((g) => ` ${g.o0.toFixed(1)}–${g.o1.toFixed(1)}s step ${g.i + 1} motion x${g.motionSpeed.toFixed(1)} waiting x${g.waitSpeed.toFixed(1)}`).join('\n'));
327
- return { silent, events, preview, warnings, captions, segs: segs.map((g) => ({ i: g.i, o0: g.o0, o1: g.o1, caption: g.step.caption })) };
464
+ // docs clips: the part of the frame each step is about (what it clicked, typed into, marked or
465
+ // noted, with some context), in output px, same aspect ratio as the video
466
+ for (const g of segs) {
467
+ const bs = (tl.steps[g.i].marks ?? []).map((m) => onScreen(m.box, Math.max(g.o0, g.o1 - 0.1))).filter((b) => b.w > 0);
468
+ if (!bs.length) continue;
469
+ const x0 = Math.min(...bs.map((b) => b.x)), y0 = Math.min(...bs.map((b) => b.y));
470
+ const x1 = Math.max(...bs.map((b) => b.x + b.w)), y1 = Math.max(...bs.map((b) => b.y + b.h));
471
+ const pad = H * 0.12;
472
+ let w = Math.max(x1 - x0 + 2 * pad, W * 0.5), h = Math.max(y1 - y0 + 2 * pad, H * 0.5);
473
+ if (w / h > W / H) h = w * H / W; else w = h * W / H;
474
+ w = Math.min(W, w); h = Math.min(H, h);
475
+ const cx = (x0 + x1) / 2, cy = (y0 + y1) / 2;
476
+ g.crop = { x: even(Math.max(0, Math.min(W - w, cx - w / 2))), y: even(Math.max(0, Math.min(H - h, cy - h / 2))), w: even(w), h: even(h) };
477
+ }
478
+ return { silent, events, preview, warnings, captions, cards: cards.map((c) => ({ t: c.t0, title: [c.card.kicker, c.card.title].filter(Boolean).join(' · ') })), segs: segs.map((g) => ({ i: g.i, o0: g.o0, o1: g.o1, caption: g.step.caption, doc: g.step.doc ?? g.step.say, crop: g.crop })) };
328
479
  }
package/src/config.mjs CHANGED
@@ -19,17 +19,39 @@ export function loadEnv(dir) {
19
19
 
20
20
  // What the video is for sets sensible defaults; anything in the YAML overrides them.
21
21
  export const PURPOSES = {
22
- pitch: { duration: null, music: { bpm: 120, volume: 1 }, sfx: true, highlight: false, stepNumbers: false, subtitles: false, chapters: false, clips: null },
23
- tutorial: { duration: 'auto', music: { bpm: 96, volume: 0.35 }, sfx: true, highlight: true, stepNumbers: true, subtitles: true, chapters: true, clips: null },
24
- course: { duration: 'auto', music: false, sfx: true, highlight: true, stepNumbers: false, subtitles: true, chapters: true, clips: null },
25
- docs: { duration: 'auto', music: false, sfx: false, highlight: true, stepNumbers: true, subtitles: false, chapters: false, clips: 'gif' },
22
+ pitch: { duration: null, music: { bpm: 120, volume: 1 }, sfx: true, highlight: false, stepNumbers: false, subtitles: false, chapters: false, clips: null, frame: true, pace: 'fast', follow: false },
23
+ tutorial: { duration: 'auto', music: { bpm: 96, volume: 0.35 }, sfx: true, highlight: true, stepNumbers: true, subtitles: true, chapters: true, clips: null, frame: false, pace: 'slow', follow: true },
24
+ course: { duration: 'auto', music: false, sfx: true, highlight: true, stepNumbers: false, subtitles: true, chapters: true, clips: null, frame: false, pace: 'slow', follow: true },
25
+ docs: { duration: 'auto', music: false, sfx: false, highlight: true, stepNumbers: true, subtitles: false, chapters: false, clips: ['gif', 'png'], frame: false, pace: 'normal', follow: false },
26
26
  };
27
27
 
28
28
  // Where storyboards and their videos go, and how they're named: <site>-<kind>[-<topic>].yaml →
29
29
  // .mp4, so a promo, a tutorial and a lesson for the same app never collide or all read "demo".
30
+ // How fast things happen on screen. Promos are brisk; tutorials and lessons give the viewer time to
31
+ // follow each action and to read its result before the next one starts.
32
+ export const PACES = {
33
+ // cursor ms typing ms/char beat after a click (ms) hold after narration (s) waits shown up to (s) voice speed
34
+ fast: { cursor: 700, type: 55, beat: 0, tail: 0.4, maxWait: 1.0, voiceSpeed: 1 },
35
+ normal: { cursor: 900, type: 70, beat: 350, tail: 0.8, maxWait: 1.5, voiceSpeed: 1 },
36
+ slow: { cursor: 1200, type: 95, beat: 800, tail: 1.6, maxWait: 3.0, voiceSpeed: 0.92 },
37
+ };
38
+
30
39
  export const VIDEO_DIR = 'videos';
31
40
  export const KINDS = { pitch: 'promo', tutorial: 'tutorial', course: 'lesson', docs: 'docs' };
32
- export const siteOf = (url) => new URL(url).hostname.replace(/^www\./, '').split('.')[0];
41
+ // pxgenius.ai → pxgenius; an IP or a port is kept whole so two internal apps don't share a name
42
+ // (http://10.1.2.3:8080 → 10-1-2-3-8080, http://localhost:3000 → localhost-3000)
43
+ export const siteOf = (url) => {
44
+ const { hostname, port } = new URL(url);
45
+ const host = hostname.replace(/^\[|\]$/g, '');
46
+ const ip = /^[\d.]+$/.test(host) || host.includes(':');
47
+ return [ip ? host.replace(/[.:]+/g, '-').replace(/^-|-$/g, '') : host.replace(/^www\./, '').split('.')[0], port].filter(Boolean).join('-');
48
+ };
49
+
50
+ // A clear message for an internal site with a self-signed / untrusted HTTPS certificate.
51
+ export const certError = (e, url) => (/ERR_CERT|ERR_SSL/.test(e?.message ?? '')
52
+ ? new Error(`${url} has an untrusted HTTPS certificate (${e.message.match(/ERR_\w+/)[0]}). If it is your own internal site with a self-signed ` +
53
+ 'certificate, add `ignoreHTTPSErrors: true` to the storyboard (inspect/init: --insecure, MCP: ignore_https_errors: true).')
54
+ : null);
33
55
  const slug = (s) => String(s).toLowerCase().normalize('NFKD').replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-+|-+$/g, '').slice(0, 40);
34
56
 
35
57
  export function defaultStoryboard(url, purpose = 'pitch', topic) {
@@ -63,26 +85,39 @@ export function loadConfig(file, { draft = false } = {}) {
63
85
  const P = PURPOSES[purpose];
64
86
  if (!P) throw new Error(`purpose must be one of ${Object.keys(PURPOSES).join(', ')}`);
65
87
  const pick = (k) => (raw[k] !== undefined ? raw[k] : P[k]);
88
+ if (!PACES[pick('pace')]) throw new Error(`pace must be one of ${Object.keys(PACES).join(', ')}`);
66
89
 
67
90
  const steps = raw.steps.map((s, i) => {
68
91
  const duration = s.duration ?? P.duration;
69
92
  if (!s.hidden && duration !== 'auto' && !(duration > 0)) {
70
93
  throw new Error(`step ${i + 1}: visible steps need a positive \`duration\` in seconds, or \`duration: auto\``);
71
94
  }
72
- return { actions: [], ...s, duration };
95
+ const card = s.card ? { ...s.card, ...(s.card.image ? { imageFile: path.resolve(dir, s.card.image) } : {}) } : undefined;
96
+ return { actions: [], ...s, duration, card };
73
97
  });
74
98
 
75
99
  let endCard = raw.end_card === false ? null : raw.end_card ?? null;
76
100
  if (endCard) endCard = { duration: endCard.say ? 'auto' : 1.0, ...endCard };
77
- if (endCard?.logo && typeof endCard.logo === 'string' && /\.(png|jpe?g|svg|webp)$/i.test(endCard.logo)) {
78
- endCard.logoFile = path.resolve(dir, endCard.logo);
101
+ // An intro title card (promos; optional for tutorials and lessons). Same fields as the end card.
102
+ let intro = raw.intro === false ? null : raw.intro ?? null;
103
+ if (intro) intro = { duration: intro.say ? 'auto' : 2.2, ...intro };
104
+ for (const card of [endCard, intro]) {
105
+ if (card?.image) card.imageFile = path.resolve(dir, card.image);
106
+ if (card?.logo && typeof card.logo === 'string' && /\.(png|jpe?g|svg|webp)$/i.test(card.logo)) card.logoFile = path.resolve(dir, card.logo);
79
107
  }
108
+ // Browser-window frame on a backdrop (promos by default): true, false, or { background: <css> }
109
+ const frame0 = pick('frame');
110
+ // follow: the camera zooms in on what each step touches and pans from step to step (tutorials)
111
+ const follow0 = pick('follow');
112
+ const follow = follow0 ? { scale: 1.8, ...(typeof follow0 === 'object' ? follow0 : {}) } : null;
113
+ const frame = frame0 ? { background: null, ...(typeof frame0 === 'object' ? frame0 : {}) } : null;
80
114
 
81
115
  let voice = null;
82
116
  if (raw.voice) {
83
117
  const provider = raw.voice.provider ?? 'kokoro';
84
118
  if (!VOICE_DEFAULTS[provider]) throw new Error(`voice.provider must be one of ${Object.keys(VOICE_DEFAULTS).join(', ')}`);
85
- voice = { speed: 1, volume: 1, ...VOICE_DEFAULTS[provider], ...raw.voice, provider };
119
+ const pace0 = PACES[pick('pace')] ?? PACES.normal;
120
+ voice = { speed: pace0.voiceSpeed, volume: 1, ...VOICE_DEFAULTS[provider], ...raw.voice, provider };
86
121
  if (draft && provider !== 'kokoro') {
87
122
  voice = { ...voice, provider: 'kokoro', voice: raw.voice.draftVoice ?? VOICE_DEFAULTS.kokoro.voice, model: undefined };
88
123
  }
@@ -90,8 +125,9 @@ export function loadConfig(file, { draft = false } = {}) {
90
125
 
91
126
  const m = pick('music');
92
127
  let music = m === false || m === null ? null : { bpm: 120, volume: 1, ...(P.music || {}), ...(raw.music || {}) };
93
- const clips = pick('clips');
94
- if (clips && !['gif', 'webm', 'mp4'].includes(clips)) throw new Error('clips must be gif, webm or mp4');
128
+ // per-step files for docs: any of gif, webm, mp4, png (annotated still of the step's result)
129
+ const clips = [].concat(pick('clips') ?? []).filter(Boolean);
130
+ for (const c of clips) if (!['gif', 'webm', 'mp4', 'png'].includes(c)) throw new Error('clips must be gif, webm, mp4 or png (or a list of them)');
95
131
  if (music?.file) music.file = path.resolve(dir, music.file);
96
132
 
97
133
  return {
@@ -102,19 +138,25 @@ export function loadConfig(file, { draft = false } = {}) {
102
138
  subtitles: pick('subtitles'),
103
139
  chapters: pick('chapters'),
104
140
  clips,
105
- maxWait: raw.maxWait ?? 1.0,
141
+ pace: { name: pick('pace'), ...PACES[pick('pace')] },
142
+ maxWait: raw.maxWait ?? PACES[pick('pace')].maxWait,
106
143
  url: raw.url,
107
144
  viewport,
108
145
  output,
109
146
  scale,
110
147
  colorScheme: raw.colorScheme ?? 'light',
148
+ ignoreHTTPSErrors: raw.ignoreHTTPSErrors === true,
111
149
  storageState: raw.storageState ? path.resolve(dir, raw.storageState) : undefined,
112
150
  scrollOffset: raw.scrollOffset ?? 40,
113
- captionPosition: raw.captionPosition ?? 'bottom',
151
+ // burned-in subtitles sit at the bottom, so captions move to the top
152
+ captionPosition: raw.captionPosition ?? (pick('subtitles') === 'burn' ? 'top' : 'bottom'),
114
153
  theme: { accent: '#d9f75b', ink: '#0f172a', font: 'Inter', ...raw.theme },
115
154
  setup: raw.setup ?? [],
116
155
  steps,
117
156
  endCard,
157
+ intro,
158
+ frame,
159
+ follow,
118
160
  music,
119
161
  voice,
120
162
  sfx: pick('sfx') !== false,
package/src/init.mjs CHANGED
@@ -9,11 +9,11 @@ import { loginAdvice } from './auth.mjs';
9
9
  const q = (s) => JSON.stringify(String(s));
10
10
  const tgt = (t) => (typeof t === 'string' ? q(t) : `{ ${Object.entries(t).map(([k, v]) => `${k}: ${typeof v === 'string' ? q(v) : v}`).join(', ')} }`);
11
11
 
12
- export async function initStoryboard(url, { purpose = 'pitch', topic, file, storageState, viewport = { width: 1600, height: 900 } } = {}) {
12
+ export async function initStoryboard(url, { purpose = 'pitch', topic, file, storageState, ignoreHTTPSErrors = false, viewport = { width: 1600, height: 900 } } = {}) {
13
13
  if (!PURPOSES[purpose]) throw new Error(`purpose must be one of ${Object.keys(PURPOSES).join(', ')}`);
14
14
  file ??= defaultStoryboard(url, purpose, topic);
15
15
  if (fs.existsSync(file)) throw new Error(`${file} already exists — edit it, or choose another path`);
16
- const page = await inspect(url, { viewport, storageState, outDir: path.join(path.dirname(path.resolve(file)), '.storyshot', 'inspect') });
16
+ const page = await inspect(url, { viewport, storageState, ignoreHTTPSErrors, outDir: path.join(path.dirname(path.resolve(file)), '.storyshot', 'inspect') });
17
17
  if (page.login?.wall) {
18
18
  throw new Error(`${url} asks to log in (${page.login.reason})${storageState ? ' even with the saved session — it has probably expired, log in again' : ''}. ` +
19
19
  `${loginAdvice(url)} Then run init again with that session (MCP: storage_state, CLI: --storage).`);
@@ -38,9 +38,15 @@ name: ${name}
38
38
  url: ${page.url}
39
39
  purpose: ${purpose}
40
40
  out: ${name}.mp4
41
- ${storageState ? `storageState: ${path.relative(path.dirname(path.resolve(file)), path.resolve(storageState)).split(path.sep).join('/')} # saved login (never commit it)\n` : ''}${narrated ? 'voice: { provider: kokoro } # free, local, English. For the final: { provider: elevenlabs, voice: <voice id> } + ELEVENLABS_API_KEY' : '# voice: { provider: kokoro } # optional voiceover; add `say:` lines to steps'}
41
+ ${storageState ? `storageState: ${path.relative(path.dirname(path.resolve(file)), path.resolve(storageState)).split(path.sep).join('/')} # saved login (never commit it)\n` : ''}${ignoreHTTPSErrors ? 'ignoreHTTPSErrors: true # internal site with a self-signed certificate\n' : ''}${narrated ? 'voice: { provider: kokoro } # free, local, English. For the final: { provider: elevenlabs, voice: <voice id> } + ELEVENLABS_API_KEY' : '# voice: { provider: kokoro } # optional voiceover; add `say:` lines to steps'}
42
42
 
43
- setup: # runs before recording; clean the frame here${dismiss ? `\n - dismiss: ${tgt(dismiss.target)}` : '\n # - dismiss: { role: button, name: Accept cookies }'}
43
+ ${purpose === 'pitch' ? `intro: # title card before the recording (promos; optional for tutorials/lessons)
44
+ title: ${q(page.title.split(/[|—–-]/)[0].trim() || host)}
45
+ subtitle: TODO the one-line promise, with the **key words** in bold
46
+ ${PURPOSES[purpose]?.frame ? '# frame: false # the recording sits in a browser window on a backdrop; false = full frame\n' : ''}
47
+ ` : purpose === 'tutorial' || purpose === 'course' ? `# intro: { title: TODO, subtitle: TODO } # optional title card (e.g. "How to export a report")
48
+
49
+ ` : ''}setup: # runs before recording; clean the frame here${dismiss ? `\n - dismiss: ${tgt(dismiss.target)}` : '\n # - dismiss: { role: button, name: Accept cookies }'}
44
50
 
45
51
  steps:
46
52
  - caption: ${q(h1?.text?.slice(0, 50) || page.title || host)}${say('TODO one sentence on what this product does.')}${dur(2.5)}