trace-avatar-render 0.1.6 → 0.2.0

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.
@@ -1,86 +1,389 @@
1
- // src/camera.ts
2
- var ZOOM_KINDS = /* @__PURE__ */ new Set(["click", "dblclick", "type", "key", "hover"]);
3
- var smooth = (u) => u * u * (3 - 2 * u);
4
- function cameraKeys(actions, o) {
5
- const Z = o.zoom ?? 1.6;
6
- const lead = o.leadMs ?? 400;
7
- const ease = o.easeMs ?? 400;
8
- const join4 = o.joinMs ?? 2500;
9
- const hold = o.holdMs ?? 900;
10
- const minChange = o.minChangeMs ?? 1500;
11
- const sorted = actions.slice().sort((a, b) => a.t - b.t);
12
- const shots = [];
13
- let cur = [];
14
- for (const a of sorted) {
15
- if (!ZOOM_KINDS.has(a.kind)) {
16
- if (cur.length) shots.push(cur);
17
- cur = [];
18
- continue;
1
+ // src/cli.ts
2
+ import { existsSync as existsSync6, readFileSync as readFileSync9, writeFileSync as writeFileSync5 } from "fs";
3
+ import { apply as applySuggestions, suggest } from "trace-avatar/assist";
4
+
5
+ // src/ai.ts
6
+ import { resolve } from "path";
7
+ import { pathToFileURL } from "url";
8
+ import { gateway, openAiCompatible } from "trace-avatar/assist";
9
+ async function providerOf(spec, env = process.env, o = {}) {
10
+ const vision = o.vision ? { visionModel: o.vision } : {};
11
+ const g = /^gateway(?::([\w.-]+)(?:\/([^,]+))?((?:,[\w.-]+)*))?$/.exec(spec);
12
+ if (g) {
13
+ return gateway({
14
+ ...g[1] ? { provider: [g[1], ...(g[3] ?? "").split(",").filter(Boolean)] } : {},
15
+ ...g[2] ? { model: g[2] } : {},
16
+ ...vision,
17
+ url: env.AI_GATEWAY_URL,
18
+ key: env.AI_GATEWAY_KEY
19
+ });
20
+ }
21
+ const m = /^openai:(.+)$/.exec(spec);
22
+ if (m) {
23
+ if (!env.OPENAI_API_KEY && !env.OPENAI_BASE_URL) throw new Error("--ai openai:\u2026 needs OPENAI_API_KEY (and OPENAI_BASE_URL for another OpenAI-compatible server)");
24
+ return openAiCompatible({ baseUrl: env.OPENAI_BASE_URL || "https://api.openai.com/v1", ...env.OPENAI_API_KEY ? { key: env.OPENAI_API_KEY } : {}, model: m[1], ...vision });
25
+ }
26
+ if (/\.(m?js|cjs)$/.test(spec)) {
27
+ const mod = await import(pathToFileURL(resolve(spec)).href);
28
+ const fn = mod.default ?? mod.ai;
29
+ if (typeof fn !== "function") throw new Error(`${spec} must export a default function (task, input, schema, { instructions, images }) \u2192 JSON`);
30
+ return fn;
31
+ }
32
+ throw new Error(`--ai is gateway, gateway:<provider>[/<model>][,<provider>\u2026], openai:<model>, or a .js file (got "${spec}")`);
33
+ }
34
+ var QA_KINDS = ["error", "empty", "stalled", "personal-data", "wrong-page", "other"];
35
+ var QA_SCHEMA = {
36
+ type: "object",
37
+ required: ["flags"],
38
+ properties: { flags: { type: "array", items: { type: "object", required: ["frame", "kind", "note"], properties: {
39
+ frame: { type: "integer" },
40
+ kind: { enum: [...QA_KINDS] },
41
+ note: { type: "string", maxLength: 200 }
42
+ } } } }
43
+ };
44
+ var QA_INSTRUCTIONS = `You check frames of a GIF/video of an on-screen guide before it is published: a cursor with a name badge walks through a web app. For each numbered frame, flag only real problems a viewer would notice: an error message or toast ("error"), an empty state or blank page where content is expected ("empty"), a "Looking for \u2026" caption meaning the guide got stuck ("stalled"), personal data such as real email addresses, phone numbers, card or account numbers ("personal-data"), or a page that does not fit the step ("wrong-page"). The cursor, the name badge, highlights and captions are part of the guide, not problems. Reply with JSON only: {"flags":[{"frame":1,"kind":"error","note":"\u2026"}]}, an empty list when all is well.`;
45
+ async function runQa(ai, frames, context) {
46
+ if (!frames.length) return [];
47
+ const input = { title: context.title, steps: context.steps, frames: frames.map((f, k) => ({ frame: k + 1, at: Math.round(f.at / 100) / 10, shows: f.label })) };
48
+ const answer = await ai("qa", input, QA_SCHEMA, { instructions: QA_INSTRUCTIONS, images: frames.map((f, k) => ({ png: f.png, label: `Frame ${k + 1}: ${f.label}` })) });
49
+ const list = answer && typeof answer === "object" && Array.isArray(answer.flags) ? answer.flags : null;
50
+ if (!list) throw new Error('the QA answer has no "flags" list');
51
+ const out = [];
52
+ for (const item of list) {
53
+ const r = item;
54
+ if (!Number.isInteger(r?.frame) || r.frame < 1 || r.frame > frames.length) continue;
55
+ const kind = QA_KINDS.includes(r.kind) ? r.kind : "other";
56
+ const note = typeof r.note === "string" ? r.note.replace(/\s+/g, " ").trim().slice(0, 200) : "";
57
+ out.push({ at: frames[r.frame - 1].at, kind, note });
58
+ }
59
+ return out.sort((a, b) => a.at - b.at);
60
+ }
61
+
62
+ // src/narration.ts
63
+ import { preview } from "trace-avatar/assist";
64
+ function linesOf(steps, script) {
65
+ const out = /* @__PURE__ */ new Map();
66
+ steps.forEach((s, i) => {
67
+ if (s.say?.trim()) out.set(i, s.say.trim());
68
+ });
69
+ for (const l of script?.lines ?? []) {
70
+ const i = l.n - 1;
71
+ if (!Number.isInteger(i) || i < 0 || i >= steps.length) throw new Error(`the script has a line for step ${l.n}, but the trace has ${steps.length} steps`);
72
+ if (l.text.trim()) out.set(i, l.text.trim());
73
+ else out.delete(i);
74
+ }
75
+ return out;
76
+ }
77
+ function parseScript(json) {
78
+ const lines = json?.lines;
79
+ if (!Array.isArray(lines) || lines.some((l) => !l || typeof l.n !== "number" || typeof l.text !== "string")) {
80
+ throw new Error('a narration script is { "lines": [{ "n": 1, "text": "\u2026" }] }');
81
+ }
82
+ return { lines: lines.map((l) => ({ n: l.n, text: l.text })) };
83
+ }
84
+ function planNarration(acts, lines, endMs, o = {}) {
85
+ const first = o.firstMs ?? 300;
86
+ const after = o.afterActMs ?? 200;
87
+ const before = o.beforeActMs ?? 250;
88
+ const gap = o.gapMs ?? 150;
89
+ const maxHold = o.maxHoldMs ?? 8e3;
90
+ const plan = { lines: [], holds: [], long: [] };
91
+ let extra = 0;
92
+ let prevCut = null;
93
+ let prevEnd = -Infinity;
94
+ for (const a of acts.slice().sort((x, y) => x.t - y.t)) {
95
+ const line = lines.get(a.index);
96
+ const prevHeld = prevCut === null ? null : prevCut + extra;
97
+ if (line && line.ms > 0) {
98
+ const start = Math.max(prevHeld === null ? first : prevHeld + after, prevEnd + gap);
99
+ const end = start + line.ms;
100
+ const need = Math.ceil(end - (a.t + extra - before));
101
+ if (need > 0) {
102
+ plan.holds.push({ at: Math.max(0, a.t - before, prevCut ?? 0), ms: need });
103
+ extra += need;
104
+ if (need > maxHold) plan.long.push({ index: a.index, ms: need });
105
+ }
106
+ plan.lines.push({ index: a.index, text: line.text, start: Math.round(start), ms: Math.round(line.ms) });
107
+ prevEnd = end;
19
108
  }
20
- const last = cur[cur.length - 1];
21
- if (last && a.t - last.t > join4) {
22
- shots.push(cur);
23
- cur = [];
109
+ prevCut = a.t;
110
+ }
111
+ const endHoldMs = Math.max(0, Math.ceil(prevEnd + (o.tailMs ?? 400) - (endMs + extra)));
112
+ if (endHoldMs > 0) plan.holds.push({ at: endMs, ms: endHoldMs });
113
+ return { ...plan, endHoldMs };
114
+ }
115
+ function narrationText(lines, offsetMs = 0) {
116
+ const at = (ms) => {
117
+ const s = Math.round((ms + offsetMs) / 1e3);
118
+ return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
119
+ };
120
+ return lines.map((l) => `[${at(l.start)}] ${l.text}`).join("\n") + (lines.length ? "\n" : "");
121
+ }
122
+ var SCRIPT_SCHEMA = { type: "object", properties: { lines: { type: "array", items: { type: "object", properties: { n: { type: "integer" }, text: { type: "string" } }, required: ["n", "text"] } } }, required: ["lines"] };
123
+ var SCRIPT_INSTRUCTIONS = `You write the voice-over for a short screen guide. For each step, write one line to be spoken while the cursor moves to it: a full, natural sentence in plain English, second person ("Now click Save"), at most 25 words. Spell out symbols and numbers as spoken ("twenty percent", not "20%"). Keep the meaning of the step's caption when it has one. Skip steps that need no words (return no line for them). Never invent data values. Answer with JSON: { "lines": [{ "n": <step number>, "text": "\u2026" }] }.`;
124
+ async function suggestScript(ai, trace) {
125
+ const p = preview("captions", trace);
126
+ const answer = await ai("narration", p.input, SCRIPT_SCHEMA, { instructions: SCRIPT_INSTRUCTIONS });
127
+ const steps = trace.steps?.length ?? 0;
128
+ const lines = [];
129
+ const dropped = [];
130
+ const seen = /* @__PURE__ */ new Set();
131
+ for (const l of answer?.lines ?? []) {
132
+ const n = l?.n;
133
+ const text = typeof l?.text === "string" ? l.text.trim() : "";
134
+ if (typeof n !== "number" || !Number.isInteger(n) || n < 1 || n > steps) dropped.push({ n, why: "no such step" });
135
+ else if (seen.has(n)) dropped.push({ n, why: "a second line for the step" });
136
+ else if (!text) dropped.push({ n, why: "empty" });
137
+ else if (text.length > 300) dropped.push({ n, why: "longer than 300 characters" });
138
+ else {
139
+ seen.add(n);
140
+ lines.push({ n, text });
24
141
  }
25
- cur.push(a);
26
142
  }
27
- if (cur.length) shots.push(cur);
28
- const merged = [];
29
- for (const s of shots) {
30
- const prev = merged[merged.length - 1];
31
- if (prev) {
32
- const outAt = prev[prev.length - 1].t + hold;
33
- const inAt = s[0].t - lead - ease;
34
- const scrollBetween = sorted.some((a) => !ZOOM_KINDS.has(a.kind) && a.t > prev[prev.length - 1].t && a.t < s[0].t);
35
- if (!scrollBetween && inAt - (outAt + ease) < minChange) {
36
- prev.push(...s);
37
- continue;
143
+ return { script: { lines: lines.sort((a, b) => a.n - b.n) }, dropped };
144
+ }
145
+
146
+ // src/voice.ts
147
+ import { spawnSync } from "child_process";
148
+ import { createHash } from "crypto";
149
+ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
150
+ import { tmpdir } from "os";
151
+ import { join, resolve as resolve2 } from "path";
152
+ import { pathToFileURL as pathToFileURL2 } from "url";
153
+
154
+ // src/audio.ts
155
+ var TRACK_RATE = 48e3;
156
+ function toWav(pcm, sampleRate) {
157
+ const data = pcm.length * 2;
158
+ const buf = new ArrayBuffer(44 + data);
159
+ const v = new DataView(buf);
160
+ const str = (at, s) => {
161
+ for (let i = 0; i < s.length; i += 1) v.setUint8(at + i, s.charCodeAt(i));
162
+ };
163
+ str(0, "RIFF");
164
+ v.setUint32(4, 36 + data, true);
165
+ str(8, "WAVE");
166
+ str(12, "fmt ");
167
+ v.setUint32(16, 16, true);
168
+ v.setUint16(20, 1, true);
169
+ v.setUint16(22, 1, true);
170
+ v.setUint32(24, sampleRate, true);
171
+ v.setUint32(28, sampleRate * 2, true);
172
+ v.setUint16(32, 2, true);
173
+ v.setUint16(34, 16, true);
174
+ str(36, "data");
175
+ v.setUint32(40, data, true);
176
+ for (let i = 0; i < pcm.length; i += 1) v.setInt16(44 + i * 2, pcm[i], true);
177
+ return new Uint8Array(buf);
178
+ }
179
+ function fromWav(bytes) {
180
+ const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
181
+ const tag = (at2) => String.fromCharCode(...bytes.subarray(at2, at2 + 4));
182
+ if (bytes.length < 12 || tag(0) !== "RIFF" || tag(8) !== "WAVE") throw new Error("not a WAV file");
183
+ let at = 12;
184
+ let rate = 0;
185
+ let channels = 1;
186
+ while (at + 8 <= bytes.length) {
187
+ const id = tag(at);
188
+ const size = v.getUint32(at + 4, true);
189
+ if (id === "fmt ") {
190
+ const format = v.getUint16(at + 8, true);
191
+ channels = v.getUint16(at + 10, true);
192
+ rate = v.getUint32(at + 12, true);
193
+ const bits = v.getUint16(at + 22, true);
194
+ if (format !== 1 && format !== 65534 || bits !== 16) throw new Error(`only 16-bit PCM WAV is read (format ${format}, ${bits} bits)`);
195
+ } else if (id === "data") {
196
+ if (!rate) throw new Error("a WAV data chunk before its format");
197
+ const len = size === 0 || size === 4294967295 || at + 8 + size > bytes.length ? bytes.length - at - 8 : size;
198
+ const n = Math.floor(len / 2 / channels);
199
+ const pcm = new Int16Array(n);
200
+ for (let i = 0; i < n; i += 1) {
201
+ let sum = 0;
202
+ for (let c = 0; c < channels; c += 1) sum += v.getInt16(at + 8 + (i * channels + c) * 2, true);
203
+ pcm[i] = Math.round(sum / channels);
38
204
  }
205
+ return { pcm, sampleRate: rate };
39
206
  }
40
- merged.push(s.slice());
207
+ at += 8 + size + size % 2;
41
208
  }
42
- const keys = [];
43
- for (const s of merged) {
44
- const first = s[0];
45
- const inEnd = Math.max(first.t - lead, (keys[keys.length - 1]?.t ?? -Infinity) + ease);
46
- keys.push({ t: inEnd - ease, z: 1, x: first.x, y: first.y }, { t: inEnd, z: Z, x: first.x, y: first.y });
47
- for (let k = 1; k < s.length; k += 1) {
48
- const a = s[k];
49
- const prev = keys[keys.length - 1];
50
- const arrive = Math.max(a.t - lead, prev.t + ease);
51
- keys.push({ t: arrive - ease, z: Z, x: prev.x, y: prev.y }, { t: arrive, z: Z, x: a.x, y: a.y });
209
+ throw new Error("a WAV file without data");
210
+ }
211
+ function fromS16le(bytes) {
212
+ const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
213
+ const out = new Int16Array(Math.floor(bytes.length / 2));
214
+ for (let i = 0; i < out.length; i += 1) out[i] = v.getInt16(i * 2, true);
215
+ return out;
216
+ }
217
+ function resample(pcm, from, to) {
218
+ if (from === to || !pcm.length) return pcm.slice();
219
+ const n = Math.max(1, Math.round(pcm.length * to / from));
220
+ const out = new Int16Array(n);
221
+ const step = from / to;
222
+ for (let i = 0; i < n; i += 1) {
223
+ const x = i * step;
224
+ const a = Math.min(pcm.length - 1, Math.floor(x));
225
+ const b = Math.min(pcm.length - 1, a + 1);
226
+ out[i] = Math.round(pcm[a] + (pcm[b] - pcm[a]) * (x - a));
227
+ }
228
+ return out;
229
+ }
230
+ function trimSilence(p, o = {}) {
231
+ const level = o.level ?? 400;
232
+ const pad = Math.round((o.padMs ?? 40) * p.sampleRate / 1e3);
233
+ let a = 0;
234
+ while (a < p.pcm.length && Math.abs(p.pcm[a]) < level) a += 1;
235
+ if (a === p.pcm.length) return { pcm: new Int16Array(0), sampleRate: p.sampleRate };
236
+ let b = p.pcm.length - 1;
237
+ while (b > a && Math.abs(p.pcm[b]) < level) b -= 1;
238
+ return { pcm: p.pcm.slice(Math.max(0, a - pad), Math.min(p.pcm.length, b + 1 + pad)), sampleRate: p.sampleRate };
239
+ }
240
+ var msOf = (p) => p.pcm.length * 1e3 / p.sampleRate;
241
+ function mix(lines, totalMs, o = {}) {
242
+ const out = new Float64Array(Math.max(0, Math.round(totalMs * TRACK_RATE / 1e3)));
243
+ const fade = Math.round((o.fadeMs ?? 15) * TRACK_RATE / 1e3);
244
+ for (const l of lines) {
245
+ const s = resample(l.audio.pcm, l.audio.sampleRate, TRACK_RATE);
246
+ const at = Math.round(l.start * TRACK_RATE / 1e3);
247
+ const f = Math.min(fade, Math.floor(s.length / 2));
248
+ for (let i = 0; i < s.length; i += 1) {
249
+ const k = at + i;
250
+ if (k < 0) continue;
251
+ if (k >= out.length) break;
252
+ const g = f ? Math.min(1, i / f, (s.length - 1 - i) / f) : 1;
253
+ out[k] += s[i] * g;
52
254
  }
53
- const last = keys[keys.length - 1];
54
- const out = Math.max(s[s.length - 1].t + hold, last.t);
55
- keys.push({ t: out, z: Z, x: last.x, y: last.y }, { t: out + ease, z: 1, x: last.x, y: last.y });
56
255
  }
57
- return keys;
256
+ const pcm = new Int16Array(out.length);
257
+ for (let i = 0; i < out.length; i += 1) pcm[i] = Math.max(-32768, Math.min(32767, Math.round(out[i])));
258
+ return pcm;
58
259
  }
59
- function cameraPath(actions, o) {
60
- const keys = cameraKeys(actions, o);
61
- const full = { x: 0, y: 0, w: o.width, h: o.height };
62
- const rectOf = (z, x, y) => {
63
- if (z <= 1.0001) return full;
64
- const w = o.width / z;
65
- const h = o.height / z;
66
- return { x: Math.min(Math.max(0, x - w / 2), o.width - w), y: Math.min(Math.max(0, y - h / 2), o.height - h), w, h };
260
+
261
+ // src/voice.ts
262
+ var GEMINI_TTS = { model: "gemini-2.5-flash-preview-tts", voice: "Kore" };
263
+ var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
264
+ async function post(f, url, headers, body) {
265
+ for (let n = 1; ; n += 1) {
266
+ let res = null;
267
+ try {
268
+ res = await f(url, { method: "POST", headers: { "content-type": "application/json", ...headers }, body: JSON.stringify(body) });
269
+ } catch (e) {
270
+ if (n >= 3) throw new Error(`could not reach the voice (${e.message})`);
271
+ }
272
+ if (res?.ok) return res;
273
+ if (res) {
274
+ const text = await res.text();
275
+ let gw = null;
276
+ try {
277
+ const j = JSON.parse(text);
278
+ if (j?.error?.source === "ai-interface") gw = j.error;
279
+ } catch {
280
+ }
281
+ if (gw) throw new Error(`the AI gateway refused the voice call: ${gw.message}`);
282
+ if (!(res.status === 429 || res.status >= 500) || n >= 3) throw new Error(`the voice call failed (${res.status}): ${text.slice(0, 300)}`);
283
+ }
284
+ await sleep(Math.min(400 * 2 ** (n - 1) * (0.5 + Math.random() / 2), 4e3));
285
+ }
286
+ }
287
+ function geminiVoice(o) {
288
+ const model = o.model ?? GEMINI_TTS.model;
289
+ return async (text) => {
290
+ const res = await post(
291
+ o.fetch ?? fetch,
292
+ `${o.url.replace(/\/+$/, "")}/models/${model}:generateContent`,
293
+ { ...o.bearer ? { authorization: `Bearer ${o.key}` } : { "x-goog-api-key": o.key }, ...o.headers },
294
+ {
295
+ contents: [{ role: "user", parts: [{ text }] }],
296
+ generationConfig: { responseModalities: ["AUDIO"], speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: o.voice ?? GEMINI_TTS.voice } } } }
297
+ }
298
+ );
299
+ const json = await res.json();
300
+ const part = json.candidates?.[0]?.content?.parts?.find((p) => p.inlineData?.data || p.inline_data?.data);
301
+ const data = part?.inlineData?.data ?? part?.inline_data?.data;
302
+ if (!data) throw new Error(`${model} answered without audio`);
303
+ const mime = part?.inlineData?.mimeType ?? part?.inline_data?.mime_type ?? "";
304
+ const rate = Number(/rate=(\d+)/.exec(mime)?.[1] ?? 24e3);
305
+ return { pcm: fromS16le(new Uint8Array(Buffer.from(data, "base64"))), sampleRate: rate };
67
306
  };
68
- return (t) => {
69
- if (!keys.length || t <= keys[0].t || t >= keys[keys.length - 1].t) return full;
70
- let k = 0;
71
- while (k < keys.length - 2 && keys[k + 1].t <= t) k += 1;
72
- const a = keys[k];
73
- const b = keys[k + 1];
74
- const u = b.t > a.t ? smooth(Math.min(1, Math.max(0, (t - a.t) / (b.t - a.t)))) : 1;
75
- const za = 1 / a.z;
76
- const zb = 1 / b.z;
77
- const z = 1 / (za + (zb - za) * u);
78
- return rectOf(z, a.x + (b.x - a.x) * u, a.y + (b.y - a.y) * u);
307
+ }
308
+ function openAiVoice(o) {
309
+ return async (text) => {
310
+ const res = await post(
311
+ o.fetch ?? fetch,
312
+ `${o.baseUrl.replace(/\/+$/, "")}/audio/speech`,
313
+ o.key ? { authorization: `Bearer ${o.key}` } : {},
314
+ { model: o.model, voice: o.voice ?? "alloy", input: text, response_format: "pcm" }
315
+ );
316
+ return { pcm: fromS16le(new Uint8Array(await res.arrayBuffer())), sampleRate: 24e3 };
79
317
  };
80
318
  }
319
+ function sayVoice(o = {}) {
320
+ return async (text) => {
321
+ const dir = mkdtempSync(join(tmpdir(), "tar-say-"));
322
+ try {
323
+ const file = join(dir, "line.wav");
324
+ const r = spawnSync("say", [...o.voice ? ["-v", o.voice] : [], "-o", file, "--file-format=WAVE", "--data-format=LEI16@24000", text], { encoding: "utf8" });
325
+ if (r.error || r.status !== 0) throw new Error(`say failed${r.error ? ` (${r.error.message})` : `: ${r.stderr}`}; --voice say needs macOS`);
326
+ return fromWav(new Uint8Array(readFileSync(file)));
327
+ } finally {
328
+ rmSync(dir, { recursive: true, force: true });
329
+ }
330
+ };
331
+ }
332
+ function cached(voice, id, dir) {
333
+ const v = (async (text) => {
334
+ const file = join(dir, `${createHash("sha256").update(`${id}
335
+ ${text}`).digest("hex").slice(0, 32)}.wav`);
336
+ if (existsSync(file)) {
337
+ v.hits += 1;
338
+ return fromWav(new Uint8Array(readFileSync(file)));
339
+ }
340
+ const p = await voice(text);
341
+ v.misses += 1;
342
+ mkdirSync(dir, { recursive: true });
343
+ writeFileSync(file, toWav(p.pcm, p.sampleRate));
344
+ return p;
345
+ });
346
+ v.hits = 0;
347
+ v.misses = 0;
348
+ return v;
349
+ }
350
+ async function voiceOf(spec, env = process.env, o = {}) {
351
+ const cacheDir = o.cacheDir === void 0 ? resolve2(".trace-avatar-cache", "voice") : o.cacheDir;
352
+ const wrap = (v) => cacheDir ? cached(v, spec, cacheDir) : v;
353
+ const g = /^gateway(?::gemini(?:\/([^:]+))?(?::(.+))?)?$/.exec(spec);
354
+ if (g) {
355
+ if (!env.AI_GATEWAY_URL || !env.AI_GATEWAY_KEY) throw new Error("--voice gateway needs AI_GATEWAY_URL and AI_GATEWAY_KEY");
356
+ return wrap(geminiVoice({
357
+ url: `${env.AI_GATEWAY_URL.replace(/\/+$/, "")}/v1/gemini`,
358
+ key: env.AI_GATEWAY_KEY,
359
+ bearer: true,
360
+ ...g[1] ? { model: g[1] } : {},
361
+ ...g[2] ? { voice: g[2] } : {},
362
+ headers: { "x-ai-feature": "trace-avatar-voice" },
363
+ ...o.fetch ? { fetch: o.fetch } : {}
364
+ }));
365
+ }
366
+ const m = /^openai:([^:]+)(?::(.+))?$/.exec(spec);
367
+ if (m) {
368
+ if (!env.OPENAI_API_KEY && !env.OPENAI_BASE_URL) throw new Error("--voice openai:\u2026 needs OPENAI_API_KEY (and OPENAI_BASE_URL for another OpenAI-compatible server)");
369
+ return wrap(openAiVoice({ baseUrl: env.OPENAI_BASE_URL || "https://api.openai.com/v1", ...env.OPENAI_API_KEY ? { key: env.OPENAI_API_KEY } : {}, model: m[1], ...m[2] ? { voice: m[2] } : {}, ...o.fetch ? { fetch: o.fetch } : {} }));
370
+ }
371
+ const s = /^say(?::(.+))?$/.exec(spec);
372
+ if (s) return wrap(sayVoice(s[1] ? { voice: s[1] } : {}));
373
+ if (/\.(m?js|cjs)$/.test(spec)) {
374
+ const mod = await import(pathToFileURL2(resolve2(spec)).href);
375
+ const fn = mod.default ?? mod.voice;
376
+ if (typeof fn !== "function") throw new Error(`${spec} must export a default function (text) \u2192 { pcm: Int16Array, sampleRate }`);
377
+ return wrap(fn);
378
+ }
379
+ throw new Error(`--voice is gateway[:gemini[/<model>][:<voice>]], openai:<model>[:<voice>], say[:<voice>], or a .js file (got "${spec}")`);
380
+ }
381
+
382
+ // src/cli.ts
383
+ import { parseArgs } from "util";
81
384
 
82
385
  // src/capture.ts
83
- import { readFileSync } from "fs";
386
+ import { readFileSync as readFileSync2 } from "fs";
84
387
  import { chromium } from "playwright";
85
388
  var RenderError = class extends Error {
86
389
  constructor(message, screenshot) {
@@ -176,7 +479,7 @@ function bootstrap(cfg) {
176
479
  if (document.readyState === "loading") addEventListener("DOMContentLoaded", go, { once: true });
177
480
  else go();
178
481
  }
179
- var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
482
+ var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
180
483
  async function capture(o) {
181
484
  const timeout = o.timeoutMs ?? 12e4;
182
485
  const cfg = {
@@ -192,7 +495,7 @@ async function capture(o) {
192
495
  ...o.security !== void 0 ? { security: o.security } : {},
193
496
  ...o.values ? { values: o.values } : {}
194
497
  };
195
- const content = `${readFileSync(o.playerFile, "utf8")}
498
+ const content = `${readFileSync2(o.playerFile, "utf8")}
196
499
  ;window.__taPlayer = TraceAvatar;
197
500
  (${bootstrap.toString()})(${JSON.stringify(cfg)});`;
198
501
  const browser = await chromium.launch({ headless: o.headless !== false });
@@ -250,7 +553,7 @@ async function capture(o) {
250
553
  if (first.type !== "ready") throw new RenderError(`the guide could not start: ${first.message ?? first.type}`);
251
554
  capturing = true;
252
555
  await startCast();
253
- await sleep(o.leadMs ?? 500);
556
+ await sleep2(o.leadMs ?? 500);
254
557
  const playAt = Date.now();
255
558
  await page.evaluate(() => window.__taPlay());
256
559
  const done = await until(() => events.find((e) => e.type === "end" || e.type === "stalled") ?? failure(), "the guide to end");
@@ -264,8 +567,8 @@ async function capture(o) {
264
567
  err.stall = { ...stall, ...data !== void 0 ? { data } : {} };
265
568
  throw err;
266
569
  }
267
- await sleep(3e3);
268
- } else await sleep(o.holdEndMs ?? 1500);
570
+ await sleep2(3e3);
571
+ } else await sleep2(o.holdEndMs ?? 1500);
269
572
  const stopAt = Date.now();
270
573
  capturing = false;
271
574
  await cdp.send("Page.stopScreencast").catch(() => {
@@ -279,13 +582,101 @@ async function capture(o) {
279
582
  await browser.close();
280
583
  }
281
584
  }
282
- async function findPlayer(explicit, env = process.env) {
283
- if (explicit) return explicit;
284
- if (env.TRACE_AVATAR_PLAYER) return env.TRACE_AVATAR_PLAYER;
285
- const { createRequire } = await import("module");
286
- const { dirname: dirname4, join: join4 } = await import("path");
287
- const req = createRequire(import.meta.url);
288
- return join4(dirname4(req.resolve("trace-avatar/package.json")), "dist", "trace-perform.min.js");
585
+ async function findPlayer(explicit, env = process.env) {
586
+ if (explicit) return explicit;
587
+ if (env.TRACE_AVATAR_PLAYER) return env.TRACE_AVATAR_PLAYER;
588
+ const { createRequire: createRequire2 } = await import("module");
589
+ const { dirname: dirname6, join: join5 } = await import("path");
590
+ const req = createRequire2(import.meta.url);
591
+ return join5(dirname6(req.resolve("trace-avatar/package.json")), "dist", "trace-perform.min.js");
592
+ }
593
+
594
+ // src/render.ts
595
+ import { readFileSync as readFileSync6, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, mkdtempSync as mkdtempSync2, rmSync as rmSync2 } from "fs";
596
+ import { tmpdir as tmpdir2 } from "os";
597
+ import { dirname as dirname3, extname as extname2, join as join3 } from "path";
598
+ import { chromium as chromium2 } from "playwright";
599
+ import { PNG as PNG2 } from "pngjs";
600
+
601
+ // src/camera.ts
602
+ var ZOOM_KINDS = /* @__PURE__ */ new Set(["click", "dblclick", "type", "key", "hover"]);
603
+ var smooth = (u) => u * u * (3 - 2 * u);
604
+ function cameraKeys(actions, o) {
605
+ const Z = o.zoom ?? 1.6;
606
+ const lead = o.leadMs ?? 400;
607
+ const ease = o.easeMs ?? 400;
608
+ const join5 = o.joinMs ?? 2500;
609
+ const hold = o.holdMs ?? 900;
610
+ const minChange = o.minChangeMs ?? 1500;
611
+ const sorted = actions.slice().sort((a, b) => a.t - b.t);
612
+ const shots = [];
613
+ let cur = [];
614
+ for (const a of sorted) {
615
+ if (!ZOOM_KINDS.has(a.kind)) {
616
+ if (cur.length) shots.push(cur);
617
+ cur = [];
618
+ continue;
619
+ }
620
+ const last = cur[cur.length - 1];
621
+ if (last && a.t - last.t > join5) {
622
+ shots.push(cur);
623
+ cur = [];
624
+ }
625
+ cur.push(a);
626
+ }
627
+ if (cur.length) shots.push(cur);
628
+ const merged = [];
629
+ for (const s of shots) {
630
+ const prev = merged[merged.length - 1];
631
+ if (prev) {
632
+ const outAt = prev[prev.length - 1].t + hold;
633
+ const inAt = s[0].t - lead - ease;
634
+ const scrollBetween = sorted.some((a) => !ZOOM_KINDS.has(a.kind) && a.t > prev[prev.length - 1].t && a.t < s[0].t);
635
+ if (!scrollBetween && inAt - (outAt + ease) < minChange) {
636
+ prev.push(...s);
637
+ continue;
638
+ }
639
+ }
640
+ merged.push(s.slice());
641
+ }
642
+ const keys = [];
643
+ for (const s of merged) {
644
+ const first = s[0];
645
+ const inEnd = Math.max(first.t - lead, (keys[keys.length - 1]?.t ?? -Infinity) + ease);
646
+ keys.push({ t: inEnd - ease, z: 1, x: first.x, y: first.y }, { t: inEnd, z: Z, x: first.x, y: first.y });
647
+ for (let k = 1; k < s.length; k += 1) {
648
+ const a = s[k];
649
+ const prev = keys[keys.length - 1];
650
+ const arrive = Math.max(a.t - lead, prev.t + ease);
651
+ keys.push({ t: arrive - ease, z: Z, x: prev.x, y: prev.y }, { t: arrive, z: Z, x: a.x, y: a.y });
652
+ }
653
+ const last = keys[keys.length - 1];
654
+ const out = Math.max(s[s.length - 1].t + hold, last.t);
655
+ keys.push({ t: out, z: Z, x: last.x, y: last.y }, { t: out + ease, z: 1, x: last.x, y: last.y });
656
+ }
657
+ return keys;
658
+ }
659
+ function cameraPath(actions, o) {
660
+ const keys = cameraKeys(actions, o);
661
+ const full = { x: 0, y: 0, w: o.width, h: o.height };
662
+ const rectOf = (z, x, y) => {
663
+ if (z <= 1.0001) return full;
664
+ const w = o.width / z;
665
+ const h = o.height / z;
666
+ return { x: Math.min(Math.max(0, x - w / 2), o.width - w), y: Math.min(Math.max(0, y - h / 2), o.height - h), w, h };
667
+ };
668
+ return (t) => {
669
+ if (!keys.length || t <= keys[0].t || t >= keys[keys.length - 1].t) return full;
670
+ let k = 0;
671
+ while (k < keys.length - 2 && keys[k + 1].t <= t) k += 1;
672
+ const a = keys[k];
673
+ const b = keys[k + 1];
674
+ const u = b.t > a.t ? smooth(Math.min(1, Math.max(0, (t - a.t) / (b.t - a.t)))) : 1;
675
+ const za = 1 / a.z;
676
+ const zb = 1 / b.z;
677
+ const z = 1 / (za + (zb - za) * u);
678
+ return rectOf(z, a.x + (b.x - a.x) * u, a.y + (b.y - a.y) * u);
679
+ };
289
680
  }
290
681
 
291
682
  // src/compose.ts
@@ -467,7 +858,7 @@ function same(a, b) {
467
858
  }
468
859
 
469
860
  // src/layers.ts
470
- import { readFileSync as readFileSync2 } from "fs";
861
+ import { readFileSync as readFileSync3 } from "fs";
471
862
  import { extname } from "path";
472
863
  import { PNG } from "pngjs";
473
864
  var MIME = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".svg": "image/svg+xml", ".webp": "image/webp", ".gif": "image/gif" };
@@ -475,7 +866,7 @@ function dataUri(file) {
475
866
  if (/^data:/.test(file)) return file;
476
867
  const type = MIME[extname(file).toLowerCase()];
477
868
  if (!type) throw new Error(`a logo is a PNG, JPEG, SVG, WebP or GIF file (got ${file})`);
478
- return `data:${type};base64,${readFileSync2(file).toString("base64")}`;
869
+ return `data:${type};base64,${readFileSync3(file).toString("base64")}`;
479
870
  }
480
871
  var DEFAULT_BACKGROUND = "linear-gradient(135deg, #dfe7fb 0%, #eef0f6 50%, #f6e9f1 100%)";
481
872
  var esc = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
@@ -643,8 +1034,8 @@ function onCanvas(srcW, srcH, width, frame, canvas) {
643
1034
  }
644
1035
 
645
1036
  // src/brand.ts
646
- import { readFileSync as readFileSync3 } from "fs";
647
- import { dirname, isAbsolute, resolve } from "path";
1037
+ import { readFileSync as readFileSync4 } from "fs";
1038
+ import { dirname, isAbsolute, resolve as resolve3 } from "path";
648
1039
  var CANVASES = {
649
1040
  "9:16": { width: 1080, height: 1920 },
650
1041
  "4:5": { width: 1080, height: 1350 },
@@ -676,7 +1067,7 @@ function brandOf(json, dir = ".") {
676
1067
  const problems = [];
677
1068
  for (const k of Object.keys(b)) if (!KEYS.includes(k)) problems.push(`unknown key ${k}`);
678
1069
  const out = {};
679
- const at = (p) => p && !isAbsolute(p) && !/^data:/.test(p) ? resolve(dir, p) : p;
1070
+ const at = (p) => p && !isAbsolute(p) && !/^data:/.test(p) ? resolve3(dir, p) : p;
680
1071
  const card = (v, name) => {
681
1072
  if (typeof v === "boolean" || typeof v === "string") return v;
682
1073
  if (v && typeof v === "object" && typeof v.title === "string") {
@@ -736,24 +1127,39 @@ function brandOf(json, dir = ".") {
736
1127
  function brandFile(file) {
737
1128
  let json;
738
1129
  try {
739
- json = JSON.parse(readFileSync3(file, "utf8"));
1130
+ json = JSON.parse(readFileSync4(file, "utf8"));
740
1131
  } catch (e) {
741
1132
  throw new Error(`brand ${file}: ${e.message}`);
742
1133
  }
743
- return brandOf(json, dirname(resolve(file)));
1134
+ return brandOf(json, dirname(resolve3(file)));
744
1135
  }
745
1136
 
746
1137
  // src/mp4.ts
747
- import { spawn, spawnSync } from "child_process";
748
- function findFfmpeg(env = process.env) {
749
- const bin = env.FFMPEG || "ffmpeg";
1138
+ import { spawn, spawnSync as spawnSync2 } from "child_process";
1139
+ import { existsSync as existsSync2 } from "fs";
1140
+ import { createRequire } from "module";
1141
+ var works = (bin) => {
1142
+ try {
1143
+ return spawnSync2(bin, ["-version"], { stdio: "ignore" }).status === 0;
1144
+ } catch {
1145
+ return false;
1146
+ }
1147
+ };
1148
+ function bundled() {
750
1149
  try {
751
- const r = spawnSync(bin, ["-version"], { stdio: "ignore" });
752
- return r.status === 0 ? bin : null;
1150
+ const p = createRequire(import.meta.url)("ffmpeg-static");
1151
+ return p && existsSync2(p) ? p : null;
753
1152
  } catch {
754
1153
  return null;
755
1154
  }
756
1155
  }
1156
+ function findFfmpeg(env = process.env, o = {}) {
1157
+ if (env.FFMPEG) return works(env.FFMPEG) ? env.FFMPEG : null;
1158
+ if (works("ffmpeg")) return "ffmpeg";
1159
+ const b = (o.bundled ?? bundled)();
1160
+ return b && works(b) ? b : null;
1161
+ }
1162
+ var FFMPEG_MISSING = "MP4 needs ffmpeg: install ffmpeg-static (npm install ffmpeg-static), install ffmpeg (brew install ffmpeg, apt install ffmpeg), or set FFMPEG to its path. GIF works without it.";
757
1163
  function mp4Args(file, fps, size, audio) {
758
1164
  return [
759
1165
  "-y",
@@ -788,16 +1194,16 @@ function mp4Args(file, fps, size, audio) {
788
1194
  }
789
1195
  async function encodeMp4(frames, o) {
790
1196
  const bin = o.ffmpeg ?? findFfmpeg();
791
- if (!bin) throw new Error("MP4 needs ffmpeg: install it (brew install ffmpeg, apt install ffmpeg) or set FFMPEG to its path. GIF works without it.");
1197
+ if (!bin) throw new Error(FFMPEG_MISSING);
792
1198
  if (o.width % 2 || o.height % 2) throw new Error(`MP4 needs an even size (got ${o.width}\xD7${o.height})`);
793
1199
  const p = spawn(bin, mp4Args(o.file, o.fps, o, o.audio), { stdio: ["pipe", "ignore", "pipe"] });
794
1200
  let err = "";
795
1201
  p.stderr.on("data", (d) => {
796
1202
  err += String(d);
797
1203
  });
798
- const done = new Promise((resolve4, reject) => {
1204
+ const done = new Promise((resolve6, reject) => {
799
1205
  p.on("error", reject);
800
- p.on("close", (code) => code === 0 ? resolve4() : reject(new Error(`ffmpeg exited with ${code}: ${err.trim()}`)));
1206
+ p.on("close", (code) => code === 0 ? resolve6() : reject(new Error(`ffmpeg exited with ${code}: ${err.trim()}`)));
801
1207
  });
802
1208
  p.stdin.on("error", () => {
803
1209
  });
@@ -998,228 +1404,37 @@ function stepCues(events, segs, endMs, o = {}) {
998
1404
  return cues.filter((c) => c.end > c.start);
999
1405
  }
1000
1406
  function pageAt(events) {
1001
- const marks = events.filter((e) => e.url && e.type !== "unload").slice().sort((a, b) => a.t - b.t);
1002
- return (src) => {
1003
- let url = marks[0]?.url ?? "/";
1004
- for (const m of marks) {
1005
- if (m.t <= src) url = m.url;
1006
- else break;
1007
- }
1008
- return url;
1009
- };
1010
- }
1011
- function cueAt(cues, t, fadeMs = 150) {
1012
- for (const c of cues) {
1013
- if (t >= c.start && t < c.end) {
1014
- const alpha = Math.min(1, (t - c.start) / fadeMs, (c.end - t) / fadeMs);
1015
- return { cue: c, alpha: Math.max(0, alpha) };
1016
- }
1017
- }
1018
- return null;
1019
- }
1020
-
1021
- // src/audio.ts
1022
- var TRACK_RATE = 48e3;
1023
- function toWav(pcm, sampleRate) {
1024
- const data = pcm.length * 2;
1025
- const buf = new ArrayBuffer(44 + data);
1026
- const v = new DataView(buf);
1027
- const str = (at, s) => {
1028
- for (let i = 0; i < s.length; i += 1) v.setUint8(at + i, s.charCodeAt(i));
1029
- };
1030
- str(0, "RIFF");
1031
- v.setUint32(4, 36 + data, true);
1032
- str(8, "WAVE");
1033
- str(12, "fmt ");
1034
- v.setUint32(16, 16, true);
1035
- v.setUint16(20, 1, true);
1036
- v.setUint16(22, 1, true);
1037
- v.setUint32(24, sampleRate, true);
1038
- v.setUint32(28, sampleRate * 2, true);
1039
- v.setUint16(32, 2, true);
1040
- v.setUint16(34, 16, true);
1041
- str(36, "data");
1042
- v.setUint32(40, data, true);
1043
- for (let i = 0; i < pcm.length; i += 1) v.setInt16(44 + i * 2, pcm[i], true);
1044
- return new Uint8Array(buf);
1045
- }
1046
- function fromWav(bytes) {
1047
- const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
1048
- const tag = (at2) => String.fromCharCode(...bytes.subarray(at2, at2 + 4));
1049
- if (bytes.length < 12 || tag(0) !== "RIFF" || tag(8) !== "WAVE") throw new Error("not a WAV file");
1050
- let at = 12;
1051
- let rate = 0;
1052
- let channels = 1;
1053
- while (at + 8 <= bytes.length) {
1054
- const id = tag(at);
1055
- const size = v.getUint32(at + 4, true);
1056
- if (id === "fmt ") {
1057
- const format = v.getUint16(at + 8, true);
1058
- channels = v.getUint16(at + 10, true);
1059
- rate = v.getUint32(at + 12, true);
1060
- const bits = v.getUint16(at + 22, true);
1061
- if (format !== 1 && format !== 65534 || bits !== 16) throw new Error(`only 16-bit PCM WAV is read (format ${format}, ${bits} bits)`);
1062
- } else if (id === "data") {
1063
- if (!rate) throw new Error("a WAV data chunk before its format");
1064
- const len = size === 0 || size === 4294967295 || at + 8 + size > bytes.length ? bytes.length - at - 8 : size;
1065
- const n = Math.floor(len / 2 / channels);
1066
- const pcm = new Int16Array(n);
1067
- for (let i = 0; i < n; i += 1) {
1068
- let sum = 0;
1069
- for (let c = 0; c < channels; c += 1) sum += v.getInt16(at + 8 + (i * channels + c) * 2, true);
1070
- pcm[i] = Math.round(sum / channels);
1071
- }
1072
- return { pcm, sampleRate: rate };
1073
- }
1074
- at += 8 + size + size % 2;
1075
- }
1076
- throw new Error("a WAV file without data");
1077
- }
1078
- function fromS16le(bytes) {
1079
- const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
1080
- const out = new Int16Array(Math.floor(bytes.length / 2));
1081
- for (let i = 0; i < out.length; i += 1) out[i] = v.getInt16(i * 2, true);
1082
- return out;
1083
- }
1084
- function resample(pcm, from, to) {
1085
- if (from === to || !pcm.length) return pcm.slice();
1086
- const n = Math.max(1, Math.round(pcm.length * to / from));
1087
- const out = new Int16Array(n);
1088
- const step = from / to;
1089
- for (let i = 0; i < n; i += 1) {
1090
- const x = i * step;
1091
- const a = Math.min(pcm.length - 1, Math.floor(x));
1092
- const b = Math.min(pcm.length - 1, a + 1);
1093
- out[i] = Math.round(pcm[a] + (pcm[b] - pcm[a]) * (x - a));
1094
- }
1095
- return out;
1096
- }
1097
- function trimSilence(p, o = {}) {
1098
- const level = o.level ?? 400;
1099
- const pad = Math.round((o.padMs ?? 40) * p.sampleRate / 1e3);
1100
- let a = 0;
1101
- while (a < p.pcm.length && Math.abs(p.pcm[a]) < level) a += 1;
1102
- if (a === p.pcm.length) return { pcm: new Int16Array(0), sampleRate: p.sampleRate };
1103
- let b = p.pcm.length - 1;
1104
- while (b > a && Math.abs(p.pcm[b]) < level) b -= 1;
1105
- return { pcm: p.pcm.slice(Math.max(0, a - pad), Math.min(p.pcm.length, b + 1 + pad)), sampleRate: p.sampleRate };
1106
- }
1107
- var msOf = (p) => p.pcm.length * 1e3 / p.sampleRate;
1108
- function mix(lines, totalMs, o = {}) {
1109
- const out = new Float64Array(Math.max(0, Math.round(totalMs * TRACK_RATE / 1e3)));
1110
- const fade = Math.round((o.fadeMs ?? 15) * TRACK_RATE / 1e3);
1111
- for (const l of lines) {
1112
- const s = resample(l.audio.pcm, l.audio.sampleRate, TRACK_RATE);
1113
- const at = Math.round(l.start * TRACK_RATE / 1e3);
1114
- const f = Math.min(fade, Math.floor(s.length / 2));
1115
- for (let i = 0; i < s.length; i += 1) {
1116
- const k = at + i;
1117
- if (k < 0) continue;
1118
- if (k >= out.length) break;
1119
- const g = f ? Math.min(1, i / f, (s.length - 1 - i) / f) : 1;
1120
- out[k] += s[i] * g;
1121
- }
1122
- }
1123
- const pcm = new Int16Array(out.length);
1124
- for (let i = 0; i < out.length; i += 1) pcm[i] = Math.max(-32768, Math.min(32767, Math.round(out[i])));
1125
- return pcm;
1126
- }
1127
-
1128
- // src/narration.ts
1129
- import { preview } from "trace-avatar/assist";
1130
- function linesOf(steps, script) {
1131
- const out = /* @__PURE__ */ new Map();
1132
- steps.forEach((s, i) => {
1133
- if (s.say?.trim()) out.set(i, s.say.trim());
1134
- });
1135
- for (const l of script?.lines ?? []) {
1136
- const i = l.n - 1;
1137
- if (!Number.isInteger(i) || i < 0 || i >= steps.length) throw new Error(`the script has a line for step ${l.n}, but the trace has ${steps.length} steps`);
1138
- if (l.text.trim()) out.set(i, l.text.trim());
1139
- else out.delete(i);
1140
- }
1141
- return out;
1142
- }
1143
- function parseScript(json) {
1144
- const lines = json?.lines;
1145
- if (!Array.isArray(lines) || lines.some((l) => !l || typeof l.n !== "number" || typeof l.text !== "string")) {
1146
- throw new Error('a narration script is { "lines": [{ "n": 1, "text": "\u2026" }] }');
1147
- }
1148
- return { lines: lines.map((l) => ({ n: l.n, text: l.text })) };
1149
- }
1150
- function planNarration(acts, lines, endMs, o = {}) {
1151
- const first = o.firstMs ?? 300;
1152
- const after = o.afterActMs ?? 200;
1153
- const before = o.beforeActMs ?? 250;
1154
- const gap = o.gapMs ?? 150;
1155
- const maxHold = o.maxHoldMs ?? 8e3;
1156
- const plan = { lines: [], holds: [], long: [] };
1157
- let extra = 0;
1158
- let prevCut = null;
1159
- let prevEnd = -Infinity;
1160
- for (const a of acts.slice().sort((x, y) => x.t - y.t)) {
1161
- const line = lines.get(a.index);
1162
- const prevHeld = prevCut === null ? null : prevCut + extra;
1163
- if (line && line.ms > 0) {
1164
- const start = Math.max(prevHeld === null ? first : prevHeld + after, prevEnd + gap);
1165
- const end = start + line.ms;
1166
- const need = Math.ceil(end - (a.t + extra - before));
1167
- if (need > 0) {
1168
- plan.holds.push({ at: Math.max(0, a.t - before, prevCut ?? 0), ms: need });
1169
- extra += need;
1170
- if (need > maxHold) plan.long.push({ index: a.index, ms: need });
1171
- }
1172
- plan.lines.push({ index: a.index, text: line.text, start: Math.round(start), ms: Math.round(line.ms) });
1173
- prevEnd = end;
1174
- }
1175
- prevCut = a.t;
1176
- }
1177
- const endHoldMs = Math.max(0, Math.ceil(prevEnd + (o.tailMs ?? 400) - (endMs + extra)));
1178
- if (endHoldMs > 0) plan.holds.push({ at: endMs, ms: endHoldMs });
1179
- return { ...plan, endHoldMs };
1180
- }
1181
- function narrationText(lines, offsetMs = 0) {
1182
- const at = (ms) => {
1183
- const s = Math.round((ms + offsetMs) / 1e3);
1184
- return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
1185
- };
1186
- return lines.map((l) => `[${at(l.start)}] ${l.text}`).join("\n") + (lines.length ? "\n" : "");
1187
- }
1188
- var SCRIPT_SCHEMA = { type: "object", properties: { lines: { type: "array", items: { type: "object", properties: { n: { type: "integer" }, text: { type: "string" } }, required: ["n", "text"] } } }, required: ["lines"] };
1189
- var SCRIPT_INSTRUCTIONS = `You write the voice-over for a short screen guide. For each step, write one line to be spoken while the cursor moves to it: a full, natural sentence in plain English, second person ("Now click Save"), at most 25 words. Spell out symbols and numbers as spoken ("twenty percent", not "20%"). Keep the meaning of the step's caption when it has one. Skip steps that need no words (return no line for them). Never invent data values. Answer with JSON: { "lines": [{ "n": <step number>, "text": "\u2026" }] }.`;
1190
- async function suggestScript(ai, trace) {
1191
- const p = preview("captions", trace);
1192
- const answer = await ai("narration", p.input, SCRIPT_SCHEMA, { instructions: SCRIPT_INSTRUCTIONS });
1193
- const steps = trace.steps?.length ?? 0;
1194
- const lines = [];
1195
- const dropped = [];
1196
- const seen = /* @__PURE__ */ new Set();
1197
- for (const l of answer?.lines ?? []) {
1198
- const n = l?.n;
1199
- const text = typeof l?.text === "string" ? l.text.trim() : "";
1200
- if (typeof n !== "number" || !Number.isInteger(n) || n < 1 || n > steps) dropped.push({ n, why: "no such step" });
1201
- else if (seen.has(n)) dropped.push({ n, why: "a second line for the step" });
1202
- else if (!text) dropped.push({ n, why: "empty" });
1203
- else if (text.length > 300) dropped.push({ n, why: "longer than 300 characters" });
1204
- else {
1205
- seen.add(n);
1206
- lines.push({ n, text });
1407
+ const marks = events.filter((e) => e.url && e.type !== "unload").slice().sort((a, b) => a.t - b.t);
1408
+ return (src) => {
1409
+ let url = marks[0]?.url ?? "/";
1410
+ for (const m of marks) {
1411
+ if (m.t <= src) url = m.url;
1412
+ else break;
1413
+ }
1414
+ return url;
1415
+ };
1416
+ }
1417
+ function cueAt(cues, t, fadeMs = 150) {
1418
+ for (const c of cues) {
1419
+ if (t >= c.start && t < c.end) {
1420
+ const alpha = Math.min(1, (t - c.start) / fadeMs, (c.end - t) / fadeMs);
1421
+ return { cue: c, alpha: Math.max(0, alpha) };
1207
1422
  }
1208
1423
  }
1209
- return { script: { lines: lines.sort((a, b) => a.n - b.n) }, dropped };
1424
+ return null;
1210
1425
  }
1211
1426
 
1212
1427
  // src/repair.ts
1213
- import { existsSync, readFileSync as readFileSync4 } from "fs";
1214
- import { dirname as dirname2, join } from "path";
1428
+ import { existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
1429
+ import { dirname as dirname2, join as join2 } from "path";
1215
1430
  import { applyRaw, chooseRepair, chooseWait, guessWait, repairSuggestion, typedOf, waitSuggestion } from "trace-avatar/assist";
1216
1431
  function repairScriptOf(playerFile) {
1217
- const file = join(dirname2(playerFile), "trace-repair.min.js");
1218
- if (!existsSync(file)) throw new RenderError(`--repair needs trace-avatar 0.1.7 or later (no ${file})`);
1432
+ const file = join2(dirname2(playerFile), "trace-repair.min.js");
1433
+ if (!existsSync3(file)) throw new RenderError(`--repair needs trace-avatar 0.1.7 or later (no ${file})`);
1219
1434
  return file;
1220
1435
  }
1221
1436
  function stallInspector(o) {
1222
- const code = `${readFileSync4(o.script, "utf8")}
1437
+ const code = `${readFileSync5(o.script, "utf8")}
1223
1438
  ;window.__taRepair = TraceAvatarRepair;`;
1224
1439
  return async (page, stall) => {
1225
1440
  if (stall.reason === "until-timeout") return waitInspect(page, stall.index);
@@ -1342,69 +1557,7 @@ function chapterCues(starts, endMs) {
1342
1557
  });
1343
1558
  }
1344
1559
 
1345
- // src/ai.ts
1346
- import { resolve as resolve2 } from "path";
1347
- import { pathToFileURL } from "url";
1348
- import { gateway, openAiCompatible } from "trace-avatar/assist";
1349
- async function providerOf(spec, env = process.env, o = {}) {
1350
- const vision = o.vision ? { visionModel: o.vision } : {};
1351
- const g = /^gateway(?::([\w.-]+)(?:\/([^,]+))?((?:,[\w.-]+)*))?$/.exec(spec);
1352
- if (g) {
1353
- return gateway({
1354
- ...g[1] ? { provider: [g[1], ...(g[3] ?? "").split(",").filter(Boolean)] } : {},
1355
- ...g[2] ? { model: g[2] } : {},
1356
- ...vision,
1357
- url: env.AI_GATEWAY_URL,
1358
- key: env.AI_GATEWAY_KEY
1359
- });
1360
- }
1361
- const m = /^openai:(.+)$/.exec(spec);
1362
- if (m) {
1363
- if (!env.OPENAI_API_KEY && !env.OPENAI_BASE_URL) throw new Error("--ai openai:\u2026 needs OPENAI_API_KEY (and OPENAI_BASE_URL for another OpenAI-compatible server)");
1364
- return openAiCompatible({ baseUrl: env.OPENAI_BASE_URL || "https://api.openai.com/v1", ...env.OPENAI_API_KEY ? { key: env.OPENAI_API_KEY } : {}, model: m[1], ...vision });
1365
- }
1366
- if (/\.(m?js|cjs)$/.test(spec)) {
1367
- const mod = await import(pathToFileURL(resolve2(spec)).href);
1368
- const fn = mod.default ?? mod.ai;
1369
- if (typeof fn !== "function") throw new Error(`${spec} must export a default function (task, input, schema, { instructions, images }) \u2192 JSON`);
1370
- return fn;
1371
- }
1372
- throw new Error(`--ai is gateway, gateway:<provider>[/<model>][,<provider>\u2026], openai:<model>, or a .js file (got "${spec}")`);
1373
- }
1374
- var QA_KINDS = ["error", "empty", "stalled", "personal-data", "wrong-page", "other"];
1375
- var QA_SCHEMA = {
1376
- type: "object",
1377
- required: ["flags"],
1378
- properties: { flags: { type: "array", items: { type: "object", required: ["frame", "kind", "note"], properties: {
1379
- frame: { type: "integer" },
1380
- kind: { enum: [...QA_KINDS] },
1381
- note: { type: "string", maxLength: 200 }
1382
- } } } }
1383
- };
1384
- var QA_INSTRUCTIONS = `You check frames of a GIF/video of an on-screen guide before it is published: a cursor with a name badge walks through a web app. For each numbered frame, flag only real problems a viewer would notice: an error message or toast ("error"), an empty state or blank page where content is expected ("empty"), a "Looking for \u2026" caption meaning the guide got stuck ("stalled"), personal data such as real email addresses, phone numbers, card or account numbers ("personal-data"), or a page that does not fit the step ("wrong-page"). The cursor, the name badge, highlights and captions are part of the guide, not problems. Reply with JSON only: {"flags":[{"frame":1,"kind":"error","note":"\u2026"}]}, an empty list when all is well.`;
1385
- async function runQa(ai, frames, context) {
1386
- if (!frames.length) return [];
1387
- const input = { title: context.title, steps: context.steps, frames: frames.map((f, k) => ({ frame: k + 1, at: Math.round(f.at / 100) / 10, shows: f.label })) };
1388
- const answer = await ai("qa", input, QA_SCHEMA, { instructions: QA_INSTRUCTIONS, images: frames.map((f, k) => ({ png: f.png, label: `Frame ${k + 1}: ${f.label}` })) });
1389
- const list = answer && typeof answer === "object" && Array.isArray(answer.flags) ? answer.flags : null;
1390
- if (!list) throw new Error('the QA answer has no "flags" list');
1391
- const out = [];
1392
- for (const item of list) {
1393
- const r = item;
1394
- if (!Number.isInteger(r?.frame) || r.frame < 1 || r.frame > frames.length) continue;
1395
- const kind = QA_KINDS.includes(r.kind) ? r.kind : "other";
1396
- const note = typeof r.note === "string" ? r.note.replace(/\s+/g, " ").trim().slice(0, 200) : "";
1397
- out.push({ at: frames[r.frame - 1].at, kind, note });
1398
- }
1399
- return out.sort((a, b) => a.at - b.at);
1400
- }
1401
-
1402
1560
  // src/render.ts
1403
- import { readFileSync as readFileSync5, writeFileSync, mkdirSync, mkdtempSync, rmSync } from "fs";
1404
- import { tmpdir } from "os";
1405
- import { dirname as dirname3, extname as extname2, join as join2 } from "path";
1406
- import { chromium as chromium2 } from "playwright";
1407
- import { PNG as PNG2 } from "pngjs";
1408
1561
  import { describe as describeGuide } from "trace-avatar/assist";
1409
1562
  var formatOf = (file) => {
1410
1563
  const ext = extname2(file).toLowerCase();
@@ -1425,7 +1578,7 @@ function cardOf(v, fallback) {
1425
1578
  return { ...fallback, ...v };
1426
1579
  }
1427
1580
  async function render(o) {
1428
- const trace = typeof o.trace === "string" ? JSON.parse(readFileSync5(o.trace, "utf8")) : o.trace;
1581
+ let trace = typeof o.trace === "string" ? JSON.parse(readFileSync6(o.trace, "utf8")) : o.trace;
1429
1582
  if (!trace || typeof trace !== "object") throw new RenderError("the trace must be an object or a .trace.json path");
1430
1583
  const mode = o.mode ?? "overlay";
1431
1584
  if (mode === "perform" && !o.allowPerform) {
@@ -1434,14 +1587,18 @@ async function render(o) {
1434
1587
  const outs = o.out.map((x) => typeof x === "string" ? { file: x } : x).map((x) => ({ ...x, format: formatOf(x.file) }));
1435
1588
  if (!outs.length) throw new RenderError("nothing to write: give at least one output (.gif or .mp4)");
1436
1589
  const ffmpeg = outs.some((x) => x.format === "mp4") ? findFfmpeg() : null;
1437
- if (outs.some((x) => x.format === "mp4") && !ffmpeg) throw new RenderError("MP4 needs ffmpeg: install it (brew install ffmpeg, apt install ffmpeg) or set FFMPEG to its path. GIF works without it.");
1590
+ if (outs.some((x) => x.format === "mp4") && !ffmpeg) throw new RenderError(FFMPEG_MISSING);
1438
1591
  const t = trace;
1439
1592
  const viewport = o.viewport ?? t.meta?.viewport ?? { w: 1280, h: 800 };
1440
1593
  const burn = o.captions === "burn" || o.captions === "both";
1441
1594
  if ((o.qa || o.alt) && !o.ai) throw new RenderError("qa and alt need an AI: pass ai (--ai)");
1442
1595
  if (o.voice && !outs.some((x) => x.format === "mp4")) throw new RenderError("narration is for video: add an .mp4 output (a GIF has no sound)");
1443
- const spoken = o.voice ? linesOf(trace.steps ?? [], o.script === void 0 ? void 0 : parseScript(typeof o.script === "string" ? JSON.parse(readFileSync5(o.script, "utf8")) : o.script)) : null;
1596
+ const spoken = o.voice ? linesOf(trace.steps ?? [], o.script === void 0 ? void 0 : parseScript(typeof o.script === "string" ? JSON.parse(readFileSync6(o.script, "utf8")) : o.script)) : null;
1444
1597
  if (spoken && !spoken.size) throw new RenderError("nothing to say: no step has a caption (say), and no script was given");
1598
+ if (spoken && o.script !== void 0) {
1599
+ const steps2 = trace.steps ?? [];
1600
+ trace = { ...trace, steps: steps2.map((st, i) => spoken.has(i) && spoken.get(i) !== st.say ? { ...st, say: spoken.get(i) } : st) };
1601
+ }
1445
1602
  if (o.repairVision && !(o.repair && o.ai)) throw new RenderError("repairVision needs repair and an AI");
1446
1603
  const capOpts = {
1447
1604
  url: o.url,
@@ -1474,8 +1631,8 @@ async function render(o) {
1474
1631
  if (!(o.repair && e instanceof RenderError && e.stall)) throw e;
1475
1632
  const outcome = await repairGuide({ trace, capture: capOpts, ...o.ai ? { ai: o.ai } : {}, ...o.repairVision ? { vision: true } : {}, first: e });
1476
1633
  const file = `${base(outs[0].file)}.repair.json`;
1477
- mkdirSync(dirname3(file) || ".", { recursive: true });
1478
- writeFileSync(file, `${JSON.stringify({ task: "repair", suggestions: outcome.suggestions, unresolved: outcome.unresolved, passed: outcome.passed }, null, 2)}
1634
+ mkdirSync2(dirname3(file) || ".", { recursive: true });
1635
+ writeFileSync2(file, `${JSON.stringify({ task: "repair", suggestions: outcome.suggestions, unresolved: outcome.unresolved, passed: outcome.passed }, null, 2)}
1479
1636
  `);
1480
1637
  const n = outcome.suggestions.length;
1481
1638
  const ok = outcome.suggestions.filter((x) => x.verified).length;
@@ -1514,7 +1671,7 @@ repair: ${n ? `${n} fix${n > 1 ? "es" : ""} (${ok} verified${outcome.passed ? ",
1514
1671
  });
1515
1672
  if (described?.alt) {
1516
1673
  const file = `${base(outs[0].file)}.alt.txt`;
1517
- writeFileSync(file, `${described.alt}
1674
+ writeFileSync2(file, `${described.alt}
1518
1675
  `);
1519
1676
  r.alt = file;
1520
1677
  }
@@ -1587,9 +1744,9 @@ async function finish(cap, outs, o = {}) {
1587
1744
  cues: o.captions ? stepCues(cap.events.map((e) => e.stepType === "card" ? { ...e, say: void 0 } : e), sg, ms) : []
1588
1745
  };
1589
1746
  };
1590
- const main = variant(segs);
1591
- const plain = narr ? variant(cut) : main;
1592
- const cues = main.cues;
1747
+ const main2 = variant(segs);
1748
+ const plain = narr ? variant(cut) : main2;
1749
+ const cues = main2.cues;
1593
1750
  const page = pageAt(cap.events);
1594
1751
  const titleMs = o.cards?.title ? TITLE_MS : 0;
1595
1752
  const endMs = o.cards?.end ? END_MS : 0;
@@ -1601,14 +1758,14 @@ async function finish(cap, outs, o = {}) {
1601
1758
  const qaFrames = [];
1602
1759
  let poster;
1603
1760
  let wav;
1604
- const tmp = narr ? mkdtempSync(join2(tmpdir(), "tar-voice-")) : null;
1761
+ const tmp = narr ? mkdtempSync2(join3(tmpdir2(), "tar-voice-")) : null;
1605
1762
  try {
1606
1763
  layers = browser ? await createLayers(browser) : null;
1607
1764
  for (const [n, out] of outs.entries()) {
1608
- mkdirSync(dirname3(out.file) || ".", { recursive: true });
1765
+ mkdirSync2(dirname3(out.file) || ".", { recursive: true });
1609
1766
  const fps = out.fps ?? (out.format === "gif" ? 12 : 30);
1610
1767
  const layout = layoutOf(srcW, srcH, out.width ?? (out.format === "gif" ? 800 : void 0), frameStyle, canvases[n]);
1611
- const v = out.format === "gif" ? plain : main;
1768
+ const v = out.format === "gif" ? plain : main2;
1612
1769
  const { cam, segs: segs2, contentMs: contentMs2 } = v;
1613
1770
  const cues2 = v.cues;
1614
1771
  const times = frameTimes(segs2, fps);
@@ -1681,7 +1838,7 @@ async function finish(cap, outs, o = {}) {
1681
1838
  const w = createGifWriter({ width: layout.width, height: layout.height, fps, palette: paletteOf(samples, samples.length) });
1682
1839
  for (let m = 0; m < total; m += 1) w.add(frameAt(m));
1683
1840
  const gif = w.finish();
1684
- writeFileSync(out.file, gif.bytes);
1841
+ writeFileSync2(out.file, gif.bytes);
1685
1842
  outputs.push({ file: out.file, format: "gif", width: layout.width, height: layout.height, fps, frames: total, bytes: gif.bytes.length, durationMs: gif.durationMs });
1686
1843
  } else {
1687
1844
  const all = function* () {
@@ -1690,16 +1847,16 @@ async function finish(cap, outs, o = {}) {
1690
1847
  let audio;
1691
1848
  if (narr && said && tmp) {
1692
1849
  const track = mix(said.lines.map((l) => ({ start: l.start + titleMs, audio: narr.lines.get(l.index).audio })), total * 1e3 / fps);
1693
- audio = join2(tmp, `${n}.wav`);
1694
- writeFileSync(audio, toWav(track, TRACK_RATE));
1850
+ audio = join3(tmp, `${n}.wav`);
1851
+ writeFileSync2(audio, toWav(track, TRACK_RATE));
1695
1852
  if (narr.out && !wav) {
1696
- mkdirSync(dirname3(narr.out) || ".", { recursive: true });
1697
- writeFileSync(narr.out, toWav(track, TRACK_RATE));
1853
+ mkdirSync2(dirname3(narr.out) || ".", { recursive: true });
1854
+ writeFileSync2(narr.out, toWav(track, TRACK_RATE));
1698
1855
  wav = narr.out;
1699
1856
  }
1700
1857
  }
1701
1858
  await encodeMp4(all(), { file: out.file, fps, width: layout.width, height: layout.height, ...audio ? { audio } : {} });
1702
- outputs.push({ file: out.file, format: "mp4", width: layout.width, height: layout.height, fps, frames: total, bytes: readFileSync5(out.file).length, durationMs: Math.round(total * 1e3 / fps) });
1859
+ outputs.push({ file: out.file, format: "mp4", width: layout.width, height: layout.height, fps, frames: total, bytes: readFileSync6(out.file).length, durationMs: Math.round(total * 1e3 / fps) });
1703
1860
  }
1704
1861
  if (n === 0 && o.poster) {
1705
1862
  const click = cap.events.find((e) => e.type === "step" && (e.stepType === "click" || e.stepType === "dblclick"));
@@ -1710,8 +1867,8 @@ async function finish(cap, outs, o = {}) {
1710
1867
  const png = new PNG2({ width: img.width, height: img.height });
1711
1868
  png.data.set(img.data);
1712
1869
  poster = typeof o.poster === "string" ? o.poster : `${base(out.file)}.png`;
1713
- mkdirSync(dirname3(poster) || ".", { recursive: true });
1714
- writeFileSync(poster, PNG2.sync.write(png));
1870
+ mkdirSync2(dirname3(poster) || ".", { recursive: true });
1871
+ writeFileSync2(poster, PNG2.sync.write(png));
1715
1872
  }
1716
1873
  if (n === 0 && o.qa) {
1717
1874
  const steps = cap.events.filter((e) => e.type === "step" && e.index !== void 0);
@@ -1735,7 +1892,7 @@ async function finish(cap, outs, o = {}) {
1735
1892
  await layers?.close().catch(() => {
1736
1893
  });
1737
1894
  await browser?.close();
1738
- if (tmp) rmSync(tmp, { recursive: true, force: true });
1895
+ if (tmp) rmSync2(tmp, { recursive: true, force: true });
1739
1896
  }
1740
1897
  let vtt;
1741
1898
  let chapters;
@@ -1743,211 +1900,1549 @@ async function finish(cap, outs, o = {}) {
1743
1900
  const shift = (c) => ({ ...c, start: c.start + titleMs, end: c.end + titleMs });
1744
1901
  vtt = `${base(outs[0].file)}.vtt`;
1745
1902
  chapters = `${base(outs[0].file)}.chapters.vtt`;
1746
- writeFileSync(vtt, toVtt(cues.map(shift)));
1747
- writeFileSync(chapters, toVtt(o.chapterNames?.length ? namedChapters(o.chapterNames, cap.events, segs, contentMs).map(shift) : chapterCues(cues.map((c) => ({ t: c.start, text: c.text })), contentMs).map(shift)));
1903
+ writeFileSync2(vtt, toVtt(cues.map(shift)));
1904
+ writeFileSync2(chapters, toVtt(o.chapterNames?.length ? namedChapters(o.chapterNames, cap.events, segs, contentMs).map(shift) : chapterCues(cues.map((c) => ({ t: c.start, text: c.text })), contentMs).map(shift)));
1905
+ }
1906
+ const qa = o.qa ? await runQa(o.qa.ai, qaFrames, { title: o.qa.title, steps: o.qa.steps }) : void 0;
1907
+ let narration;
1908
+ if (said) {
1909
+ const mp4 = outs.find((x) => x.format === "mp4");
1910
+ const text = `${base(mp4.file)}.narration.txt`;
1911
+ writeFileSync2(text, narrationText(said.lines, titleMs));
1912
+ narration = { lines: said.lines.map((l) => ({ ...l, start: l.start + titleMs })), holdMs: said.holds.reduce((a, h) => a + h.ms, 0), text, ...wav ? { wav } : {} };
1913
+ }
1914
+ const rel = (t) => Math.round(t - start);
1915
+ const result = {
1916
+ durationMs: Math.round(contentMs + titleMs + endMs),
1917
+ offsetMs: titleMs,
1918
+ rawMs: Math.round(end - start),
1919
+ segments: segs.map((s) => ({ from: rel(s.from), to: rel(s.to), ...s.hold ? { hold: s.hold } : {}, ...s.card !== void 0 ? { card: s.card } : {} })),
1920
+ events: cap.events.map((e) => ({ ...e, t: rel(e.t) })),
1921
+ outputs,
1922
+ ...poster ? { poster } : {},
1923
+ ...vtt ? { vtt, chapters } : {},
1924
+ ...qa ? { qa } : {},
1925
+ ...narration ? { narration } : {},
1926
+ ...warnings.length ? { warnings } : {}
1927
+ };
1928
+ if (o.timeline) {
1929
+ mkdirSync2(dirname3(o.timeline) || ".", { recursive: true });
1930
+ writeFileSync2(o.timeline, JSON.stringify(result, null, 2));
1931
+ }
1932
+ return result;
1933
+ }
1934
+ function namedChapters(names, events, segs, endMs) {
1935
+ const starts = names.flatMap((c) => {
1936
+ const e = events.find((x) => x.type === "step" && x.index === c.index);
1937
+ const t = e ? outputAt(segs, e.t) : null;
1938
+ return t === null ? [] : [{ t: c.index === names[0].index ? 0 : t, text: c.name }];
1939
+ }).sort((a, b) => a.t - b.t);
1940
+ return starts.map((c, k) => ({ start: c.t, end: starts[k + 1]?.t ?? endMs, text: c.text }));
1941
+ }
1942
+ function badgeAt(W, H, w, h, at = "bottom-right") {
1943
+ const m = Math.round(Math.min(W, H) * 0.025);
1944
+ return { x: at.endsWith("left") ? m : W - w - m, y: at.startsWith("top") ? m : H - h - m };
1945
+ }
1946
+ async function artFor(layers, layout, o) {
1947
+ const art = { base: null, captions: /* @__PURE__ */ new Map(), mid: [] };
1948
+ if (!layers) return art;
1949
+ if (o.frameStyle !== "none" || layout.canvas) {
1950
+ art.base = /* @__PURE__ */ new Map();
1951
+ for (const url of o.urls.length ? o.urls : ["/"]) art.base.set(url, await layers.base(layout, { background: o.background, path: url, title: o.titles[url] }));
1952
+ }
1953
+ const fontPx = layout.canvas ? Math.max(12, Math.round(layout.width * 0.034)) : Math.max(12, Math.round(layout.content.w * 0.026));
1954
+ const maxWidth = Math.round(layout.canvas ? layout.width * 0.9 : layout.content.w * 0.8);
1955
+ for (const c of o.cues) {
1956
+ if (!art.captions.has(c.text)) art.captions.set(c.text, await layers.caption(c.text, { maxWidth, fontPx }));
1957
+ }
1958
+ if (o.cards?.title) art.title = await layers.card(layout, { ...o.cards.title, background: o.background });
1959
+ if (o.cards?.end) art.end = await layers.card(layout, { ...o.cards.end, background: o.background });
1960
+ for (const c of o.mid ?? []) art.mid.push(await layers.card(layout, { ...c, background: o.background }));
1961
+ if (o.mark) {
1962
+ 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 } : {} });
1963
+ const { x, y } = badgeAt(layout.width, layout.height, img.width, img.height, o.mark.at);
1964
+ art.badge = { img, x, y, alpha: o.mark.opacity ?? 0.9 };
1965
+ for (const k of ["title", "end"]) {
1966
+ const c = art[k];
1967
+ if (c) {
1968
+ const d = copy(c);
1969
+ overlay(d, img, x, y, art.badge.alpha);
1970
+ art[k] = d;
1971
+ }
1972
+ }
1973
+ art.mid = art.mid.map((c) => {
1974
+ const d = copy(c);
1975
+ overlay(d, img, x, y, art.badge.alpha);
1976
+ return d;
1977
+ });
1978
+ }
1979
+ return art;
1980
+ }
1981
+
1982
+ // src/catalogue.ts
1983
+ var CATALOGUE_SPEC = "trace-avatar-catalogue/1";
1984
+ var CATALOGUE_KINDS = ["intro", "demo", "guide", "onboarding", "pitch", "whats-new", "ad", "docs-gif", "qa", "support"];
1985
+ var CATALOGUE_SHAPES = ["16:9", "1:1", "4:5", "9:16"];
1986
+ var CATALOGUE_FORMATS = ["mp4", "gif"];
1987
+ var CATALOGUE_REQUIRED = ["id", "product", "video", "kind", "preset", "shape", "format", "url", "captionsBurned", "seconds", "narrated", "alt", "site", "made"];
1988
+ function catalogueId(e) {
1989
+ return `${e.product}/${e.video}/${e.preset}/${e.format === "gif" || !e.shape ? "gif" : e.shape}`;
1990
+ }
1991
+ var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
1992
+ var isTime = (v) => typeof v === "string" && /^\d{4}-\d{2}-\d{2}T/.test(v) && !Number.isNaN(Date.parse(v));
1993
+ var isHttps = (v) => {
1994
+ if (typeof v !== "string") return false;
1995
+ try {
1996
+ return new URL(v).protocol === "https:";
1997
+ } catch {
1998
+ return false;
1999
+ }
2000
+ };
2001
+ function checkShape(doc, problems, warnings, https) {
2002
+ if (!isObj(doc)) {
2003
+ problems.push("a catalogue is a JSON object { spec, updated, videos }");
2004
+ return [];
2005
+ }
2006
+ if (doc.spec !== CATALOGUE_SPEC) problems.push(doc.spec === void 0 ? `no spec: a catalogue says "spec": "${CATALOGUE_SPEC}"` : `spec is ${JSON.stringify(doc.spec)}; this checks ${CATALOGUE_SPEC}`);
2007
+ if (!isTime(doc.updated)) problems.push("updated is an ISO time");
2008
+ if (!Array.isArray(doc.videos)) {
2009
+ problems.push("videos is a list");
2010
+ return [];
2011
+ }
2012
+ const ids = /* @__PURE__ */ new Map();
2013
+ const tuples = /* @__PURE__ */ new Map();
2014
+ const good = [];
2015
+ doc.videos.forEach((v, i) => {
2016
+ const at = `videos[${i}]${isObj(v) && typeof v.id === "string" ? ` (${v.id})` : ""}`;
2017
+ if (!isObj(v)) {
2018
+ problems.push(`${at}: an entry is an object`);
2019
+ return;
2020
+ }
2021
+ const before = problems.length;
2022
+ const p = (m) => problems.push(`${at}: ${m}`);
2023
+ for (const k of CATALOGUE_REQUIRED) if (v[k] === void 0) p(`no ${k}`);
2024
+ for (const k of ["id", "product", "video", "preset"]) if (v[k] !== void 0 && !(typeof v[k] === "string" && /^\S+$/.test(v[k]))) p(`${k} is a word with no spaces`);
2025
+ if (v.kind !== void 0 && !CATALOGUE_KINDS.includes(v.kind)) p(`kind is one of ${CATALOGUE_KINDS.join(", ")}`);
2026
+ if (v.format !== void 0 && !CATALOGUE_FORMATS.includes(v.format)) p("format is mp4 or gif");
2027
+ if (v.format === "gif" && v.shape !== null && v.shape !== void 0) p("a GIF has no shape (null)");
2028
+ if (v.format === "mp4" && !CATALOGUE_SHAPES.includes(v.shape)) p(`an mp4's shape is one of ${CATALOGUE_SHAPES.join(", ")}`);
2029
+ for (const k of ["url", "site"]) if (v[k] !== void 0 && !https(v[k])) p(`${k} is an https link`);
2030
+ for (const k of ["poster", "captions"]) if (v[k] !== void 0 && !https(v[k])) p(`${k} is an https link`);
2031
+ if (v.captionsBurned !== void 0 && typeof v.captionsBurned !== "boolean") p("captionsBurned is true or false");
2032
+ if (v.narrated !== void 0 && typeof v.narrated !== "boolean") p("narrated is true or false");
2033
+ if (v.captions !== void 0 && v.captionsBurned === true) p("captions are burned in, so it has no captions file");
2034
+ if (v.seconds !== void 0 && !(typeof v.seconds === "number" && Number.isFinite(v.seconds) && v.seconds > 0)) p("seconds is its length, a number above 0");
2035
+ if (v.language !== void 0 && !(typeof v.language === "string" && /^[a-z]{2}$/.test(v.language))) p("language is two lowercase letters, e.g. en");
2036
+ if (v.title !== void 0 && v.title !== null && typeof v.title !== "string") p("title is text or null");
2037
+ if (v.alt !== void 0 && !(typeof v.alt === "string" && v.alt.trim())) p("alt says what it shows");
2038
+ if (v.says !== void 0 && !(Array.isArray(v.says) && v.says.length && v.says.every((s) => typeof s === "string" && s.trim()))) p("says is a list of the lines the video shows or speaks");
2039
+ if (v.endsWith !== void 0 && typeof v.endsWith !== "string") p("endsWith is text");
2040
+ if (v.made !== void 0 && !isTime(v.made)) p("made is an ISO time");
2041
+ if (problems.length > before) return;
2042
+ const e = v;
2043
+ const seen = ids.get(e.id);
2044
+ if (seen !== void 0) p(`id used twice (videos[${seen}])`);
2045
+ else ids.set(e.id, i);
2046
+ const tuple = `${e.product}/${e.video}/${e.preset}/${e.shape}/${e.format}`;
2047
+ const twin = tuples.get(tuple);
2048
+ if (twin !== void 0) p(`the same product, video, preset, shape and format as videos[${twin}]`);
2049
+ else tuples.set(tuple, i);
2050
+ if (e.id !== catalogueId(e)) warnings.push(`${at}: the id ${catalogueId(e)} is recommended (stable across re-renders)`);
2051
+ if (e.format === "mp4" && !e.captionsBurned && !e.captions && e.says?.length) warnings.push(`${at}: it has words but no captions file`);
2052
+ good.push(e);
2053
+ });
2054
+ return good;
2055
+ }
2056
+ function vttEnds(text) {
2057
+ if (!/^?WEBVTT(?:[ \t].*)?(?:\r?\n|$)/.test(text)) throw new Error("not WebVTT (it does not start with WEBVTT)");
2058
+ const ends = [];
2059
+ const re = /(?:(\d+):)?(\d{2}):(\d{2})\.(\d{3})\s+-->\s+(?:(\d+):)?(\d{2}):(\d{2})\.(\d{3})/g;
2060
+ for (let m = re.exec(text); m; m = re.exec(text)) ends.push(Number(m[5] ?? 0) * 3600 + Number(m[6]) * 60 + Number(m[7]) + Number(m[8]) / 1e3);
2061
+ return ends;
2062
+ }
2063
+ function mp4Head(bytes) {
2064
+ const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
2065
+ const name = (at2) => String.fromCharCode(bytes[at2], bytes[at2 + 1], bytes[at2 + 2], bytes[at2 + 3]);
2066
+ let at = 0;
2067
+ while (at + 8 <= bytes.length) {
2068
+ let size = dv.getUint32(at);
2069
+ const type = name(at + 4);
2070
+ if (size === 1 && at + 16 <= bytes.length) size = Number(dv.getBigUint64(at + 8));
2071
+ if (type === "mdat") return { faststart: false, codecs: null };
2072
+ if (type === "moov") {
2073
+ if (size < 8 || at + size > bytes.length) return { faststart: true, codecs: null };
2074
+ const body = new TextDecoder("latin1").decode(bytes.subarray(at, at + size));
2075
+ return { faststart: true, codecs: ["avc1", "avc3", "hvc1", "hev1", "mp4a", "Opus"].filter((c) => body.includes(c)) };
2076
+ }
2077
+ if (size < 8) break;
2078
+ at += size;
2079
+ }
2080
+ return { faststart: null, codecs: null };
2081
+ }
2082
+ var TYPES = { mp4: /^video\/mp4\b/, gif: /^image\/gif\b/, poster: /^image\/(png|jpeg|webp)\b/, captions: /^text\/vtt\b/ };
2083
+ async function each(items, n, fn) {
2084
+ let i = 0;
2085
+ await Promise.all(Array.from({ length: Math.min(n, items.length) }, async () => {
2086
+ while (i < items.length) await fn(items[i++]);
2087
+ }));
2088
+ }
2089
+ async function checkCatalogue(doc, o = {}) {
2090
+ const problems = [];
2091
+ const warnings = [];
2092
+ const https = o.allowHttp ? (v) => isHttps(v) || typeof v === "string" && /^http:\/\//.test(v) : isHttps;
2093
+ const entries = checkShape(doc, problems, warnings, https);
2094
+ let fetched = 0;
2095
+ if (o.fetch) {
2096
+ const f = o.fetcher ?? fetch;
2097
+ const jobs = [];
2098
+ for (const e of entries) {
2099
+ jobs.push({ e, what: e.format, url: e.url });
2100
+ if (e.poster) jobs.push({ e, what: "poster", url: e.poster });
2101
+ if (e.captions) jobs.push({ e, what: "captions", url: e.captions });
2102
+ }
2103
+ await each(jobs, o.concurrency ?? 6, async ({ e, what, url }) => {
2104
+ const at = `${e.id} ${what}`;
2105
+ try {
2106
+ const res = await f(url, { headers: what === "captions" ? {} : { range: "bytes=0-262143" }, redirect: "follow" });
2107
+ fetched += 1;
2108
+ if (!res.ok) {
2109
+ problems.push(`${at}: ${url} answered ${res.status}`);
2110
+ return;
2111
+ }
2112
+ const type = res.headers.get("content-type") ?? "";
2113
+ if (!TYPES[what].test(type)) problems.push(`${at}: served as ${type || "no type"}, not ${what === "captions" ? "text/vtt" : what === "poster" ? "an image" : what === "gif" ? "image/gif" : "video/mp4"}`);
2114
+ if (what === "captions") {
2115
+ const ends = vttEnds(await res.text());
2116
+ if (!ends.length) warnings.push(`${at}: the captions have no cues`);
2117
+ else if (Math.max(...ends) > e.seconds + 0.5) problems.push(`${at}: the captions run to ${Math.max(...ends).toFixed(1)} s; the video is ${e.seconds} s`);
2118
+ } else if (what === "mp4") {
2119
+ const head = mp4Head(new Uint8Array(await res.arrayBuffer()));
2120
+ if (head.faststart === false) problems.push(`${at}: its moov comes after its media, so it can't start before it has all loaded (encode with -movflags +faststart)`);
2121
+ else if (head.faststart === null) warnings.push(`${at}: could not read its first boxes`);
2122
+ if (head.codecs && !head.codecs.some((c) => c === "avc1" || c === "avc3")) problems.push(`${at}: not H.264 (${head.codecs.join(", ") || "no known codec"}); platforms want H.264/AAC`);
2123
+ if (head.codecs && e.narrated && !head.codecs.includes("mp4a")) problems.push(`${at}: narrated, but no AAC sound`);
2124
+ } else await res.body?.cancel();
2125
+ } catch (err) {
2126
+ problems.push(`${at}: ${err.message}`);
2127
+ }
2128
+ });
2129
+ }
2130
+ return { ok: !problems.length, problems, warnings, videos: entries.length, fetched };
2131
+ }
2132
+
2133
+ // src/campaign.ts
2134
+ import { spawn as spawn2 } from "child_process";
2135
+ import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync8, rmSync as rmSync3, writeFileSync as writeFileSync4 } from "fs";
2136
+ import { dirname as dirname5, join as join4, resolve as resolve5 } from "path";
2137
+ import { pathToFileURL as pathToFileURL4 } from "url";
2138
+
2139
+ // src/director.ts
2140
+ import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync7, writeFileSync as writeFileSync3 } from "fs";
2141
+ import { dirname as dirname4, extname as extname3, resolve as resolve4 } from "path";
2142
+ import { pathToFileURL as pathToFileURL3 } from "url";
2143
+ import { chromium as chromium3 } from "playwright";
2144
+ import { PNG as PNG3 } from "pngjs";
2145
+ var DIRECTOR_VIEWPORT = { width: 1280, height: 800 };
2146
+ var FPS = 30;
2147
+ var RING_MS = 420;
2148
+ var SKIP_KEEP_MS = 1600;
2149
+ var CURSOR_SIZE = 1.5;
2150
+ var ARROW = [[0, 0], [0, 17], [4.2, 13.1], [7.1, 19.6], [9.8, 18.4], [7, 12.1], [12.6, 12.1]];
2151
+ function inside(poly, x, y) {
2152
+ let c = false;
2153
+ for (let i = 0, j = poly.length - 1; i < poly.length; j = i, i += 1) {
2154
+ const [xi, yi] = poly[i];
2155
+ const [xj, yj] = poly[j];
2156
+ if (yi > y !== yj > y && x < (xj - xi) * (y - yi) / (yj - yi) + xi) c = !c;
2157
+ }
2158
+ return c;
2159
+ }
2160
+ function arrowSprite(scale = 1) {
2161
+ const pad = 2;
2162
+ const w = Math.ceil((13 + pad * 2) * scale);
2163
+ const h = Math.ceil((20 + pad * 2) * scale);
2164
+ const data = new Uint8Array(w * h * 4);
2165
+ const n = 4;
2166
+ const inner = ARROW.map(([x, y]) => [x * 0.8 + 1.3, y * 0.8 + 2.4]);
2167
+ for (let y = 0; y < h; y += 1) {
2168
+ for (let x = 0; x < w; x += 1) {
2169
+ let edge = 0;
2170
+ let body = 0;
2171
+ for (let sy = 0; sy < n; sy += 1) {
2172
+ for (let sx = 0; sx < n; sx += 1) {
2173
+ const px = (x + (sx + 0.5) / n) / scale - pad;
2174
+ const py = (y + (sy + 0.5) / n) / scale - pad;
2175
+ if (inside(ARROW, px, py)) {
2176
+ edge += 1;
2177
+ if (inside(inner, px, py)) body += 1;
2178
+ }
2179
+ }
2180
+ }
2181
+ const k = (y * w + x) * 4;
2182
+ const a = edge / (n * n);
2183
+ const b = edge ? body / edge : 0;
2184
+ const v = Math.round(255 * b + 24 * (1 - b));
2185
+ data[k] = v;
2186
+ data[k + 1] = v;
2187
+ data[k + 2] = v;
2188
+ data[k + 3] = Math.round(a * 255);
2189
+ }
2190
+ }
2191
+ return { width: w, height: h, data, ox: Math.round(pad * scale), oy: Math.round(pad * scale) };
2192
+ }
2193
+ function blend(img, x, y, r, g, b, a) {
2194
+ if (x < 0 || y < 0 || x >= img.width || y >= img.height || a <= 0) return;
2195
+ const k = (y * img.width + x) * 4;
2196
+ img.data[k] = Math.round(img.data[k] * (1 - a) + r * a);
2197
+ img.data[k + 1] = Math.round(img.data[k + 1] * (1 - a) + g * a);
2198
+ img.data[k + 2] = Math.round(img.data[k + 2] * (1 - a) + b * a);
2199
+ }
2200
+ function drawCursor(img, sprite, x, y, ring = null) {
2201
+ if (ring) {
2202
+ const p = ring.p;
2203
+ const rad = 8 + 18 * p;
2204
+ const alpha = 0.55 * (1 - p);
2205
+ const x0 = Math.floor(ring.x - rad - 3);
2206
+ const y0 = Math.floor(ring.y - rad - 3);
2207
+ for (let py = y0; py <= ring.y + rad + 3; py += 1) {
2208
+ for (let px = x0; px <= ring.x + rad + 3; px += 1) {
2209
+ const d = Math.abs(Math.hypot(px - ring.x, py - ring.y) - rad);
2210
+ if (d < 2.5) blend(img, px, py, 37, 99, 235, alpha * Math.min(1, 2.5 - d));
2211
+ }
2212
+ }
2213
+ }
2214
+ const left = Math.round(x) - sprite.ox;
2215
+ const top = Math.round(y) - sprite.oy;
2216
+ for (let sy = 0; sy < sprite.height; sy += 1) {
2217
+ for (let sx = 0; sx < sprite.width; sx += 1) {
2218
+ const k = (sy * sprite.width + sx) * 4;
2219
+ const a = sprite.data[k + 3] / 255;
2220
+ if (a) blend(img, left + sx, top + sy, sprite.data[k], sprite.data[k + 1], sprite.data[k + 2], a);
2221
+ }
2222
+ }
2223
+ }
2224
+ function cursorAt(moves, t) {
2225
+ if (!moves.length) return null;
2226
+ if (t <= moves[0].t) return moves[0];
2227
+ for (let i = 1; i < moves.length; i += 1) {
2228
+ if (moves[i].t >= t) {
2229
+ const a = moves[i - 1];
2230
+ const b = moves[i];
2231
+ const f = b.t === a.t ? 1 : (t - a.t) / (b.t - a.t);
2232
+ return { x: a.x + (b.x - a.x) * f, y: a.y + (b.y - a.y) * f };
2233
+ }
2234
+ }
2235
+ return moves[moves.length - 1];
2236
+ }
2237
+ function withCursor(shots, moves, clicks, o = {}) {
2238
+ if (!shots.length) return [];
2239
+ const sprite = o.sprite ?? arrowSprite((o.scale ?? 1) * CURSOR_SIZE);
2240
+ const times = new Set(shots.map((s2) => s2.t));
2241
+ const step = 1e3 / FPS;
2242
+ for (let i = 1; i < moves.length; i += 1) {
2243
+ if (moves[i].x === moves[i - 1].x && moves[i].y === moves[i - 1].y) continue;
2244
+ for (let t = moves[i - 1].t; t < moves[i].t; t += step) times.add(Math.round(t));
2245
+ times.add(moves[i].t);
2246
+ }
2247
+ for (const c of clicks) for (let t = c.t; t <= c.t + RING_MS + step; t += step) times.add(Math.round(t));
2248
+ const end = shots[shots.length - 1].t;
2249
+ const last = Math.max(end, moves.at(-1)?.t ?? end, (clicks.at(-1)?.t ?? 0) + RING_MS);
2250
+ const sorted = [...times].filter((t) => t >= shots[0].t && t <= last).sort((a, b) => a - b);
2251
+ const out = [];
2252
+ let k = 0;
2253
+ let decoded = null;
2254
+ const s = o.scale ?? 1;
2255
+ for (const t of sorted) {
2256
+ while (k + 1 < shots.length && shots[k + 1].t <= t) k += 1;
2257
+ if (!decoded || decoded.k !== k) {
2258
+ const p = PNG3.sync.read(shots[k].png);
2259
+ decoded = { k, width: p.width, height: p.height, data: p.data };
2260
+ }
2261
+ const img = { width: decoded.width, height: decoded.height, data: Buffer.from(decoded.data) };
2262
+ const at = cursorAt(moves, t);
2263
+ const c = [...clicks].reverse().find((x) => x.t <= t && t - x.t <= RING_MS);
2264
+ if (at) drawCursor(img, sprite, at.x * s, at.y * s, c ? { x: c.x * s, y: c.y * s, p: (t - c.t) / RING_MS } : null);
2265
+ const png = new PNG3({ width: img.width, height: img.height });
2266
+ img.data.copy(png.data);
2267
+ out.push({ t, png: PNG3.sync.write(png, { deflateLevel: 1 }) });
2268
+ }
2269
+ return out;
2270
+ }
2271
+ var sleep3 = (ms) => new Promise((r) => {
2272
+ setTimeout(r, ms);
2273
+ });
2274
+ function pathOf(a, b, ms) {
2275
+ const n = Math.max(2, Math.round(ms / 16));
2276
+ const dx = b.x - a.x;
2277
+ const dy = b.y - a.y;
2278
+ const bend = Math.min(60, Math.hypot(dx, dy) * 0.12);
2279
+ const nx = -dy / (Math.hypot(dx, dy) || 1);
2280
+ const ny = dx / (Math.hypot(dx, dy) || 1);
2281
+ const pts = [];
2282
+ for (let i = 1; i <= n; i += 1) {
2283
+ const f = i / n;
2284
+ const e = f < 0.5 ? 4 * f * f * f : 1 - (-2 * f + 2) ** 3 / 2;
2285
+ const arc = Math.sin(Math.PI * e) * bend;
2286
+ pts.push({ x: a.x + dx * e + nx * arc, y: a.y + dy * e + ny * arc });
2287
+ }
2288
+ return pts;
2289
+ }
2290
+ var travelMs = (d) => Math.round(Math.min(1100, 380 + d * 0.9));
2291
+ function sayFrom(script, count, id = "video") {
2292
+ const out = /* @__PURE__ */ new Map();
2293
+ for (const l of script?.lines ?? []) {
2294
+ if (!(Number.isInteger(l.n) && l.n >= 1 && l.n <= count)) throw new Error(`${id}: the narration script has a line ${l.n}, but the video has ${count} scene(s)`);
2295
+ if (typeof l.text === "string" && l.text.trim()) out.set(l.n, l.text.trim());
2296
+ }
2297
+ return out;
2298
+ }
2299
+ function lookOptions(video, brand, appName = "") {
2300
+ const p = video.polish ?? [];
2301
+ const at = (flag) => p.indexOf(flag);
2302
+ const b = typeof brand === "string" ? brandFile(brand) : brand ?? {};
2303
+ const { titleCard: bTitle, endCard: bEnd, ...look } = b;
2304
+ const o = { ...look };
2305
+ if (at("--canvas") >= 0) o.canvas = p[at("--canvas") + 1];
2306
+ if (at("--watermark") >= 0) o.watermark = p[at("--watermark") + 1];
2307
+ if (at("--frame") >= 0) o.frame = p[at("--frame") + 1];
2308
+ if (at("--captions") >= 0) o.captions = p[at("--captions") + 1];
2309
+ if (at("--captions-at") >= 0) o.captionsAt = p[at("--captions-at") + 1];
2310
+ if (at("--background") >= 0) o.background = p[at("--background") + 1];
2311
+ if (p.includes("--camera")) o.camera = true;
2312
+ if (p.includes("--poster")) o.poster = true;
2313
+ const sub = { sub: appName };
2314
+ const wantTitle = p.includes("--title-card") || bTitle !== void 0;
2315
+ const wantEnd = p.includes("--end-card") || bEnd !== void 0;
2316
+ const cardFrom = (brandCard, own, fallback) => {
2317
+ const base2 = brandCard && typeof brandCard === "object" ? brandCard : typeof brandCard === "string" ? { title: brandCard } : true;
2318
+ const v = own !== void 0 ? base2 === true ? own : { ...base2, title: own } : base2;
2319
+ return cardOf(v, { title: own ?? fallback, ...sub });
2320
+ };
2321
+ const title = wantTitle ? cardFrom(bTitle, video.title, "How to") : void 0;
2322
+ const end = wantEnd ? cardFrom(bEnd, video.endTitle, "Done") : void 0;
2323
+ if (title || end) o.cards = { ...title ? { title } : {}, ...end ? { end } : {} };
2324
+ return o;
2325
+ }
2326
+ function cardsOf(cards, finishCards = {}, appName = "") {
2327
+ const { title: _t, url, ...look } = finishCards?.end ?? finishCards?.title ?? { sub: appName };
2328
+ return cards.map((c) => ({ t: c.t, ms: c.ms, step: c.step, card: { ...look, title: c.title, ...c.url && url ? { url } : {} } }));
2329
+ }
2330
+ var TYPES2 = { ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".css": "text/css; charset=utf-8", ".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png" };
2331
+ function aliasOf(url, alias) {
2332
+ const a = typeof alias === "string" ? { host: alias } : alias;
2333
+ if (!a?.host) return { url, local: null, rewrite: [] };
2334
+ return { url: `https://${a.host}`, local: url.replace(/\/$/, ""), ...a.api ? { api: `https://api.${a.host}`, localApi: a.api.replace(/\/$/, "") } : {}, rewrite: a.rewrite ?? [] };
2335
+ }
2336
+ async function routeAlias(context, alias) {
2337
+ if (!alias.local) return;
2338
+ const forward = (to) => async (route) => {
2339
+ const u = new URL(route.request().url());
2340
+ const response = await route.fetch({ url: `${to}${u.pathname}${u.search}` });
2341
+ if (to === alias.local && alias.localApi && alias.rewrite.includes(u.pathname)) {
2342
+ const body = (await response.text()).split(alias.localApi).join(alias.api);
2343
+ await route.fulfill({ response, body });
2344
+ return;
2345
+ }
2346
+ await route.fulfill({ response });
2347
+ };
2348
+ await context.route(`${alias.url}/**`, forward(alias.local));
2349
+ if (alias.localApi) await context.route(`${alias.api}/**`, forward(alias.localApi));
2350
+ }
2351
+ async function routeFolders(context, base2, routes) {
2352
+ for (const [prefix, dir] of Object.entries(routes)) {
2353
+ const root = resolve4(dir);
2354
+ const at = `/${prefix.replace(/^\/+|\/+$/g, "")}/`;
2355
+ await context.route(`${base2}${at}**`, async (route) => {
2356
+ const rel = decodeURIComponent(new URL(route.request().url()).pathname.slice(at.length));
2357
+ const file = resolve4(root, rel);
2358
+ if (!file.startsWith(`${root}/`) || !existsSync4(file)) return route.fulfill({ status: 404, body: "not found" });
2359
+ return route.fulfill({ status: 200, contentType: TYPES2[extname3(file)] ?? "application/octet-stream", body: readFileSync7(file), headers: { "cache-control": "no-store" } });
2360
+ });
2361
+ }
2362
+ }
2363
+ var pathOfUrl = (u) => {
2364
+ try {
2365
+ return new URL(u).pathname;
2366
+ } catch {
2367
+ return "/";
2368
+ }
2369
+ };
2370
+ async function expectFn() {
2371
+ try {
2372
+ const m = await import("@playwright/test");
2373
+ return m.expect;
2374
+ } catch {
2375
+ return () => {
2376
+ throw new Error("d.expect needs @playwright/test: npm install -D @playwright/test");
2377
+ };
2378
+ }
2379
+ }
2380
+ async function direct(o) {
2381
+ const id = o.id ?? "video";
2382
+ const log = o.log ?? (() => {
2383
+ });
2384
+ const VP = o.viewport ?? DIRECTOR_VIEWPORT;
2385
+ const DSF = o.scale ?? (VP.width === DIRECTOR_VIEWPORT.width && VP.height === DIRECTOR_VIEWPORT.height ? 1 : 2);
2386
+ const alias = aliasOf(o.url, o.alias);
2387
+ const url = alias.url;
2388
+ const script = typeof o.script === "function" ? o.script : (await import(pathToFileURL3(resolve4(o.script)).href)).default;
2389
+ if (typeof script !== "function") throw new Error(`${id}: ${o.script} has no default export (the script)`);
2390
+ const expect = await expectFn();
2391
+ const stateOf = async (opts) => {
2392
+ if (!o.session) return void 0;
2393
+ if (typeof o.session === "string") return o.session;
2394
+ return o.session(url, opts);
2395
+ };
2396
+ const browser = await chromium3.launch({ headless: o.headless ?? true, ...o.launchArgs ? { args: o.launchArgs } : {} });
2397
+ const shots = [];
2398
+ const moves = [];
2399
+ const clicks = [];
2400
+ const events = [];
2401
+ const titles = {};
2402
+ const scenes = [];
2403
+ const cards = [];
2404
+ let playAt = 0;
2405
+ let skipped = false;
2406
+ try {
2407
+ const windowOf = async (opts) => {
2408
+ const signedIn = opts.signedIn !== false;
2409
+ const state = signedIn ? await stateOf(opts) : void 0;
2410
+ const context2 = await browser.newContext({
2411
+ viewport: VP,
2412
+ deviceScaleFactor: DSF,
2413
+ permissions: ["clipboard-read", "clipboard-write"],
2414
+ ...state ? { storageState: state } : {}
2415
+ });
2416
+ await routeAlias(context2, alias);
2417
+ if (o.routes) await routeFolders(context2, url, o.routes);
2418
+ const page2 = await context2.newPage();
2419
+ const cdp2 = await context2.newCDPSession(page2);
2420
+ cdp2.on("Page.screencastFrame", (f2) => {
2421
+ shots.push({ t: f2.metadata?.timestamp ? Math.round(f2.metadata.timestamp * 1e3) : Date.now(), png: Buffer.from(f2.data, "base64") });
2422
+ cdp2.send("Page.screencastFrameAck", { sessionId: f2.sessionId }).catch(() => {
2423
+ });
2424
+ });
2425
+ page2.on("framenavigated", (fr) => {
2426
+ if (fr !== page2.mainFrame()) return;
2427
+ const p = pathOfUrl(page2.url());
2428
+ events.push({ t: Date.now(), type: "page", url: p });
2429
+ page2.title().then((t) => {
2430
+ titles[p] = t;
2431
+ }).catch(() => {
2432
+ });
2433
+ });
2434
+ return { context: context2, page: page2, cdp: cdp2 };
2435
+ };
2436
+ let { context, page, cdp } = await windowOf({ ...o.sessionOptions ?? {}, ...o.signedOut ? { signedIn: false } : {} });
2437
+ const path = () => pathOfUrl(page.url());
2438
+ const screencast = () => cdp.send("Page.startScreencast", { format: "png", everyNthFrame: 1, maxWidth: VP.width * DSF, maxHeight: VP.height * DSF });
2439
+ let at = { x: VP.width * 0.62, y: VP.height * 0.55 };
2440
+ const moveTo = async (to, ms) => {
2441
+ for (const p of pathOf(at, to, ms ?? travelMs(Math.hypot(to.x - at.x, to.y - at.y)))) {
2442
+ await page.mouse.move(p.x, p.y);
2443
+ moves.push({ t: Date.now(), x: p.x, y: p.y });
2444
+ await sleep3(16);
2445
+ }
2446
+ at = to;
2447
+ };
2448
+ const pointOf = async (locator, opts = {}) => {
2449
+ await locator.waitFor({ state: "visible", timeout: opts.timeout ?? 15e3 });
2450
+ await locator.scrollIntoViewIfNeeded();
2451
+ const box = await locator.boundingBox();
2452
+ if (!box) throw new Error(`director: ${locator} has no box`);
2453
+ const fx = box.width > 160 ? 0.35 : 0.5;
2454
+ return { x: box.x + box.width * fx, y: box.y + box.height * 0.5 };
2455
+ };
2456
+ const d = {
2457
+ ...o.props ?? {},
2458
+ page,
2459
+ expect,
2460
+ url,
2461
+ local: alias.local ?? url,
2462
+ async window(p, opts = {}) {
2463
+ await cdp.send("Page.stopScreencast").catch(() => {
2464
+ });
2465
+ await context.close();
2466
+ ({ context, page, cdp } = await windowOf({ ...o.sessionOptions ?? {}, ...opts }));
2467
+ d.page = page;
2468
+ await screencast();
2469
+ await page.goto(`${url}${p}`, { waitUntil: "networkidle" });
2470
+ await sleep3(400);
2471
+ },
2472
+ async open(p) {
2473
+ await page.goto(`${url}${p}`, { waitUntil: "networkidle" });
2474
+ await sleep3(300);
2475
+ },
2476
+ read: (ms = 900) => sleep3(ms),
2477
+ async hover(locator, opts = {}) {
2478
+ const p = await pointOf(locator, opts);
2479
+ await moveTo(p, opts.ms);
2480
+ await sleep3(opts.rest ?? 250);
2481
+ },
2482
+ async click(locator, opts = {}) {
2483
+ const p = await pointOf(locator, opts);
2484
+ await moveTo(p, opts.ms);
2485
+ await sleep3(opts.aim ?? 180);
2486
+ await page.mouse.down();
2487
+ clicks.push({ t: Date.now(), x: p.x, y: p.y });
2488
+ await sleep3(70);
2489
+ await page.mouse.up();
2490
+ await sleep3(opts.rest ?? 350);
2491
+ },
2492
+ async type(locator, text, opts = {}) {
2493
+ await d.click(locator, { rest: 150, ...opts });
2494
+ if (opts.clear) {
2495
+ await page.keyboard.press("ControlOrMeta+A");
2496
+ await page.keyboard.press("Backspace");
2497
+ }
2498
+ await page.keyboard.type(text, { delay: opts.delay ?? 55 });
2499
+ await sleep3(opts.rest ?? 350);
2500
+ },
2501
+ async press(key, opts = {}) {
2502
+ await page.keyboard.press(key);
2503
+ await sleep3(opts.rest ?? 350);
2504
+ },
2505
+ async skip(fn) {
2506
+ events.push({ t: Date.now(), type: "state", phase: "waiting" });
2507
+ await fn();
2508
+ events.push({ t: Date.now(), type: "state", phase: "playing" });
2509
+ skipped = true;
2510
+ },
2511
+ async card(title, opts = {}) {
2512
+ await sleep3(5);
2513
+ const t = Date.now();
2514
+ const index = scenes.length;
2515
+ const ms = opts.ms ?? 2200;
2516
+ scenes.push({ index, caption: title, say: opts.say ?? title, from: t, to: t + ms, card: true });
2517
+ cards.push({ t, ms, title, url: !!opts.url, step: index });
2518
+ events.push({ t: t + 1, type: "step", index, stepType: "card", say: title, url: path() });
2519
+ await sleep3(5);
2520
+ },
2521
+ async scene(caption, fn, opts = {}) {
2522
+ const from = Date.now();
2523
+ await fn();
2524
+ await sleep3(opts.hold ?? 500);
2525
+ const index = scenes.length;
2526
+ scenes.push({ index, caption, say: opts.say ?? caption, from, to: Date.now() });
2527
+ events.push({ t: Date.now(), type: "step", index, stepType: "scene", say: caption, url: path() });
2528
+ }
2529
+ };
2530
+ await screencast();
2531
+ await page.goto(`${url}${o.page ?? "/"}`, { waitUntil: "networkidle" });
2532
+ await sleep3(600);
2533
+ moves.push({ t: Date.now(), ...at });
2534
+ playAt = Date.now();
2535
+ events.push({ t: playAt, type: "play", url: path() });
2536
+ log(`${id}: playing \u2026`);
2537
+ await script(d);
2538
+ await sleep3(o.tailMs ?? 800);
2539
+ moves.push({ t: Date.now(), ...at });
2540
+ await cdp.send("Page.stopScreencast").catch(() => {
2541
+ });
2542
+ await sleep3(100);
2543
+ if (shots.length) shots.push({ t: Date.now(), png: shots[shots.length - 1].png });
2544
+ await context.close();
2545
+ } finally {
2546
+ await browser.close();
2547
+ }
2548
+ if (!shots.length) throw new Error("director: the screencast sent no frames");
2549
+ const stopAt = Date.now();
2550
+ events.push({ t: stopAt, type: "end" });
2551
+ shots.sort((a, b) => a.t - b.t);
2552
+ log(`${id}: ${scenes.length} scenes, ${shots.length} screencast frames; drawing the cursor \u2026`);
2553
+ const frames = withCursor(shots.filter((s) => s.t >= playAt - 400), moves, clicks, { scale: DSF });
2554
+ const cap = { frames, viewport: { w: VP.width, h: VP.height, scale: DSF }, titles, events, playAt, stopAt, endAt: stopAt };
2555
+ const f = { ...o.look ?? {}, cuts: { maxWaitMs: skipped ? SKIP_KEEP_MS : 0 } };
2556
+ if (cards.length) cap.cards = cardsOf(cards, f.cards, o.appName);
2557
+ let narrated = false;
2558
+ if (o.voice) {
2559
+ const lines = /* @__PURE__ */ new Map();
2560
+ if (o.voiceScript) {
2561
+ const s = sayFrom(typeof o.voiceScript === "string" ? JSON.parse(readFileSync7(o.voiceScript, "utf8")) : o.voiceScript, scenes.length, id);
2562
+ for (const sc of scenes) sc.say = s.get(sc.index + 1) ?? sc.say;
2563
+ }
2564
+ for (const sc of scenes) {
2565
+ if (sc.card || !sc.say || sc.say === sc.caption) continue;
2566
+ sc.caption = sc.say;
2567
+ for (const e of events) if (e.type === "step" && e.index === sc.index) e.say = sc.say;
2568
+ }
2569
+ for (const sc of scenes) {
2570
+ if (!sc.say) continue;
2571
+ const audio = trimSilence(await o.voice(sc.say));
2572
+ if (audio.pcm.length) lines.set(sc.index, { text: sc.say, audio });
2573
+ }
2574
+ f.narration = { lines };
2575
+ narrated = lines.size > 0;
2576
+ }
2577
+ for (const x of o.out) mkdirSync3(dirname4(x.file), { recursive: true });
2578
+ if (f.poster === true) f.poster = o.out[0].file.replace(/\.[^./]+$/, ".png");
2579
+ const r = await finish(cap, o.out, f);
2580
+ if (o.scenesFile) writeFileSync3(o.scenesFile, `${JSON.stringify(scenes.map(({ index, caption, say, from, to }) => ({ n: index + 1, caption, say, ms: to - from })), null, 2)}
2581
+ `);
2582
+ return { ...r, narrated, scenes };
2583
+ }
2584
+
2585
+ // src/campaign.ts
2586
+ var CAMPAIGN_KINDS = CATALOGUE_KINDS;
2587
+ var CAMPAIGN_SHAPES = CATALOGUE_SHAPES;
2588
+ var DESKTOP = ["16:9", "1:1", "4:5"];
2589
+ var PHONE = "390x844";
2590
+ var abs = (base2, p) => p === void 0 ? void 0 : resolve5(base2, p);
2591
+ function loadCampaign(file = "campaign.json") {
2592
+ const f = resolve5(file);
2593
+ if (!existsSync5(f)) throw new Error(`no campaign file ${file}`);
2594
+ let c;
2595
+ try {
2596
+ c = JSON.parse(readFileSync8(f, "utf8"));
2597
+ } catch (e) {
2598
+ throw new Error(`${file}: ${e.message}`);
2599
+ }
2600
+ const base2 = dirname5(f);
2601
+ const app = { ...c.app ?? {} };
2602
+ app.dir = process.env.TRACE_AVATAR_APP_DIR ? resolve5(process.env.TRACE_AVATAR_APP_DIR) : resolve5(base2, app.dir ?? ".");
2603
+ for (const k of ["guides", "storageState", "session"]) app[k] = abs(app.dir, app[k]);
2604
+ if (app.routes) app.routes = Object.fromEntries(Object.entries(app.routes).map(([k, v]) => [k, resolve5(base2, v)]));
2605
+ const looks = Object.fromEntries(Object.entries(c.looks ?? {}).map(([k, l]) => [k, { ...l, brand: resolve5(base2, l?.brand ?? "") }]));
2606
+ const videos = (c.videos ?? []).map((v) => ({
2607
+ ...v,
2608
+ ...v.director ? { director: resolve5(base2, v.director) } : {},
2609
+ ...v.guide && /\.json$/i.test(v.guide) ? { guide: resolve5(base2, v.guide) } : {},
2610
+ ...v.voice ? { voice: Object.fromEntries(Object.entries(v.voice).map(([k, s]) => [k, resolve5(base2, s)])) } : {}
2611
+ }));
2612
+ return { ...c, app, looks, videos, file: f, base: base2, out: resolve5(base2, c.out ?? join4("out", c.product ?? "product")) };
2613
+ }
2614
+ var guidesOf = (c) => c.app.guides && existsSync5(c.app.guides) ? JSON.parse(readFileSync8(c.app.guides, "utf8")) : null;
2615
+ function guideOf(c, v, set = guidesOf(c)) {
2616
+ if (/\.json$/i.test(v.guide)) {
2617
+ if (!existsSync5(v.guide)) return null;
2618
+ const trace = JSON.parse(readFileSync8(v.guide, "utf8"));
2619
+ return { trace, page: v.page ?? "/" };
2620
+ }
2621
+ const g = set?.guides.find((x) => x.id === v.guide);
2622
+ if (!g) return null;
2623
+ return { trace: g.trace, page: v.page ?? (g.pages ?? []).find((p) => !p.includes("*")) ?? "/" };
2624
+ }
2625
+ function checkCampaign(c, o = {}) {
2626
+ const files = o.files ?? true;
2627
+ const problems = [];
2628
+ if (!/^[a-z0-9-]+$/.test(c.product ?? "")) problems.push("product is a word of a-z, 0-9 and -, e.g. acme");
2629
+ if (!/^https:\/\/[^\s/]+/.test(c.site ?? "")) problems.push("site is the product's https address, e.g. https://acme.com");
2630
+ if (c.language !== void 0 && !/^[a-z]{2}$/.test(c.language)) problems.push("language is two letters, e.g. en");
2631
+ if (!/^https?:\/\//.test(c.app?.url ?? "")) problems.push("app.url is where the app serves, e.g. http://127.0.0.1:3000");
2632
+ if (c.app.reset && !("post" in c.app.reset && /^https?:\/\//.test(c.app.reset.post)) && !("run" in c.app.reset && Array.isArray(c.app.reset.run) && c.app.reset.run.length)) problems.push('app.reset is { "post": url } or { "run": [command\u2026] }');
2633
+ if (c.app.start && !(Array.isArray(c.app.start) && c.app.start.length)) problems.push('app.start is a command, e.g. ["npm", "run", "demo"]');
2634
+ if (files) {
2635
+ if (c.app.guides && !existsSync5(c.app.guides)) problems.push(`no guides file ${c.app.guides}`);
2636
+ if (c.app.storageState && !existsSync5(c.app.storageState)) problems.push(`no storageState ${c.app.storageState}`);
2637
+ if (c.app.session && !existsSync5(c.app.session)) problems.push(`no session module ${c.app.session}`);
2638
+ }
2639
+ for (const [d, dir] of Object.entries(c.app.routes ?? {})) if (!existsSync5(dir)) problems.push(`app.routes ${d}: no folder ${dir}`);
2640
+ const lookNames = Object.keys(c.looks ?? {});
2641
+ if (!lookNames.length) problems.push('no looks: { "product": { "brand": "brands/acme.json" } }');
2642
+ for (const [k, l] of Object.entries(c.looks ?? {})) {
2643
+ if (!/^[a-z0-9-]+$/.test(k)) problems.push(`look ${k}: a name of a-z, 0-9 and -`);
2644
+ if (!existsSync5(l.brand)) problems.push(`look ${k}: no brand file ${l.brand}`);
2645
+ }
2646
+ const set = files ? guidesOf(c) : null;
2647
+ const ids = /* @__PURE__ */ new Set();
2648
+ for (const v of c.videos ?? []) {
2649
+ const at = `${v.id}:`;
2650
+ if (!/^[a-z0-9-]+$/.test(v.id ?? "")) problems.push(`bad video id ${v.id} (a-z, 0-9 and -)`);
2651
+ if (ids.has(v.id)) problems.push(`${at} id used twice`);
2652
+ ids.add(v.id);
2653
+ if (!CAMPAIGN_KINDS.includes(v.kind)) problems.push(`${at} kind is one of ${CAMPAIGN_KINDS.join(", ")}`);
2654
+ if (!v.guide === !v.director) problems.push(`${at} a guide or a director script (one of them)`);
2655
+ if (v.director && !existsSync5(v.director)) problems.push(`${at} no director script ${v.director}`);
2656
+ if (v.guide && files) {
2657
+ const g = guideOf(c, v, set);
2658
+ if (!g) problems.push(`${at} no guide ${v.guide}${/\.json$/i.test(v.guide) ? "" : c.app.guides ? ` in ${c.app.guides}` : " (no app.guides)"}`);
2659
+ else for (const [look, s] of Object.entries(v.voice ?? {})) {
2660
+ if (!existsSync5(s)) continue;
2661
+ const steps = g.trace.steps?.length ?? 0;
2662
+ const over = (JSON.parse(readFileSync8(s, "utf8")).lines ?? []).filter((l) => !(l.n >= 1 && l.n <= steps));
2663
+ if (over.length) problems.push(`${at} the ${look} script has line ${over.map((l) => l.n).join(", ")}, but the guide has ${steps} step(s)`);
2664
+ }
2665
+ }
2666
+ if (v.mode !== void 0 && v.mode !== "overlay" && v.mode !== "perform") problems.push(`${at} mode is overlay or perform`);
2667
+ if (v.director && v.mode) problems.push(`${at} a director video has no mode`);
2668
+ if (!v.alt?.trim()) problems.push(`${at} no alt text (what it shows)`);
2669
+ const looks = v.looks ?? lookNames.slice(0, 1);
2670
+ if (!looks.length || looks.some((l) => !lookNames.includes(l))) problems.push(`${at} looks are some of ${lookNames.join(", ") || "(none defined)"}`);
2671
+ if (v.kind === "docs-gif") {
2672
+ if (v.shapes) problems.push(`${at} a docs-gif has no shapes`);
2673
+ if (v.voice) problems.push(`${at} a GIF has no sound`);
2674
+ } else if (!v.shapes?.length || v.shapes.some((s) => !CAMPAIGN_SHAPES.includes(s))) problems.push(`${at} shapes are some of ${CAMPAIGN_SHAPES.join(", ")}`);
2675
+ for (const l of looks) {
2676
+ const s = v.voice?.[l];
2677
+ if (v.voice && !s) problems.push(`${at} a narrated video needs a script for each look (voice.${l})`);
2678
+ if (s && !existsSync5(s)) problems.push(`${at} no script ${s}`);
2679
+ }
2680
+ if (v.polish && !Array.isArray(v.polish)) problems.push(`${at} polish is a list of renderer flags`);
1748
2681
  }
1749
- const qa = o.qa ? await runQa(o.qa.ai, qaFrames, { title: o.qa.title, steps: o.qa.steps }) : void 0;
1750
- let narration;
1751
- if (said) {
1752
- const mp4 = outs.find((x) => x.format === "mp4");
1753
- const text = `${base(mp4.file)}.narration.txt`;
1754
- writeFileSync(text, narrationText(said.lines, titleMs));
1755
- narration = { lines: said.lines.map((l) => ({ ...l, start: l.start + titleMs })), holdMs: said.holds.reduce((a, h) => a + h.ms, 0), text, ...wav ? { wav } : {} };
2682
+ if (!ids.size) problems.push("no videos");
2683
+ return problems;
2684
+ }
2685
+ function readCampaign(file, o = {}) {
2686
+ const c = loadCampaign(file);
2687
+ const problems = checkCampaign(c, o);
2688
+ if (problems.length) throw new Error(`campaign ${c.product ?? c.file}: ${problems.join("; ")}`);
2689
+ return c;
2690
+ }
2691
+ function rendersOf(c) {
2692
+ const out = [];
2693
+ const first = Object.keys(c.looks)[0];
2694
+ for (const v of c.videos) {
2695
+ for (const look of v.looks ?? [first]) {
2696
+ if (v.kind === "docs-gif") {
2697
+ out.push({ id: `${v.id}--${look}`, video: v, look, phone: false, shapes: [], format: "gif", polish: [...v.polish ?? []] });
2698
+ continue;
2699
+ }
2700
+ const desk = (v.shapes ?? []).filter((s) => DESKTOP.includes(s));
2701
+ if (desk.length) out.push({ id: `${v.id}--${look}`, video: v, look, phone: false, shapes: desk, format: "mp4", polish: ["--scale", "2", "--captions", "vtt", "--poster", ...v.polish ?? []] });
2702
+ if (v.shapes?.includes("9:16")) out.push({ id: `${v.id}--${look}--phone`, video: v, look, phone: true, shapes: ["9:16"], format: "mp4", polish: ["--scale", "2", "--frame", "none", "--captions", "burn", "--poster", ...v.polish ?? []] });
2703
+ }
1756
2704
  }
1757
- const rel = (t) => Math.round(t - start);
1758
- const result = {
1759
- durationMs: Math.round(contentMs + titleMs + endMs),
1760
- offsetMs: titleMs,
1761
- rawMs: Math.round(end - start),
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 } : {} })),
1763
- events: cap.events.map((e) => ({ ...e, t: rel(e.t) })),
1764
- outputs,
1765
- ...poster ? { poster } : {},
1766
- ...vtt ? { vtt, chapters } : {},
1767
- ...qa ? { qa } : {},
1768
- ...narration ? { narration } : {},
1769
- ...warnings.length ? { warnings } : {}
2705
+ return out;
2706
+ }
2707
+ var shapeTag = (shape) => shape.replace(":", "x");
2708
+ function filesOf(r) {
2709
+ if (!r.shapes.length) return [{ key: r.format, name: `${r.id}.${r.format}`, format: r.format }];
2710
+ return r.shapes.map((s) => ({ key: `${r.format}@${s}`, name: `${r.id}-${shapeTag(s)}.${r.format}`, format: r.format, canvas: s }));
2711
+ }
2712
+ function endsWithOf(look, endTitle) {
2713
+ if (look.endsWith) return look.endsWith;
2714
+ const b = existsSync5(look.brand) ? JSON.parse(readFileSync8(look.brand, "utf8")) : {};
2715
+ const end = b.endCard;
2716
+ if (end && typeof end === "object") return [endTitle ?? end.title, end.url].filter(Boolean).join(" ") || null;
2717
+ if (typeof end === "string") return endTitle ?? end;
2718
+ const w = typeof b.watermark === "string" ? b.watermark : b.watermark?.text;
2719
+ return w ?? null;
2720
+ }
2721
+ function progressOf(out, ids, o = {}) {
2722
+ const file = join4(out, "progress.json");
2723
+ const was = !o.fresh && existsSync5(file) ? JSON.parse(readFileSync8(file, "utf8")) : null;
2724
+ const same2 = !!was && !was.finished && JSON.stringify([...was.ids].sort()) === JSON.stringify([...ids].sort());
2725
+ const p = same2 ? { ...was, failed: {}, current: null, resumed: (/* @__PURE__ */ new Date()).toISOString() } : { ids, started: (/* @__PURE__ */ new Date()).toISOString(), done: {}, failed: {}, current: null, finished: null };
2726
+ mkdirSync4(out, { recursive: true });
2727
+ const save = () => writeFileSync4(file, `${JSON.stringify(p, null, 2)}
2728
+ `);
2729
+ save();
2730
+ return {
2731
+ file,
2732
+ resumed: same2,
2733
+ isDone: (id) => Boolean(p.done[id]),
2734
+ start(id, n, of) {
2735
+ p.current = { id, n, of, since: (/* @__PURE__ */ new Date()).toISOString() };
2736
+ save();
2737
+ },
2738
+ done(id) {
2739
+ p.done[id] = (/* @__PURE__ */ new Date()).toISOString();
2740
+ delete p.failed[id];
2741
+ p.current = null;
2742
+ save();
2743
+ },
2744
+ fail(id, why) {
2745
+ p.failed[id] = why;
2746
+ p.current = null;
2747
+ save();
2748
+ },
2749
+ finish() {
2750
+ p.finished = (/* @__PURE__ */ new Date()).toISOString();
2751
+ p.current = null;
2752
+ save();
2753
+ },
2754
+ get state() {
2755
+ return p;
2756
+ }
1770
2757
  };
1771
- if (o.timeline) {
1772
- mkdirSync(dirname3(o.timeline) || ".", { recursive: true });
1773
- writeFileSync(o.timeline, JSON.stringify(result, null, 2));
2758
+ }
2759
+ function statusOf(c, now = Date.now()) {
2760
+ const file = join4(c.out, "progress.json");
2761
+ if (!existsSync5(file)) return `${c.product}: no make run yet`;
2762
+ const p = JSON.parse(readFileSync8(file, "utf8"));
2763
+ const done = p.ids.filter((id) => p.done[id]);
2764
+ const mins = (t) => `${Math.round((now - Date.parse(t)) / 6e4)} min`;
2765
+ return [
2766
+ `${c.product}: ${done.length} of ${p.ids.length} made${p.finished ? ` \u2014 finished ${mins(p.finished)} ago` : ""} (started ${mins(p.started)} ago${p.resumed ? `, carried on ${mins(p.resumed)} ago` : ""})`,
2767
+ ...p.current ? [` now: [${p.current.n}/${p.current.of}] ${p.current.id}, for ${mins(p.current.since)}`] : [],
2768
+ ...p.ids.map((id) => ` ${p.done[id] ? "\u2713" : p.failed[id] ? "\u2717" : p.current?.id === id ? "\u2026" : "\xB7"} ${id}${p.failed[id] ? ` \u2014 ${p.failed[id]}` : ""}`)
2769
+ ].join("\n");
2770
+ }
2771
+ var reachable = async (url) => {
2772
+ try {
2773
+ return (await fetch(url)).ok;
2774
+ } catch {
2775
+ return false;
1774
2776
  }
1775
- return result;
2777
+ };
2778
+ var sleep4 = (ms) => new Promise((r) => {
2779
+ setTimeout(r, ms);
2780
+ });
2781
+ async function ensureApp(app, start, log = () => {
2782
+ }) {
2783
+ const ready = `${app.url.replace(/\/$/, "")}${app.ready ?? "/"}`;
2784
+ if (await reachable(ready)) return () => {
2785
+ };
2786
+ if (!start || !app.start?.length) throw new Error(`the app is not serving at ${ready}${app.start?.length ? `: run \`${app.start.join(" ")}\` in ${app.dir}, or pass --start` : ""}`);
2787
+ log(`starting the app: ${app.start.join(" ")} (in ${app.dir}) \u2026`);
2788
+ const child = spawn2(app.start[0], app.start.slice(1), { cwd: app.dir, stdio: ["ignore", "pipe", "inherit"] });
2789
+ let exited = null;
2790
+ let said = false;
2791
+ child.on("exit", (code) => {
2792
+ exited = code ?? -1;
2793
+ });
2794
+ child.stdout.on("data", (d) => {
2795
+ process.stdout.write(d);
2796
+ if (app.readyText && String(d).includes(app.readyText)) said = true;
2797
+ });
2798
+ const until = Date.now() + 6e5;
2799
+ for (; ; ) {
2800
+ if (exited !== null) throw new Error(`the app exited (${exited}) before it was ready`);
2801
+ if (app.readyText ? said : await reachable(ready)) break;
2802
+ if (Date.now() > until) {
2803
+ child.kill("SIGTERM");
2804
+ throw new Error("the app did not start in 10 minutes");
2805
+ }
2806
+ await sleep4(500);
2807
+ }
2808
+ return () => {
2809
+ child.kill("SIGTERM");
2810
+ };
1776
2811
  }
1777
- function namedChapters(names, events, segs, endMs) {
1778
- const starts = names.flatMap((c) => {
1779
- const e = events.find((x) => x.type === "step" && x.index === c.index);
1780
- const t = e ? outputAt(segs, e.t) : null;
1781
- return t === null ? [] : [{ t: c.index === names[0].index ? 0 : t, text: c.name }];
1782
- }).sort((a, b) => a.t - b.t);
1783
- return starts.map((c, k) => ({ start: c.t, end: starts[k + 1]?.t ?? endMs, text: c.text }));
2812
+ async function resetFor(app, body) {
2813
+ if (!app.reset) return;
2814
+ if ("post" in app.reset) {
2815
+ const r = await fetch(app.reset.post, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ...app.reset.body ?? {}, ...body }) }).catch((e) => e);
2816
+ if (r instanceof Error || !r.ok) throw new Error(`the app did not reset (${app.reset.post}: ${r instanceof Error ? r.message : r.status})`);
2817
+ return;
2818
+ }
2819
+ const run = app.reset.run;
2820
+ const code = await new Promise((done) => {
2821
+ const p = spawn2(run[0], run.slice(1), { cwd: app.dir, stdio: "inherit", env: { ...process.env, TRACE_AVATAR_RESET: JSON.stringify(body) } });
2822
+ p.on("exit", (c) => done(c ?? -1));
2823
+ p.on("error", () => done(-1));
2824
+ });
2825
+ if (code !== 0) throw new Error(`the app did not reset (${run.join(" ")} exited ${code})`);
1784
2826
  }
1785
- function badgeAt(W, H, w, h, at = "bottom-right") {
1786
- const m = Math.round(Math.min(W, H) * 0.025);
1787
- return { x: at.endsWith("left") ? m : W - w - m, y: at.startsWith("top") ? m : H - h - m };
2827
+ async function sessionFn(app) {
2828
+ if (!app.session) return null;
2829
+ const m = await import(pathToFileURL4(app.session).href);
2830
+ if (typeof m.storageStateFor !== "function") throw new Error(`${app.session} has no storageStateFor(url, options)`);
2831
+ return m.storageStateFor;
1788
2832
  }
1789
- async function artFor(layers, layout, o) {
1790
- const art = { base: null, captions: /* @__PURE__ */ new Map(), mid: [] };
1791
- if (!layers) return art;
1792
- if (o.frameStyle !== "none" || layout.canvas) {
1793
- art.base = /* @__PURE__ */ new Map();
1794
- for (const url of o.urls.length ? o.urls : ["/"]) art.base.set(url, await layers.base(layout, { background: o.background, path: url, title: o.titles[url] }));
2833
+ async function voiceFor(spec, log) {
2834
+ if (!spec) return null;
2835
+ const v = typeof spec === "function" ? spec : await voiceOf(spec);
2836
+ try {
2837
+ await v("This is a short check that the voice can be reached.");
2838
+ } catch (e) {
2839
+ throw new Error(`the voice is not reachable (${e.message}); nothing was filmed`);
1795
2840
  }
1796
- const fontPx = layout.canvas ? Math.max(12, Math.round(layout.width * 0.034)) : Math.max(12, Math.round(layout.content.w * 0.026));
1797
- const maxWidth = Math.round(layout.canvas ? layout.width * 0.9 : layout.content.w * 0.8);
1798
- for (const c of o.cues) {
1799
- if (!art.captions.has(c.text)) art.captions.set(c.text, await layers.caption(c.text, { maxWidth, fontPx }));
2841
+ log(`voice: ${typeof spec === "string" ? spec : "given"}`);
2842
+ return v;
2843
+ }
2844
+ async function makeCampaign(c, o = {}) {
2845
+ const log = o.log ?? console.log;
2846
+ const only = o.only ?? [];
2847
+ const all = rendersOf(c);
2848
+ const hit = (r, id) => r.video.id === id || r.id === id;
2849
+ const unknown = only.filter((id) => !all.some((r) => hit(r, id)));
2850
+ if (unknown.length) throw new Error(`no such video: ${unknown.join(", ")}`);
2851
+ const renders = only.length ? all.filter((r) => only.some((id) => hit(r, id))) : all;
2852
+ mkdirSync4(join4(c.out, "work"), { recursive: true });
2853
+ if (renders.some((r) => r.format === "mp4")) {
2854
+ const ff = findFfmpeg();
2855
+ if (!ff) throw new Error(`${FFMPEG_MISSING} Nothing was captured.`);
2856
+ process.env.FFMPEG = ff;
1800
2857
  }
1801
- if (o.cards?.title) art.title = await layers.card(layout, { ...o.cards.title, background: o.background });
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 }));
1804
- if (o.mark) {
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 } : {} });
1806
- const { x, y } = badgeAt(layout.width, layout.height, img.width, img.height, o.mark.at);
1807
- art.badge = { img, x, y, alpha: o.mark.opacity ?? 0.9 };
1808
- for (const k of ["title", "end"]) {
1809
- const c = art[k];
1810
- if (c) {
1811
- const d = copy(c);
1812
- overlay(d, img, x, y, art.badge.alpha);
1813
- art[k] = d;
2858
+ const narrated = renders.some((r) => r.video.voice);
2859
+ const spec = o.voice ?? process.env.TRACE_AVATAR_VOICE ?? c.narrator;
2860
+ const voice = narrated ? await voiceFor(spec, log) : null;
2861
+ if (narrated && !voice) log("no voice (--voice, TRACE_AVATAR_VOICE or the campaign's narrator): narrated videos are made without narration");
2862
+ const manifest = join4(c.out, "made.json");
2863
+ const made = existsSync5(manifest) ? JSON.parse(readFileSync8(manifest, "utf8")) : {};
2864
+ const failed = [];
2865
+ const progress = progressOf(c.out, renders.map((r) => r.id), { fresh: o.fresh });
2866
+ if (progress.resumed) log(`carrying on a run that stopped: ${renders.filter((r) => progress.isDone(r.id)).length} of ${renders.length} already made (--fresh to start over) \u2014 progress in ${progress.file}`);
2867
+ else log(`${renders.length} render(s) \u2014 progress in ${progress.file}`);
2868
+ const fail = (id, why) => {
2869
+ failed.push(`${id}: ${why}`);
2870
+ progress.fail(id, why);
2871
+ log(`${id}: \u2717 ${why}`);
2872
+ };
2873
+ let stop = null;
2874
+ const session = await sessionFn(c.app);
2875
+ try {
2876
+ for (const [i, r] of renders.entries()) {
2877
+ const tag = `[${i + 1}/${renders.length}]`;
2878
+ if (progress.isDone(r.id)) {
2879
+ log(`${tag} ${r.id}: made earlier in this run \u2014 kept`);
2880
+ continue;
2881
+ }
2882
+ log(`${tag} ${r.id} \u2026`);
2883
+ progress.start(r.id, i + 1, renders.length);
2884
+ stop ??= await ensureApp(c.app, !!o.start, log);
2885
+ const v = r.video;
2886
+ const outs = filesOf(r);
2887
+ const outBase = join4(c.out, r.id);
2888
+ const firstBase = join4(c.out, outs[0].name.replace(/\.[^.]+$/, ""));
2889
+ for (const b of [outBase, firstBase]) for (const ext of ["vtt", "chapters.vtt", "png", "scenes.json"]) rmSync3(`${b}.${ext}`, { force: true });
2890
+ const look = c.looks[r.look];
2891
+ const script = v.voice?.[r.look];
2892
+ const speak = !!(v.voice && voice);
2893
+ let traceFile = "";
2894
+ try {
2895
+ await resetFor(c.app, v.reset ?? {});
2896
+ let width;
2897
+ let height;
2898
+ let seconds;
2899
+ let spoke = false;
2900
+ if (v.director) {
2901
+ const res = await direct({
2902
+ id: r.id,
2903
+ script: v.director,
2904
+ url: c.app.url,
2905
+ page: v.page ?? "/",
2906
+ appName: c.app.name ?? "",
2907
+ out: outs.map((x) => ({ file: join4(c.out, x.name), format: x.format, ...x.canvas ? { canvas: x.canvas } : {}, ...x.format === "gif" ? { width: v.width ?? 800 } : {} })),
2908
+ look: lookOptions({ title: v.title, endTitle: v.endTitle, polish: r.polish }, look.brand, c.app.name ?? ""),
2909
+ ...r.phone ? { viewport: { width: 390, height: 844 } } : {},
2910
+ ...session ? { session } : c.app.storageState ? { session: c.app.storageState } : {},
2911
+ ...v.session ? { sessionOptions: v.session } : {},
2912
+ ...v.signedIn === false ? { signedOut: true } : {},
2913
+ ...c.app.alias ? { alias: c.app.alias } : {},
2914
+ ...c.app.routes ? { routes: c.app.routes } : {},
2915
+ ...speak ? { voice, ...script ? { voiceScript: script } : {} } : {},
2916
+ scenesFile: `${outBase}.scenes.json`,
2917
+ headless: !v.headed,
2918
+ ...v.launchArgs ? { launchArgs: v.launchArgs } : {},
2919
+ ...v.tailMs !== void 0 ? { tailMs: v.tailMs } : {},
2920
+ log
2921
+ });
2922
+ ({ width, height } = res.outputs[0]);
2923
+ seconds = Math.round(res.durationMs / 100) / 10;
2924
+ spoke = res.narrated;
2925
+ for (const w of res.warnings ?? []) log(`${r.id}: ${w}`);
2926
+ } else {
2927
+ const g = guideOf(c, v);
2928
+ if (!g) throw new Error(`no guide ${v.guide}`);
2929
+ const trace = join4(c.out, "work", `${r.id}.trace.json`);
2930
+ writeFileSync4(trace, JSON.stringify(g.trace, null, 2));
2931
+ traceFile = trace;
2932
+ let storageState = c.app.storageState;
2933
+ if (!storageState && session) {
2934
+ storageState = join4(c.out, "work", `${r.id}.session.json`);
2935
+ writeFileSync4(storageState, JSON.stringify(await session(c.app.url, v.session ?? {})));
2936
+ }
2937
+ const args = [trace, "--url", `${c.app.url.replace(/\/$/, "")}${g.page}`, "--navigate", "--brand", look.brand];
2938
+ if (storageState) args.push("--storage-state", storageState);
2939
+ if (r.phone) args.push("--viewport", PHONE);
2940
+ if (r.format === "gif") args.push("--width", String(v.width ?? 800));
2941
+ if (v.mode === "perform") args.push("--mode", "perform", "--allow-perform");
2942
+ for (const [name, text] of Object.entries(v.values ?? {})) args.push("--value", `${name}=${text}`);
2943
+ args.push(...r.polish);
2944
+ if (speak && script) args.push("--voice", "given", "--script", script);
2945
+ for (const x of outs) args.push("--out", `${join4(c.out, x.name)}${x.canvas ? `@${x.canvas}` : ""}`);
2946
+ const p = parse(args);
2947
+ const res = await render({ ...p.options, ...speak ? { voice } : {} });
2948
+ ({ width, height } = res.outputs[0]);
2949
+ seconds = Math.round(res.durationMs / 100) / 10;
2950
+ spoke = !!res.narration?.lines.length;
2951
+ for (const w of res.warnings ?? []) log(`${r.id}: ${w}`);
2952
+ }
2953
+ const files = {};
2954
+ for (const x of outs) files[x.key] = x.name;
2955
+ if (existsSync5(`${firstBase}.png`)) files.poster = `${outs[0].name.replace(/\.[^.]+$/, "")}.png`;
2956
+ if (existsSync5(`${firstBase}.vtt`)) files.vtt = `${outs[0].name.replace(/\.[^.]+$/, "")}.vtt`;
2957
+ made[r.id] = { files, width, height, seconds, narrated: spoke, video: v.id, look: r.look, at: (/* @__PURE__ */ new Date()).toISOString() };
2958
+ writeFileSync4(manifest, `${JSON.stringify(made, null, 2)}
2959
+ `);
2960
+ log(`${r.id}: \u2713 ${Object.values(files).join(", ")}`);
2961
+ progress.done(r.id);
2962
+ } catch (e) {
2963
+ if (e instanceof RenderError) {
2964
+ const rep = reportOf(e, traceFile);
2965
+ fail(r.id, `${rep.outcome}${rep.step !== null ? ` at step ${rep.step + 1}` : ""}: ${String(rep.message).split("\n")[0]}`);
2966
+ } else fail(r.id, String(e.message).split("\n")[0]);
1814
2967
  }
1815
2968
  }
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
- });
2969
+ if (!failed.length) progress.finish();
2970
+ } finally {
2971
+ stop?.();
1821
2972
  }
1822
- return art;
2973
+ return { made, failed };
2974
+ }
2975
+ function saysOf(c, renderId) {
2976
+ const file = join4(c.out, `${renderId}.scenes.json`);
2977
+ if (!existsSync5(file)) return null;
2978
+ const lines = JSON.parse(readFileSync8(file, "utf8")).map((x) => String(x.caption ?? "").trim()).filter(Boolean);
2979
+ return lines.length ? lines : null;
1823
2980
  }
1824
2981
 
1825
- // src/voice.ts
1826
- import { spawnSync as spawnSync2 } from "child_process";
1827
- import { createHash } from "crypto";
1828
- import { existsSync as existsSync2, mkdirSync as mkdirSync2, mkdtempSync as mkdtempSync2, readFileSync as readFileSync6, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
1829
- import { tmpdir as tmpdir2 } from "os";
1830
- import { join as join3, resolve as resolve3 } from "path";
1831
- import { pathToFileURL as pathToFileURL2 } from "url";
1832
- var GEMINI_TTS = { model: "gemini-2.5-flash-preview-tts", voice: "Kore" };
1833
- var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
1834
- async function post(f, url, headers, body) {
1835
- for (let n = 1; ; n += 1) {
1836
- let res = null;
1837
- try {
1838
- res = await f(url, { method: "POST", headers: { "content-type": "application/json", ...headers }, body: JSON.stringify(body) });
1839
- } catch (e) {
1840
- if (n >= 3) throw new Error(`could not reach the voice (${e.message})`);
2982
+ // src/cli.ts
2983
+ var USAGE = `Usage: trace-avatar-render <trace.json> --url <page> --out <file.gif|file.mp4> [options]
2984
+
2985
+ --url <url> the page the guide starts on (required)
2986
+ --out <file> .gif or .mp4; repeat for several (required). <file>@<shape> gives that output its own
2987
+ canvas (e.g. --out wide.mp4@16:9 --out square.mp4@1:1): several shapes from one capture
2988
+ --mode <overlay|perform> Show me (default) or Do it for me
2989
+ --allow-perform needed for perform: it clicks and types for real (use a sandbox account)
2990
+ --width <px> output width (GIF default 800, MP4 the capture's)
2991
+ --fps <n> frames per second (GIF default 12, MP4 30)
2992
+ --viewport <WxH> default: the trace's meta.viewport, else 1280x800
2993
+ --scale <n> device pixel ratio of the capture (2 for crisp video)
2994
+ --storage-state <file> a signed-in Playwright session
2995
+ --max-wait <ms> waits longer than this are cut to it (default 800, 0 keeps them)
2996
+ --hide <selector> hidden before capture; repeatable
2997
+ --blur <selector> blurred before capture (as well as [data-trace-blur]); repeatable
2998
+ --allow-stall render a stalled guide anyway instead of failing
2999
+ --navigate a step on another page: load that page, as the app's router would (without it, a
3000
+ Show me guide that crosses pages waits on "Open \u2026 to continue")
3001
+ --security [guards] perform: leave these to the viewer (a hand-off): all, or secrets,money,files
3002
+ --value <name=text> perform: a value to type, by name or field label (e.g. password=demo-pass); repeatable
3003
+ --player <file> the trace-perform.min.js to use (default: the installed trace-avatar)
3004
+ --timeline <file> write the timeline and the cuts as JSON
3005
+ --timeout <ms> give up after this long (default 120000)
3006
+ --report <file> write what happened as JSON: { outcome: passed|stalled|failed, step, reason, message }
3007
+ (for CI: one result per guide, whatever the exit code)
3008
+ --headed show the browser
3009
+
3010
+ Polish (all off by default):
3011
+ --frame <none|browser> a browser window around the app, on a background
3012
+ --background <css> the background behind the window and on the cards
3013
+ --camera zoom in on each action and pan between close ones
3014
+ --zoom <n> how far the camera goes in (default 1.6; implies --camera)
3015
+ --captions <burn|vtt|both> burn the steps' words in, write <out>.vtt + <out>.chapters.vtt, or both
3016
+ --captions-at <top|bottom> where burned-in captions sit (default bottom; top when the app's own UI is low)
3017
+ --poster [file] a PNG at the first click (default <out>.png)
3018
+ --title-card [title] a 1.5 s card first (default: the trace's title)
3019
+ --end-card [title] a 2 s card last (default: "Done")
3020
+ --canvas <shape> compose onto 9:16 (1080x1920), 4:5, 1:1, 16:9 or WxH: the app between safe margins on the
3021
+ background, for Reels, Stories and feeds (--width scales the whole canvas)
3022
+ --watermark <text> a small badge on every frame, cards too, e.g. "Created with TraceAvatar \xB7 traceavatar.com"
3023
+ --watermark-at <corner> top-left, top-right, bottom-left or bottom-right (default)
3024
+ --brand <file.json> the look in one file: canvas, watermark, frame, background, camera, captions, captionsAt,
3025
+ titleCard, endCard ({ title, url, logo, color }); flags given here win over it
3026
+
3027
+ AI (nothing calls a model without --ai):
3028
+ --ai <provider> gateway: our AI gateway (AI_GATEWAY_URL, AI_GATEWAY_KEY), DeepSeek first, then Gemini,
3029
+ then OpenAI; or gateway:<provider>[/<model>][,<provider>\u2026]; openai:<model> (OPENAI_API_KEY,
3030
+ OPENAI_BASE_URL for any OpenAI-compatible server); or ./provider.js
3031
+ --ai-vision <model> the model for --qa's frames (gateway's DeepSeek default: deepseek-flash)
3032
+ --qa [strict] send a frame per step to the AI to look for errors, empty states, a stall, personal
3033
+ data; strict exits 1 when anything is flagged (needs a vision model)
3034
+ --alt write <out>.alt.txt; with --captions vtt, AI names the chapters
3035
+ --repair when a step can't find its element, or a wait's text never shows, propose a fix in
3036
+ <out>.repair.json (verified by playing again); still exits 1. With --ai, unsure
3037
+ cases are asked (DeepSeek first)
3038
+ --repair-vision with --repair and --ai: send a screenshot of the stalled page too (elements only)
3039
+
3040
+ Narration (MP4 only; nothing speaks without --voice):
3041
+ --voice <voice> gateway (our AI gateway: Gemini speech, AI_GATEWAY_URL/KEY), gateway:gemini/<model>:<voice>,
3042
+ openai:<model>[:<voice>] (OPENAI_API_KEY / OPENAI_BASE_URL), say[:<voice>] (macOS, offline),
3043
+ or ./voice.js. Each step's caption is spoken; the video holds where a line runs long
3044
+ --script <file.json> the spoken lines instead: { "lines": [{ "n": 1, "text": "\u2026" }] }
3045
+ --voice-out <file.wav> also write the narration track
3046
+ --voice-strict fail when a line needs a hold longer than 8 s
3047
+ --no-voice-cache don't keep spoken lines in .trace-avatar-cache/voice
3048
+
3049
+ Suggestions for a person to accept (the renderer never changes a trace):
3050
+ trace-avatar-render suggest <trace.json> --task captions|title|waits|narration --ai <provider> [--tone friendly|terse|formal]
3051
+ [--hints hints.json] [--out suggestions.json]
3052
+ trace-avatar-render apply <trace.json> <suggestions.json> --accept 1,3|all --out <new.trace.json>
3053
+
3054
+ A product's marketing videos from one campaign.json (every look and shape; progress kept, a stopped run carries on):
3055
+ trace-avatar-render campaign check [campaign.json] every problem at once
3056
+ trace-avatar-render campaign make [campaign.json] [video ids\u2026] [--start] [--fresh] [--voice <voice>]
3057
+ trace-avatar-render campaign status [campaign.json] done, failed, and what it's on now
3058
+
3059
+ A clip catalogue (trace-avatar-catalogue/1, schemas/catalogue-1.json):
3060
+ trace-avatar-render catalogue check <file.json|https://\u2026> [--fetch] [--json]
3061
+ --fetch: fetch every link too (reachable, its type, captions within the video, mp4 head)
3062
+ --allow-http: accept http:// links (a local test server)
3063
+ `;
3064
+ function parse(argv) {
3065
+ const extra = {};
3066
+ const flags = { "--poster": "poster", "--title-card": "title", "--end-card": "end", "--qa": "qa" };
3067
+ const rest = [];
3068
+ for (let k = 0; k < argv.length; k += 1) {
3069
+ const a = argv[k];
3070
+ const eq = a.indexOf("=");
3071
+ const name = eq > 0 ? a.slice(0, eq) : a;
3072
+ if (flags[name]) {
3073
+ if (eq > 0) extra[flags[name]] = a.slice(eq + 1);
3074
+ else if (argv[k + 1] !== void 0 && !argv[k + 1].startsWith("-") && !/\.json$/i.test(argv[k + 1]) && (flags[name] !== "qa" || argv[k + 1] === "strict")) {
3075
+ extra[flags[name]] = argv[k + 1];
3076
+ k += 1;
3077
+ } else extra[flags[name]] = true;
3078
+ continue;
1841
3079
  }
1842
- if (res?.ok) return res;
1843
- if (res) {
1844
- const text = await res.text();
1845
- let gw = null;
1846
- try {
1847
- const j = JSON.parse(text);
1848
- if (j?.error?.source === "ai-interface") gw = j.error;
1849
- } catch {
1850
- }
1851
- if (gw) throw new Error(`the AI gateway refused the voice call: ${gw.message}`);
1852
- if (!(res.status === 429 || res.status >= 500) || n >= 3) throw new Error(`the voice call failed (${res.status}): ${text.slice(0, 300)}`);
3080
+ rest.push(a);
3081
+ }
3082
+ const { values, positionals } = parseArgs({
3083
+ args: rest,
3084
+ allowPositionals: true,
3085
+ options: {
3086
+ url: { type: "string" },
3087
+ out: { type: "string", multiple: true },
3088
+ mode: { type: "string" },
3089
+ "allow-perform": { type: "boolean" },
3090
+ width: { type: "string" },
3091
+ fps: { type: "string" },
3092
+ viewport: { type: "string" },
3093
+ scale: { type: "string" },
3094
+ "storage-state": { type: "string" },
3095
+ "max-wait": { type: "string" },
3096
+ hide: { type: "string", multiple: true },
3097
+ blur: { type: "string", multiple: true },
3098
+ "allow-stall": { type: "boolean" },
3099
+ navigate: { type: "boolean" },
3100
+ security: { type: "string" },
3101
+ value: { type: "string", multiple: true },
3102
+ player: { type: "string" },
3103
+ timeline: { type: "string" },
3104
+ timeout: { type: "string" },
3105
+ headed: { type: "boolean" },
3106
+ help: { type: "boolean", short: "h" },
3107
+ frame: { type: "string" },
3108
+ background: { type: "string" },
3109
+ camera: { type: "boolean" },
3110
+ zoom: { type: "string" },
3111
+ captions: { type: "string" },
3112
+ "captions-at": { type: "string" },
3113
+ ai: { type: "string" },
3114
+ "ai-vision": { type: "string" },
3115
+ alt: { type: "boolean" },
3116
+ voice: { type: "string" },
3117
+ script: { type: "string" },
3118
+ "voice-out": { type: "string" },
3119
+ "voice-strict": { type: "boolean" },
3120
+ "no-voice-cache": { type: "boolean" },
3121
+ repair: { type: "boolean" },
3122
+ "repair-vision": { type: "boolean" },
3123
+ report: { type: "string" },
3124
+ canvas: { type: "string" },
3125
+ watermark: { type: "string" },
3126
+ "watermark-at": { type: "string" },
3127
+ brand: { type: "string" }
1853
3128
  }
1854
- await sleep2(Math.min(400 * 2 ** (n - 1) * (0.5 + Math.random() / 2), 4e3));
3129
+ });
3130
+ if (values.help) throw new UsageError("");
3131
+ const trace = positionals[0];
3132
+ if (!trace) throw new UsageError("a trace file is needed");
3133
+ if (positionals.length > 1) throw new UsageError(`one trace at a time (got ${positionals.join(", ")})`);
3134
+ if (!values.url) throw new UsageError("--url is needed");
3135
+ if (!values.out?.length) throw new UsageError("--out is needed");
3136
+ const num = (name, v, min = 0) => {
3137
+ if (v === void 0) return void 0;
3138
+ const n = Number(v);
3139
+ if (!Number.isFinite(n) || n < min) throw new UsageError(`--${name} must be a number \u2265 ${min}`);
3140
+ return n;
3141
+ };
3142
+ const mode = values.mode ?? "overlay";
3143
+ if (mode !== "overlay" && mode !== "perform") throw new UsageError("--mode is overlay or perform");
3144
+ let viewport;
3145
+ if (values.viewport) {
3146
+ const m = /^(\d+)x(\d+)$/i.exec(values.viewport);
3147
+ if (!m) throw new UsageError("--viewport is WIDTHxHEIGHT, e.g. 1280x800");
3148
+ viewport = { w: Number(m[1]), h: Number(m[2]) };
1855
3149
  }
1856
- }
1857
- function geminiVoice(o) {
1858
- const model = o.model ?? GEMINI_TTS.model;
1859
- return async (text) => {
1860
- const res = await post(
1861
- o.fetch ?? fetch,
1862
- `${o.url.replace(/\/+$/, "")}/models/${model}:generateContent`,
1863
- { ...o.bearer ? { authorization: `Bearer ${o.key}` } : { "x-goog-api-key": o.key }, ...o.headers },
1864
- {
1865
- contents: [{ role: "user", parts: [{ text }] }],
1866
- generationConfig: { responseModalities: ["AUDIO"], speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: o.voice ?? GEMINI_TTS.voice } } } }
1867
- }
1868
- );
1869
- const json = await res.json();
1870
- const part = json.candidates?.[0]?.content?.parts?.find((p) => p.inlineData?.data || p.inline_data?.data);
1871
- const data = part?.inlineData?.data ?? part?.inline_data?.data;
1872
- if (!data) throw new Error(`${model} answered without audio`);
1873
- const mime = part?.inlineData?.mimeType ?? part?.inline_data?.mime_type ?? "";
1874
- const rate = Number(/rate=(\d+)/.exec(mime)?.[1] ?? 24e3);
1875
- return { pcm: fromS16le(new Uint8Array(Buffer.from(data, "base64"))), sampleRate: rate };
3150
+ if (values.frame && values.frame !== "none" && values.frame !== "browser") throw new UsageError("--frame is none or browser");
3151
+ const captions = values.captions;
3152
+ if (captions !== void 0 && captions !== "burn" && captions !== "vtt" && captions !== "both") throw new UsageError("--captions is burn, vtt or both");
3153
+ const captionsAt = values["captions-at"];
3154
+ if (captionsAt !== void 0 && captionsAt !== "top" && captionsAt !== "bottom") throw new UsageError("--captions-at is top or bottom");
3155
+ const zoom = num("zoom", values.zoom, 1);
3156
+ if (extra.qa !== void 0 && extra.qa !== true && extra.qa !== "strict") throw new UsageError("--qa takes nothing or strict");
3157
+ if ((extra.qa !== void 0 || values.alt || values["ai-vision"]) && !values.ai) throw new UsageError("--qa, --alt and --ai-vision need --ai");
3158
+ if (values["repair-vision"] && !(values.repair && values.ai)) throw new UsageError("--repair-vision needs --repair and --ai");
3159
+ if ((values.script || values["voice-out"] || values["voice-strict"] || values["no-voice-cache"]) && !values.voice) throw new UsageError("--script, --voice-out, --voice-strict and --no-voice-cache need --voice");
3160
+ if (values.voice && !values.out.some((f) => /\.mp4(@.*)?$/i.test(f))) throw new UsageError("--voice needs an .mp4 output (a GIF has no sound)");
3161
+ let security;
3162
+ if (values.security !== void 0) {
3163
+ const s = values.security.trim().toLowerCase();
3164
+ const guards = s === "" || s === "all" || s === "true" ? true : s.split(/[\s,]+/).filter(Boolean);
3165
+ if (Array.isArray(guards) && guards.some((g) => !["secrets", "money", "files"].includes(g))) throw new UsageError("--security is all, or a list of secrets, money, files");
3166
+ security = guards;
3167
+ }
3168
+ const typed = {};
3169
+ for (const v of values.value ?? []) {
3170
+ const k = v.indexOf("=");
3171
+ if (k < 1) throw new UsageError("--value is name=text, e.g. password=demo-pass");
3172
+ typed[v.slice(0, k)] = v.slice(k + 1);
3173
+ }
3174
+ if ((security !== void 0 || values.value?.length) && mode !== "perform") throw new UsageError("--security and --value are for --mode perform");
3175
+ const tryUsage = (f) => {
3176
+ try {
3177
+ return f();
3178
+ } catch (e) {
3179
+ throw new UsageError(e.message);
3180
+ }
1876
3181
  };
1877
- }
1878
- function openAiVoice(o) {
1879
- return async (text) => {
1880
- const res = await post(
1881
- o.fetch ?? fetch,
1882
- `${o.baseUrl.replace(/\/+$/, "")}/audio/speech`,
1883
- o.key ? { authorization: `Bearer ${o.key}` } : {},
1884
- { model: o.model, voice: o.voice ?? "alloy", input: text, response_format: "pcm" }
1885
- );
1886
- return { pcm: fromS16le(new Uint8Array(await res.arrayBuffer())), sampleRate: 24e3 };
3182
+ if (values.canvas !== void 0) tryUsage(() => canvasOf(values.canvas));
3183
+ for (const o of values.out ?? []) {
3184
+ const m = /^.+\.(?:gif|mp4)@(.+)$/i.exec(o);
3185
+ if (m) tryUsage(() => canvasOf(m[1]));
3186
+ }
3187
+ const at = values["watermark-at"];
3188
+ if (at !== void 0 && !CORNERS.includes(at)) throw new UsageError(`--watermark-at is ${CORNERS.join(", ")}`);
3189
+ const brand = values.brand !== void 0 ? tryUsage(() => brandFile(values.brand)) : {};
3190
+ let watermark = values.watermark !== void 0 ? tryUsage(() => watermarkOf(values.watermark)) : brand.watermark;
3191
+ if (at !== void 0) {
3192
+ if (watermark === void 0) throw new UsageError("--watermark-at needs a watermark (--watermark, or one in --brand)");
3193
+ watermark = { ...typeof watermark === "string" ? { text: watermark } : watermark, at };
3194
+ }
3195
+ const width = num("width", values.width, 16);
3196
+ const fps = num("fps", values.fps, 1);
3197
+ const maxWait = num("max-wait", values["max-wait"]);
3198
+ return {
3199
+ trace,
3200
+ options: {
3201
+ // The brand first: the flags below win over it.
3202
+ ...brand,
3203
+ trace,
3204
+ url: values.url,
3205
+ mode,
3206
+ allowPerform: !!values["allow-perform"],
3207
+ out: values.out.map((spec) => {
3208
+ const m = /^(.+\.(?:gif|mp4))@(.+)$/i.exec(spec);
3209
+ const file = m ? m[1] : spec;
3210
+ return { file, ...width ? { width } : {}, ...fps ? { fps } : {}, ...m ? { canvas: m[2] } : {} };
3211
+ }),
3212
+ ...viewport ? { viewport } : {},
3213
+ ...values.scale ? { scale: num("scale", values.scale, 1) } : {},
3214
+ ...values["storage-state"] ? { storageState: values["storage-state"] } : {},
3215
+ ...maxWait !== void 0 ? { cuts: { maxWaitMs: maxWait } } : {},
3216
+ ...values.hide ? { hide: values.hide } : {},
3217
+ ...values.blur ? { blur: values.blur } : {},
3218
+ allowStall: !!values["allow-stall"],
3219
+ ...values.navigate ? { navigate: true } : {},
3220
+ ...security !== void 0 ? { security } : {},
3221
+ ...values.value?.length ? { values: typed } : {},
3222
+ ...values.player ? { player: values.player } : {},
3223
+ ...values.timeline ? { timeline: values.timeline } : {},
3224
+ ...values.timeout ? { timeoutMs: num("timeout", values.timeout, 1) } : {},
3225
+ headless: !values.headed,
3226
+ ...values.frame ? { frame: values.frame } : {},
3227
+ ...values.background ? { background: values.background } : {},
3228
+ ...zoom ? { camera: { zoom } } : values.camera ? { camera: true } : {},
3229
+ ...captions ? { captions } : {},
3230
+ ...captionsAt ? { captionsAt } : {},
3231
+ ...extra.poster !== void 0 ? { poster: extra.poster } : {},
3232
+ ...extra.title !== void 0 ? { titleCard: extra.title } : {},
3233
+ ...extra.end !== void 0 ? { endCard: extra.end } : {},
3234
+ ...values.canvas !== void 0 ? { canvas: values.canvas } : {},
3235
+ ...watermark !== void 0 ? { watermark } : {},
3236
+ ...extra.qa !== void 0 ? { qa: true } : {},
3237
+ ...values.alt ? { alt: true } : {},
3238
+ ...values.script ? { script: values.script } : {},
3239
+ ...values["voice-out"] ? { voiceOut: values["voice-out"] } : {},
3240
+ ...values["voice-strict"] ? { voiceStrict: true } : {},
3241
+ ...values.repair ? { repair: true } : {},
3242
+ ...values["repair-vision"] ? { repairVision: true } : {}
3243
+ },
3244
+ ...values.ai ? { ai: values.ai } : {},
3245
+ ...values["ai-vision"] ? { aiVision: values["ai-vision"] } : {},
3246
+ ...values.voice ? { voice: values.voice } : {},
3247
+ ...values["no-voice-cache"] ? { noVoiceCache: true } : {},
3248
+ ...extra.qa === "strict" ? { strict: true } : {},
3249
+ ...values.report ? { report: values.report } : {}
1887
3250
  };
1888
3251
  }
1889
- function sayVoice(o = {}) {
1890
- return async (text) => {
1891
- const dir = mkdtempSync2(join3(tmpdir2(), "tar-say-"));
3252
+ function reportOf(err, traceFile, repairFile) {
3253
+ if (!err) return { outcome: "passed", step: null, reason: null, message: null };
3254
+ const stall = err instanceof RenderError ? err.stall : void 0;
3255
+ if (stall && Number.isInteger(stall.index)) {
3256
+ let say = null;
1892
3257
  try {
1893
- const file = join3(dir, "line.wav");
1894
- const r = spawnSync2("say", [...o.voice ? ["-v", o.voice] : [], "-o", file, "--file-format=WAVE", "--data-format=LEI16@24000", text], { encoding: "utf8" });
1895
- if (r.error || r.status !== 0) throw new Error(`say failed${r.error ? ` (${r.error.message})` : `: ${r.stderr}`}; --voice say needs macOS`);
1896
- return fromWav(new Uint8Array(readFileSync6(file)));
1897
- } finally {
1898
- rmSync2(dir, { recursive: true, force: true });
3258
+ say = JSON.parse(readFileSync9(traceFile, "utf8")).steps?.[stall.index]?.say ?? null;
3259
+ } catch {
1899
3260
  }
1900
- };
3261
+ return {
3262
+ outcome: "stalled",
3263
+ step: stall.index,
3264
+ reason: stall.reason === "until-timeout" ? "until-timeout" : "not-found",
3265
+ message: say ?? err.message,
3266
+ ...repairFile && existsSync6(repairFile) ? { repair: repairFile } : {}
3267
+ };
3268
+ }
3269
+ return { outcome: "failed", step: null, reason: null, message: err?.message ?? String(err) };
1901
3270
  }
1902
- function cached(voice, id, dir) {
1903
- const v = (async (text) => {
1904
- const file = join3(dir, `${createHash("sha256").update(`${id}
1905
- ${text}`).digest("hex").slice(0, 32)}.wav`);
1906
- if (existsSync2(file)) {
1907
- v.hits += 1;
1908
- return fromWav(new Uint8Array(readFileSync6(file)));
3271
+ var UsageError = class extends Error {
3272
+ };
3273
+ async function main(argv, io = { log: console.log, error: console.error }) {
3274
+ if (argv[0] === "suggest" || argv[0] === "apply" || argv[0] === "catalogue" || argv[0] === "campaign") {
3275
+ const cmds = { suggest: suggestCmd, apply: applyCmd, catalogue: catalogueCmd, campaign: campaignCmd };
3276
+ try {
3277
+ return await cmds[argv[0]](argv.slice(1), io);
3278
+ } catch (e) {
3279
+ io.error(`trace-avatar-render ${argv[0]}: ${e.message}`);
3280
+ if (e instanceof UsageError) io.error(USAGE);
3281
+ return e instanceof UsageError ? 2 : 1;
1909
3282
  }
1910
- const p = await voice(text);
1911
- v.misses += 1;
1912
- mkdirSync2(dir, { recursive: true });
1913
- writeFileSync2(file, toWav(p.pcm, p.sampleRate));
1914
- return p;
1915
- });
1916
- v.hits = 0;
1917
- v.misses = 0;
1918
- return v;
1919
- }
1920
- async function voiceOf(spec, env = process.env, o = {}) {
1921
- const cacheDir = o.cacheDir === void 0 ? resolve3(".trace-avatar-cache", "voice") : o.cacheDir;
1922
- const wrap = (v) => cacheDir ? cached(v, spec, cacheDir) : v;
1923
- const g = /^gateway(?::gemini(?:\/([^:]+))?(?::(.+))?)?$/.exec(spec);
1924
- if (g) {
1925
- if (!env.AI_GATEWAY_URL || !env.AI_GATEWAY_KEY) throw new Error("--voice gateway needs AI_GATEWAY_URL and AI_GATEWAY_KEY");
1926
- return wrap(geminiVoice({
1927
- url: `${env.AI_GATEWAY_URL.replace(/\/+$/, "")}/v1/gemini`,
1928
- key: env.AI_GATEWAY_KEY,
1929
- bearer: true,
1930
- ...g[1] ? { model: g[1] } : {},
1931
- ...g[2] ? { voice: g[2] } : {},
1932
- headers: { "x-ai-feature": "trace-avatar-voice" },
1933
- ...o.fetch ? { fetch: o.fetch } : {}
1934
- }));
1935
3283
  }
1936
- const m = /^openai:([^:]+)(?::(.+))?$/.exec(spec);
1937
- if (m) {
1938
- if (!env.OPENAI_API_KEY && !env.OPENAI_BASE_URL) throw new Error("--voice openai:\u2026 needs OPENAI_API_KEY (and OPENAI_BASE_URL for another OpenAI-compatible server)");
1939
- return wrap(openAiVoice({ baseUrl: env.OPENAI_BASE_URL || "https://api.openai.com/v1", ...env.OPENAI_API_KEY ? { key: env.OPENAI_API_KEY } : {}, model: m[1], ...m[2] ? { voice: m[2] } : {}, ...o.fetch ? { fetch: o.fetch } : {} }));
3284
+ let p;
3285
+ try {
3286
+ p = parse(argv);
3287
+ } catch (e) {
3288
+ const msg = e.message;
3289
+ if (msg) io.error(`trace-avatar-render: ${msg}
3290
+ `);
3291
+ io.error(USAGE);
3292
+ return e instanceof UsageError && !msg ? 0 : 2;
1940
3293
  }
1941
- const s = /^say(?::(.+))?$/.exec(spec);
1942
- if (s) return wrap(sayVoice(s[1] ? { voice: s[1] } : {}));
1943
- if (/\.(m?js|cjs)$/.test(spec)) {
1944
- const mod = await import(pathToFileURL2(resolve3(spec)).href);
1945
- const fn = mod.default ?? mod.voice;
1946
- if (typeof fn !== "function") throw new Error(`${spec} must export a default function (text) \u2192 { pcm: Int16Array, sampleRate }`);
1947
- return wrap(fn);
3294
+ try {
3295
+ if (p.ai) p.options.ai = await providerOf(p.ai, process.env, p.aiVision ? { vision: p.aiVision } : {});
3296
+ if (p.voice) p.options.voice = await voiceOf(p.voice, process.env, p.noVoiceCache ? { cacheDir: null } : {});
3297
+ const r = await render(p.options);
3298
+ for (const o of r.outputs) io.log(`${o.file} ${o.width}\xD7${o.height} ${o.fps} fps ${(r.durationMs / 1e3).toFixed(1)} s ${(o.bytes / 1024).toFixed(0)} KB`);
3299
+ if (r.rawMs > r.durationMs + 50) io.log(`cut ${((r.rawMs - r.durationMs) / 1e3).toFixed(1)} s of waiting`);
3300
+ for (const f of [r.poster, r.vtt, r.chapters, r.alt]) if (f) io.log(f);
3301
+ if (r.narration) {
3302
+ io.log(`narration: ${r.narration.lines.length} line${r.narration.lines.length === 1 ? "" : "s"}${r.narration.holdMs ? `, the video holds ${(r.narration.holdMs / 1e3).toFixed(1)} s for them` : ""} ${r.narration.text}`);
3303
+ if (r.narration.wav) io.log(r.narration.wav);
3304
+ }
3305
+ for (const w of r.warnings ?? []) io.error(`warning: ${w}`);
3306
+ if (p.report) writeFileSync5(p.report, `${JSON.stringify(reportOf(null, p.trace), null, 2)}
3307
+ `);
3308
+ if (r.qa) {
3309
+ if (!r.qa.length) io.log("qa: nothing flagged");
3310
+ for (const f of r.qa) io.log(`qa: ${(f.at / 1e3).toFixed(1)} s ${f.kind} ${f.note}`);
3311
+ if (p.strict && r.qa.length) {
3312
+ io.error(`trace-avatar-render: qa flagged ${r.qa.length} problem${r.qa.length > 1 ? "s" : ""} (--qa strict)`);
3313
+ return 1;
3314
+ }
3315
+ }
3316
+ return 0;
3317
+ } catch (e) {
3318
+ io.error(`trace-avatar-render: ${e.message}`);
3319
+ if (p.report) {
3320
+ const first = p.options.out[0];
3321
+ const base2 = (typeof first === "string" ? first : first.file).replace(/\.[^./]+$/, "");
3322
+ writeFileSync5(p.report, `${JSON.stringify(reportOf(e, p.trace, `${base2}.repair.json`), null, 2)}
3323
+ `);
3324
+ }
3325
+ if (e instanceof RenderError && e.screenshot) {
3326
+ const first = p.options.out[0];
3327
+ const shot = `${(typeof first === "string" ? first : first.file).replace(/\.[^./]+$/, "")}.failure.png`;
3328
+ writeFileSync5(shot, e.screenshot);
3329
+ io.error(`the page at that moment: ${shot}`);
3330
+ }
3331
+ return 1;
1948
3332
  }
1949
- throw new Error(`--voice is gateway[:gemini[/<model>][:<voice>]], openai:<model>[:<voice>], say[:<voice>], or a .js file (got "${spec}")`);
1950
3333
  }
3334
+ var readJson = (file) => {
3335
+ try {
3336
+ return JSON.parse(readFileSync9(file, "utf8"));
3337
+ } catch (e) {
3338
+ throw new Error(`could not read ${file}: ${e.message}`);
3339
+ }
3340
+ };
3341
+ async function suggestCmd(argv, io) {
3342
+ const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: {
3343
+ task: { type: "string" },
3344
+ ai: { type: "string" },
3345
+ tone: { type: "string" },
3346
+ hints: { type: "string" },
3347
+ out: { type: "string" },
3348
+ "send-typed": { type: "boolean" }
3349
+ } });
3350
+ const [file] = positionals;
3351
+ if (!file) throw new UsageError("suggest needs a trace file");
3352
+ const task = values.task;
3353
+ if (task !== "captions" && task !== "title" && task !== "waits" && task !== "narration") throw new UsageError("--task is captions, title, waits or narration");
3354
+ if (!values.ai) throw new UsageError("suggest needs --ai");
3355
+ if (task === "narration") {
3356
+ const r2 = await suggestScript(await providerOf(values.ai), readJson(file));
3357
+ const out2 = JSON.stringify({ ...r2.script, ...r2.dropped.length ? { dropped: r2.dropped } : {} }, null, 2);
3358
+ if (values.out) {
3359
+ writeFileSync5(values.out, `${out2}
3360
+ `);
3361
+ io.log(`${r2.script.lines.length} line${r2.script.lines.length === 1 ? "" : "s"} in ${values.out}: edit them, then --script ${values.out}`);
3362
+ } else io.log(out2);
3363
+ return 0;
3364
+ }
3365
+ const tone = values.tone;
3366
+ if (tone !== void 0 && tone !== "friendly" && tone !== "terse" && tone !== "formal") throw new UsageError("--tone is friendly, terse or formal");
3367
+ const trace = readJson(file);
3368
+ const hints = values.hints ? readJson(values.hints) : void 0;
3369
+ const r = await suggest(task, trace, { ai: await providerOf(values.ai), ...hints ? { hints } : {}, ...tone ? { tone } : {}, ...values["send-typed"] ? { sendTyped: true } : {} });
3370
+ const out = JSON.stringify({ task, suggestions: r.suggestions.map((sg, k) => ({ id: k + 1, ...sg })), dropped: r.dropped }, null, 2);
3371
+ if (values.out) {
3372
+ writeFileSync5(values.out, `${out}
3373
+ `);
3374
+ io.log(`${r.suggestions.length} suggestion${r.suggestions.length === 1 ? "" : "s"} in ${values.out}`);
3375
+ } else io.log(out);
3376
+ return 0;
3377
+ }
3378
+ async function applyCmd(argv, io) {
3379
+ const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { accept: { type: "string" }, out: { type: "string" } } });
3380
+ const [file, sugFile] = positionals;
3381
+ if (!file || !sugFile) throw new UsageError("apply needs a trace file and a suggestions file");
3382
+ if (!values.accept) throw new UsageError("apply needs --accept 1,3 (or all): a person picks what goes in");
3383
+ if (!values.out) throw new UsageError("apply needs --out for the new trace");
3384
+ const all = readJson(sugFile).suggestions ?? [];
3385
+ const ids = values.accept === "all" ? all.map((x) => x.id) : values.accept.split(",").map((x) => Number(x.trim()));
3386
+ const missing = ids.filter((id) => !all.some((x) => x.id === id));
3387
+ if (missing.length) throw new UsageError(`no suggestion ${missing.join(", ")} in ${sugFile}`);
3388
+ const next = applySuggestions(readJson(file), all.filter((x) => ids.includes(x.id)));
3389
+ writeFileSync5(values.out, `${JSON.stringify(next, null, 2)}
3390
+ `);
3391
+ io.log(`applied ${ids.length} of ${all.length} to ${values.out}`);
3392
+ return 0;
3393
+ }
3394
+ async function campaignCmd(argv, io) {
3395
+ const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { start: { type: "boolean" }, fresh: { type: "boolean" }, voice: { type: "string" } } });
3396
+ const [sub, ...rest] = positionals;
3397
+ const file = rest[0] && /\.json$/i.test(rest[0]) ? rest.shift() : "campaign.json";
3398
+ if (sub !== "check" && sub !== "make" && sub !== "status") throw new UsageError("campaign check, make or status");
3399
+ if (!existsSync6(file)) throw new UsageError(`no campaign file ${file}`);
3400
+ if (sub === "status") {
3401
+ io.log(statusOf(readCampaign(file, { files: false })));
3402
+ return 0;
3403
+ }
3404
+ if (sub === "check") {
3405
+ const c2 = readCampaign(file);
3406
+ io.log(`${file}: ${c2.product}, ${c2.videos.length} video${c2.videos.length === 1 ? "" : "s"} in ${Object.keys(c2.looks).length} look${Object.keys(c2.looks).length === 1 ? "" : "s"} \u2014 ready to make`);
3407
+ return 0;
3408
+ }
3409
+ const c = readCampaign(file);
3410
+ const r = await makeCampaign(c, { only: rest, start: !!values.start, fresh: !!values.fresh, ...values.voice !== void 0 ? { voice: values.voice } : {}, log: io.log });
3411
+ if (r.failed.length) {
3412
+ io.error(`
3413
+ ${r.failed.length} failed:
3414
+ ${r.failed.join("\n ")}`);
3415
+ return 1;
3416
+ }
3417
+ return 0;
3418
+ }
3419
+ async function catalogueCmd(argv, io) {
3420
+ const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { fetch: { type: "boolean" }, json: { type: "boolean" }, "allow-http": { type: "boolean" } } });
3421
+ const [sub, where] = positionals;
3422
+ if (sub !== "check" || !where) throw new UsageError("catalogue check needs a file or a link");
3423
+ let doc;
3424
+ if (/^https?:\/\//.test(where)) {
3425
+ const res = await fetch(where);
3426
+ if (!res.ok) throw new Error(`${where} answered ${res.status}`);
3427
+ doc = await res.json();
3428
+ } else {
3429
+ if (!existsSync6(where)) throw new UsageError(`no file ${where}`);
3430
+ doc = readJson(where);
3431
+ }
3432
+ const r = await checkCatalogue(doc, { fetch: !!values.fetch, allowHttp: !!values["allow-http"] });
3433
+ if (values.json) {
3434
+ io.log(JSON.stringify(r, null, 2));
3435
+ return r.ok ? 0 : 1;
3436
+ }
3437
+ for (const p of r.problems) io.error(`\u2717 ${p}`);
3438
+ for (const w of r.warnings) io.log(`warning: ${w}`);
3439
+ io.log(`${where}: ${r.videos} video${r.videos === 1 ? "" : "s"}${values.fetch ? `, ${r.fetched} link${r.fetched === 1 ? "" : "s"} fetched` : ""} \u2014 ${r.ok ? "keeps trace-avatar-catalogue/1" : `${r.problems.length} problem${r.problems.length === 1 ? "" : "s"}`}${r.warnings.length ? `, ${r.warnings.length} warning${r.warnings.length === 1 ? "" : "s"}` : ""}`);
3440
+ return r.ok ? 0 : 1;
3441
+ }
3442
+ var isMain = import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("/trace-avatar-render") || process.argv[1]?.endsWith("/cli.js");
3443
+ if (isMain) void main(process.argv.slice(2)).then((code) => {
3444
+ process.exitCode = code;
3445
+ });
1951
3446
 
1952
3447
  export {
1953
3448
  ZOOM_KINDS,
@@ -2026,6 +3521,47 @@ export {
2026
3521
  openAiVoice,
2027
3522
  sayVoice,
2028
3523
  cached,
2029
- voiceOf
3524
+ voiceOf,
3525
+ CATALOGUE_SPEC,
3526
+ CATALOGUE_KINDS,
3527
+ CATALOGUE_SHAPES,
3528
+ CATALOGUE_FORMATS,
3529
+ CATALOGUE_REQUIRED,
3530
+ catalogueId,
3531
+ vttEnds,
3532
+ mp4Head,
3533
+ checkCatalogue,
3534
+ DIRECTOR_VIEWPORT,
3535
+ SKIP_KEEP_MS,
3536
+ arrowSprite,
3537
+ drawCursor,
3538
+ cursorAt,
3539
+ withCursor,
3540
+ pathOf,
3541
+ travelMs,
3542
+ sayFrom,
3543
+ lookOptions,
3544
+ cardsOf,
3545
+ aliasOf,
3546
+ direct,
3547
+ USAGE,
3548
+ parse,
3549
+ reportOf,
3550
+ UsageError,
3551
+ main,
3552
+ CAMPAIGN_KINDS,
3553
+ CAMPAIGN_SHAPES,
3554
+ loadCampaign,
3555
+ checkCampaign,
3556
+ readCampaign,
3557
+ rendersOf,
3558
+ shapeTag,
3559
+ filesOf,
3560
+ endsWithOf,
3561
+ progressOf,
3562
+ statusOf,
3563
+ ensureApp,
3564
+ makeCampaign,
3565
+ saysOf
2030
3566
  };
2031
- //# sourceMappingURL=chunk-ZNHFXKD3.js.map
3567
+ //# sourceMappingURL=chunk-EAMOVIQK.js.map