trace-avatar-render 0.1.5 → 0.1.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +18 -1
- package/README.md +39 -0
- package/dist/{chunk-OYFQTEVA.js → chunk-PPVNEPXF.js} +238 -11
- package/dist/chunk-PPVNEPXF.js.map +1 -0
- package/dist/cli.js +32 -3
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +266 -162
- package/dist/index.js +23 -1
- package/package.json +4 -2
- package/schemas/catalogue-1.json +48 -0
- package/dist/chunk-OYFQTEVA.js.map +0 -1
package/dist/index.d.ts
CHANGED
|
@@ -1,166 +1,6 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { Browser, Page } from 'playwright';
|
|
2
2
|
import { Ai, preview, Suggestion, Candidate, TextCandidate, applyRaw } from 'trace-avatar/assist';
|
|
3
3
|
|
|
4
|
-
/**
|
|
5
|
-
* The guide's own timeline, and the edit list made from it. PURE: plain numbers in, plain numbers out.
|
|
6
|
-
*
|
|
7
|
-
* Times are wall-clock milliseconds (the page logs Date.now(), the screencast stamps frames in epoch
|
|
8
|
-
* seconds), so events and frames from every page load share one clock.
|
|
9
|
-
*/
|
|
10
|
-
type Phase = 'idle' | 'playing' | 'paused' | 'waiting' | 'ended';
|
|
11
|
-
interface TimelineEvent {
|
|
12
|
-
t: number;
|
|
13
|
-
type: 'ready' | 'play' | 'state' | 'step' | 'stalled' | 'handoff' | 'page' | 'end' | 'error' | 'blocked' | 'unload';
|
|
14
|
-
phase?: Phase;
|
|
15
|
-
index?: number;
|
|
16
|
-
stepType?: string;
|
|
17
|
-
reason?: string;
|
|
18
|
-
message?: string;
|
|
19
|
-
url?: string;
|
|
20
|
-
/** step: where its element was (viewport CSS px). */
|
|
21
|
-
rect?: {
|
|
22
|
-
x: number;
|
|
23
|
-
y: number;
|
|
24
|
-
w: number;
|
|
25
|
-
h: number;
|
|
26
|
-
};
|
|
27
|
-
/** step: its words. */
|
|
28
|
-
say?: string;
|
|
29
|
-
}
|
|
30
|
-
interface Span {
|
|
31
|
-
from: number;
|
|
32
|
-
to: number;
|
|
33
|
-
phase: Phase;
|
|
34
|
-
}
|
|
35
|
-
/**
|
|
36
|
-
* A kept stretch of the capture, in source time. A hold (from === to, `hold` ms) shows the frame at `from`
|
|
37
|
-
* for that long: the video waits, for instance while a narrated line finishes.
|
|
38
|
-
*/
|
|
39
|
-
interface Segment {
|
|
40
|
-
from: number;
|
|
41
|
-
to: number;
|
|
42
|
-
hold?: number;
|
|
43
|
-
}
|
|
44
|
-
interface EditOptions {
|
|
45
|
-
/** Where the output starts and ends (source time). */
|
|
46
|
-
start: number;
|
|
47
|
-
end: number;
|
|
48
|
-
/** A wait longer than this keeps its first and last half of it; the middle is cut. Default 800. 0 keeps every wait. */
|
|
49
|
-
maxWaitMs?: number;
|
|
50
|
-
}
|
|
51
|
-
declare const DEFAULT_MAX_WAIT_MS = 800;
|
|
52
|
-
/**
|
|
53
|
-
* The player's phase over [start, end]. A page unloading counts as waiting until the next page's player
|
|
54
|
-
* reports a phase again.
|
|
55
|
-
*/
|
|
56
|
-
declare function spansOf(events: readonly TimelineEvent[], start: number, end: number): Span[];
|
|
57
|
-
/** The stretches of the capture to keep: everything, except the middle of each long wait. */
|
|
58
|
-
declare function editList(events: readonly TimelineEvent[], o: EditOptions): Segment[];
|
|
59
|
-
declare const durationOf: (segs: readonly Segment[]) => number;
|
|
60
|
-
/** The source time shown at output time `t` (clamped to the ends). */
|
|
61
|
-
declare function sourceAt(segs: readonly Segment[], t: number): number;
|
|
62
|
-
/** The output time where source time `src` lands, or null when it was cut. */
|
|
63
|
-
declare function outputAt(segs: readonly Segment[], src: number): number | null;
|
|
64
|
-
/**
|
|
65
|
-
* Insert holds: each `{ at, ms }` (at = output time on `segs`) freezes the frame there for `ms`. Later output
|
|
66
|
-
* times move by the holds before them.
|
|
67
|
-
*/
|
|
68
|
-
declare function withHolds(segs: readonly Segment[], holds: ReadonlyArray<{
|
|
69
|
-
at: number;
|
|
70
|
-
ms: number;
|
|
71
|
-
}>): Segment[];
|
|
72
|
-
/** The source time of every output frame at `fps`. */
|
|
73
|
-
declare function frameTimes(segs: readonly Segment[], fps: number): number[];
|
|
74
|
-
/** For each wanted time, the last captured frame at or before it (the first frame before any). */
|
|
75
|
-
declare function pickFrames(captured: readonly number[], want: readonly number[]): number[];
|
|
76
|
-
|
|
77
|
-
/**
|
|
78
|
-
* Play a trace on the real app in headless Chromium and capture it.
|
|
79
|
-
*
|
|
80
|
-
* The player (trace-perform.min.js) and a small bootstrap are injected into every page of the context,
|
|
81
|
-
* so a guide that crosses a full page load carries on (the player's resumeKey) and keeps logging its
|
|
82
|
-
* events. Frames come from Chromium's screencast, stamped on the same wall clock as the events.
|
|
83
|
-
*/
|
|
84
|
-
|
|
85
|
-
interface CaptureOptions {
|
|
86
|
-
/** The trace object. */
|
|
87
|
-
trace: unknown;
|
|
88
|
-
url: string;
|
|
89
|
-
mode: 'overlay' | 'perform';
|
|
90
|
-
viewport: {
|
|
91
|
-
w: number;
|
|
92
|
-
h: number;
|
|
93
|
-
};
|
|
94
|
-
/** Device pixel ratio. Default 1. */
|
|
95
|
-
scale?: number;
|
|
96
|
-
/** A signed-in session (Playwright storageState file). */
|
|
97
|
-
storageState?: string;
|
|
98
|
-
/** The player build (trace-perform.min.js). */
|
|
99
|
-
playerFile: string;
|
|
100
|
-
/** Selectors hidden before capture (e.g. your own dev toolbars). */
|
|
101
|
-
hide?: string[];
|
|
102
|
-
/** Selectors blurred before capture, as well as [data-trace-blur]. */
|
|
103
|
-
blur?: string[];
|
|
104
|
-
rate?: number;
|
|
105
|
-
/** When a step is on another page, load that page (as an app's router would) instead of waiting for it. */
|
|
106
|
-
navigate?: boolean;
|
|
107
|
-
/** Perform mode: what the guide leaves to the viewer (trace-avatar's `security`). */
|
|
108
|
-
security?: boolean | string[];
|
|
109
|
-
/** Perform mode: values to type, by name or field label (trace-avatar's `values`). */
|
|
110
|
-
values?: Record<string, string>;
|
|
111
|
-
/** The player's own captions: 'none' when the renderer burns them in itself. Default: the player's. */
|
|
112
|
-
captions?: 'bubble' | 'bar' | 'none';
|
|
113
|
-
/** A guide's own pause (or a hand-off) is held this long, then it plays on. Default 1200. */
|
|
114
|
-
pauseHoldMs?: number;
|
|
115
|
-
/** Keep capturing this long after the end. Default 1500. */
|
|
116
|
-
holdEndMs?: number;
|
|
117
|
-
/** Still frames before the guide starts. Default 500. */
|
|
118
|
-
leadMs?: number;
|
|
119
|
-
/** Render a stalled guide anyway (it shows "Looking for …") instead of failing. */
|
|
120
|
-
allowStall?: boolean;
|
|
121
|
-
/** Called on a stall with the live page, before anything else happens; what it returns rides on the RenderError. */
|
|
122
|
-
onStall?: (page: Page, stall: {
|
|
123
|
-
index: number;
|
|
124
|
-
reason: string;
|
|
125
|
-
}) => Promise<unknown>;
|
|
126
|
-
/** Give up after this long. Default 120 000. */
|
|
127
|
-
timeoutMs?: number;
|
|
128
|
-
headless?: boolean;
|
|
129
|
-
}
|
|
130
|
-
interface CapturedFrame {
|
|
131
|
-
t: number;
|
|
132
|
-
png: Buffer;
|
|
133
|
-
}
|
|
134
|
-
interface Capture {
|
|
135
|
-
frames: CapturedFrame[];
|
|
136
|
-
/** The viewport in CSS px and the device pixel ratio (frames are viewport × scale). */
|
|
137
|
-
viewport?: {
|
|
138
|
-
w: number;
|
|
139
|
-
h: number;
|
|
140
|
-
scale: number;
|
|
141
|
-
};
|
|
142
|
-
/** Each page's title, by path. */
|
|
143
|
-
titles?: Record<string, string>;
|
|
144
|
-
events: TimelineEvent[];
|
|
145
|
-
/** When the guide started and when capture stopped (wall ms). */
|
|
146
|
-
playAt: number;
|
|
147
|
-
stopAt: number;
|
|
148
|
-
endAt: number | null;
|
|
149
|
-
}
|
|
150
|
-
declare class RenderError extends Error {
|
|
151
|
-
readonly screenshot?: Buffer | undefined;
|
|
152
|
-
/** A stall: which step, why, and what onStall found on the page. */
|
|
153
|
-
stall?: {
|
|
154
|
-
index: number;
|
|
155
|
-
reason: string;
|
|
156
|
-
data?: unknown;
|
|
157
|
-
};
|
|
158
|
-
constructor(message: string, screenshot?: Buffer | undefined);
|
|
159
|
-
}
|
|
160
|
-
declare function capture(o: CaptureOptions): Promise<Capture>;
|
|
161
|
-
/** Where the player build is: an explicit file, TRACE_AVATAR_PLAYER, or the installed trace-avatar. */
|
|
162
|
-
declare function findPlayer(explicit?: string, env?: NodeJS.ProcessEnv): Promise<string>;
|
|
163
|
-
|
|
164
4
|
/** RGBA pixel helpers. PURE. */
|
|
165
5
|
interface Image {
|
|
166
6
|
width: number;
|
|
@@ -342,6 +182,188 @@ interface Layers {
|
|
|
342
182
|
declare const DEFAULT_BACKGROUND = "linear-gradient(135deg, #dfe7fb 0%, #eef0f6 50%, #f6e9f1 100%)";
|
|
343
183
|
declare function createLayers(browser: Browser): Promise<Layers>;
|
|
344
184
|
|
|
185
|
+
/**
|
|
186
|
+
* The guide's own timeline, and the edit list made from it. PURE: plain numbers in, plain numbers out.
|
|
187
|
+
*
|
|
188
|
+
* Times are wall-clock milliseconds (the page logs Date.now(), the screencast stamps frames in epoch
|
|
189
|
+
* seconds), so events and frames from every page load share one clock.
|
|
190
|
+
*/
|
|
191
|
+
type Phase = 'idle' | 'playing' | 'paused' | 'waiting' | 'ended';
|
|
192
|
+
interface TimelineEvent {
|
|
193
|
+
t: number;
|
|
194
|
+
type: 'ready' | 'play' | 'state' | 'step' | 'stalled' | 'handoff' | 'page' | 'end' | 'error' | 'blocked' | 'unload';
|
|
195
|
+
phase?: Phase;
|
|
196
|
+
index?: number;
|
|
197
|
+
stepType?: string;
|
|
198
|
+
reason?: string;
|
|
199
|
+
message?: string;
|
|
200
|
+
url?: string;
|
|
201
|
+
/** step: where its element was (viewport CSS px). */
|
|
202
|
+
rect?: {
|
|
203
|
+
x: number;
|
|
204
|
+
y: number;
|
|
205
|
+
w: number;
|
|
206
|
+
h: number;
|
|
207
|
+
};
|
|
208
|
+
/** step: its words. */
|
|
209
|
+
say?: string;
|
|
210
|
+
}
|
|
211
|
+
interface Span {
|
|
212
|
+
from: number;
|
|
213
|
+
to: number;
|
|
214
|
+
phase: Phase;
|
|
215
|
+
}
|
|
216
|
+
/**
|
|
217
|
+
* A kept stretch of the capture, in source time. A hold (from === to, `hold` ms) shows the frame at `from`
|
|
218
|
+
* for that long: the video waits, for instance while a narrated line finishes.
|
|
219
|
+
*/
|
|
220
|
+
/** A stretch of the source (from–to), or a frozen moment (`hold` ms at `from`); `card` shows a capture's card instead. */
|
|
221
|
+
interface Segment {
|
|
222
|
+
from: number;
|
|
223
|
+
to: number;
|
|
224
|
+
hold?: number;
|
|
225
|
+
card?: number;
|
|
226
|
+
}
|
|
227
|
+
interface EditOptions {
|
|
228
|
+
/** Where the output starts and ends (source time). */
|
|
229
|
+
start: number;
|
|
230
|
+
end: number;
|
|
231
|
+
/** A wait longer than this keeps its first and last half of it; the middle is cut. Default 800. 0 keeps every wait. */
|
|
232
|
+
maxWaitMs?: number;
|
|
233
|
+
}
|
|
234
|
+
declare const DEFAULT_MAX_WAIT_MS = 800;
|
|
235
|
+
/**
|
|
236
|
+
* The player's phase over [start, end]. A page unloading counts as waiting until the next page's player
|
|
237
|
+
* reports a phase again.
|
|
238
|
+
*/
|
|
239
|
+
declare function spansOf(events: readonly TimelineEvent[], start: number, end: number): Span[];
|
|
240
|
+
/** The stretches of the capture to keep: everything, except the middle of each long wait. */
|
|
241
|
+
declare function editList(events: readonly TimelineEvent[], o: EditOptions): Segment[];
|
|
242
|
+
declare const durationOf: (segs: readonly Segment[]) => number;
|
|
243
|
+
/** The source time shown at output time `t` (clamped to the ends). */
|
|
244
|
+
declare function sourceAt(segs: readonly Segment[], t: number): number;
|
|
245
|
+
/** The output time where source time `src` lands, or null when it was cut. */
|
|
246
|
+
declare function outputAt(segs: readonly Segment[], src: number): number | null;
|
|
247
|
+
/**
|
|
248
|
+
* Insert holds: each `{ at, ms }` (at = output time on `segs`) freezes the frame there for `ms`. Later output
|
|
249
|
+
* times move by the holds before them.
|
|
250
|
+
*/
|
|
251
|
+
declare function withHolds(segs: readonly Segment[], holds: ReadonlyArray<{
|
|
252
|
+
at: number;
|
|
253
|
+
ms: number;
|
|
254
|
+
}>): Segment[];
|
|
255
|
+
/**
|
|
256
|
+
* Insert cards (a director's `d.card`): each `{ t, ms }` (t = source time) is shown for `ms` at that moment, as a
|
|
257
|
+
* held segment marked with its index in `cards`. A card at a cut-out moment goes where the next kept stretch starts.
|
|
258
|
+
*/
|
|
259
|
+
declare function withCards(segs: readonly Segment[], cards: ReadonlyArray<{
|
|
260
|
+
t: number;
|
|
261
|
+
ms: number;
|
|
262
|
+
}>): Segment[];
|
|
263
|
+
/** For every output frame at `fps`, the card it shows (its index), or undefined for the app. */
|
|
264
|
+
declare function cardFrames(segs: readonly Segment[], fps: number): Array<number | undefined>;
|
|
265
|
+
/** The source time of every output frame at `fps`. */
|
|
266
|
+
declare function frameTimes(segs: readonly Segment[], fps: number): number[];
|
|
267
|
+
/** For each wanted time, the last captured frame at or before it (the first frame before any). */
|
|
268
|
+
declare function pickFrames(captured: readonly number[], want: readonly number[]): number[];
|
|
269
|
+
|
|
270
|
+
/**
|
|
271
|
+
* Play a trace on the real app in headless Chromium and capture it.
|
|
272
|
+
*
|
|
273
|
+
* The player (trace-perform.min.js) and a small bootstrap are injected into every page of the context,
|
|
274
|
+
* so a guide that crosses a full page load carries on (the player's resumeKey) and keeps logging its
|
|
275
|
+
* events. Frames come from Chromium's screencast, stamped on the same wall clock as the events.
|
|
276
|
+
*/
|
|
277
|
+
|
|
278
|
+
interface CaptureOptions {
|
|
279
|
+
/** The trace object. */
|
|
280
|
+
trace: unknown;
|
|
281
|
+
url: string;
|
|
282
|
+
mode: 'overlay' | 'perform';
|
|
283
|
+
viewport: {
|
|
284
|
+
w: number;
|
|
285
|
+
h: number;
|
|
286
|
+
};
|
|
287
|
+
/** Device pixel ratio. Default 1. */
|
|
288
|
+
scale?: number;
|
|
289
|
+
/** A signed-in session (Playwright storageState file). */
|
|
290
|
+
storageState?: string;
|
|
291
|
+
/** The player build (trace-perform.min.js). */
|
|
292
|
+
playerFile: string;
|
|
293
|
+
/** Selectors hidden before capture (e.g. your own dev toolbars). */
|
|
294
|
+
hide?: string[];
|
|
295
|
+
/** Selectors blurred before capture, as well as [data-trace-blur]. */
|
|
296
|
+
blur?: string[];
|
|
297
|
+
rate?: number;
|
|
298
|
+
/** When a step is on another page, load that page (as an app's router would) instead of waiting for it. */
|
|
299
|
+
navigate?: boolean;
|
|
300
|
+
/** Perform mode: what the guide leaves to the viewer (trace-avatar's `security`). */
|
|
301
|
+
security?: boolean | string[];
|
|
302
|
+
/** Perform mode: values to type, by name or field label (trace-avatar's `values`). */
|
|
303
|
+
values?: Record<string, string>;
|
|
304
|
+
/** The player's own captions: 'none' when the renderer burns them in itself. Default: the player's. */
|
|
305
|
+
captions?: 'bubble' | 'bar' | 'none';
|
|
306
|
+
/** A guide's own pause (or a hand-off) is held this long, then it plays on. Default 1200. */
|
|
307
|
+
pauseHoldMs?: number;
|
|
308
|
+
/** Keep capturing this long after the end. Default 1500. */
|
|
309
|
+
holdEndMs?: number;
|
|
310
|
+
/** Still frames before the guide starts. Default 500. */
|
|
311
|
+
leadMs?: number;
|
|
312
|
+
/** Render a stalled guide anyway (it shows "Looking for …") instead of failing. */
|
|
313
|
+
allowStall?: boolean;
|
|
314
|
+
/** Called on a stall with the live page, before anything else happens; what it returns rides on the RenderError. */
|
|
315
|
+
onStall?: (page: Page, stall: {
|
|
316
|
+
index: number;
|
|
317
|
+
reason: string;
|
|
318
|
+
}) => Promise<unknown>;
|
|
319
|
+
/** Give up after this long. Default 120 000. */
|
|
320
|
+
timeoutMs?: number;
|
|
321
|
+
headless?: boolean;
|
|
322
|
+
}
|
|
323
|
+
interface CapturedFrame {
|
|
324
|
+
t: number;
|
|
325
|
+
png: Buffer;
|
|
326
|
+
}
|
|
327
|
+
interface Capture {
|
|
328
|
+
frames: CapturedFrame[];
|
|
329
|
+
/** The viewport in CSS px and the device pixel ratio (frames are viewport × scale). */
|
|
330
|
+
viewport?: {
|
|
331
|
+
w: number;
|
|
332
|
+
h: number;
|
|
333
|
+
scale: number;
|
|
334
|
+
};
|
|
335
|
+
/** Each page's title, by path. */
|
|
336
|
+
titles?: Record<string, string>;
|
|
337
|
+
events: TimelineEvent[];
|
|
338
|
+
/** When the guide started and when capture stopped (wall ms). */
|
|
339
|
+
playAt: number;
|
|
340
|
+
stopAt: number;
|
|
341
|
+
endAt: number | null;
|
|
342
|
+
/**
|
|
343
|
+
* Cards between scenes (a director clip's `d.card`): each shown for `ms` at source time `t`. A narrated card's
|
|
344
|
+
* step sits just after `t` (t + 1), so its line is spoken over the card, and the card lasts as long as its line.
|
|
345
|
+
*/
|
|
346
|
+
cards?: Array<{
|
|
347
|
+
t: number;
|
|
348
|
+
ms: number;
|
|
349
|
+
card: CardOptions;
|
|
350
|
+
step?: number;
|
|
351
|
+
}>;
|
|
352
|
+
}
|
|
353
|
+
declare class RenderError extends Error {
|
|
354
|
+
readonly screenshot?: Buffer | undefined;
|
|
355
|
+
/** A stall: which step, why, and what onStall found on the page. */
|
|
356
|
+
stall?: {
|
|
357
|
+
index: number;
|
|
358
|
+
reason: string;
|
|
359
|
+
data?: unknown;
|
|
360
|
+
};
|
|
361
|
+
constructor(message: string, screenshot?: Buffer | undefined);
|
|
362
|
+
}
|
|
363
|
+
declare function capture(o: CaptureOptions): Promise<Capture>;
|
|
364
|
+
/** Where the player build is: an explicit file, TRACE_AVATAR_PLAYER, or the installed trace-avatar. */
|
|
365
|
+
declare function findPlayer(explicit?: string, env?: NodeJS.ProcessEnv): Promise<string>;
|
|
366
|
+
|
|
345
367
|
/**
|
|
346
368
|
* Mono 16-bit PCM: read and write WAV, resample, trim silence, and lay lines on one track. PURE.
|
|
347
369
|
*/
|
|
@@ -933,4 +955,86 @@ declare function repairGuide(o: {
|
|
|
933
955
|
first?: RenderError;
|
|
934
956
|
}): Promise<RepairOutcome>;
|
|
935
957
|
|
|
936
|
-
|
|
958
|
+
/**
|
|
959
|
+
* The clip catalogue, `trace-avatar-catalogue/1` (schemas/catalogue-1.json): a public JSON file listing a product's
|
|
960
|
+
* published marketing videos, one entry per file and shape, so anything (a scheduler such as DutyCaptain, a site) can
|
|
961
|
+
* pick a clip and write about it from the clip's own words (`says`).
|
|
962
|
+
*
|
|
963
|
+
* const r = checkCatalogue(json); // the rules a file can show by itself
|
|
964
|
+
* const r = await checkCatalogue(json, { fetch: true }); // …and its links: reachable, the right type, captions that
|
|
965
|
+
* // fit the video, an mp4 that starts playing before it has all loaded
|
|
966
|
+
*
|
|
967
|
+
* Problems break the spec; warnings are advice (a reader still works). Unknown fields are allowed.
|
|
968
|
+
*/
|
|
969
|
+
declare const CATALOGUE_SPEC = "trace-avatar-catalogue/1";
|
|
970
|
+
declare const CATALOGUE_KINDS: readonly ["intro", "demo", "guide", "onboarding", "pitch", "whats-new", "ad", "docs-gif", "qa", "support"];
|
|
971
|
+
declare const CATALOGUE_SHAPES: readonly ["16:9", "1:1", "4:5", "9:16"];
|
|
972
|
+
declare const CATALOGUE_FORMATS: readonly ["mp4", "gif"];
|
|
973
|
+
/** The fields every entry has. */
|
|
974
|
+
declare const CATALOGUE_REQUIRED: readonly ["id", "product", "video", "kind", "preset", "shape", "format", "url", "captionsBurned", "seconds", "narrated", "alt", "site", "made"];
|
|
975
|
+
interface CatalogueEntry {
|
|
976
|
+
id: string;
|
|
977
|
+
product: string;
|
|
978
|
+
video: string;
|
|
979
|
+
kind: (typeof CATALOGUE_KINDS)[number];
|
|
980
|
+
preset: string;
|
|
981
|
+
shape: (typeof CATALOGUE_SHAPES)[number] | null;
|
|
982
|
+
format: (typeof CATALOGUE_FORMATS)[number];
|
|
983
|
+
url: string;
|
|
984
|
+
poster?: string;
|
|
985
|
+
captions?: string;
|
|
986
|
+
/** Two letters; `en` when absent. */
|
|
987
|
+
language?: string;
|
|
988
|
+
captionsBurned: boolean;
|
|
989
|
+
seconds: number;
|
|
990
|
+
narrated: boolean;
|
|
991
|
+
title?: string | null;
|
|
992
|
+
alt: string;
|
|
993
|
+
/** The video's own words, in order: its captions (the spoken lines when narrated) and its cards' lines. */
|
|
994
|
+
says?: string[];
|
|
995
|
+
site: string;
|
|
996
|
+
endsWith?: string;
|
|
997
|
+
made: string;
|
|
998
|
+
[more: string]: unknown;
|
|
999
|
+
}
|
|
1000
|
+
interface Catalogue {
|
|
1001
|
+
spec: typeof CATALOGUE_SPEC;
|
|
1002
|
+
updated: string;
|
|
1003
|
+
videos: CatalogueEntry[];
|
|
1004
|
+
[more: string]: unknown;
|
|
1005
|
+
}
|
|
1006
|
+
interface CatalogueCheck {
|
|
1007
|
+
ok: boolean;
|
|
1008
|
+
problems: string[];
|
|
1009
|
+
warnings: string[];
|
|
1010
|
+
/** Entries checked. */
|
|
1011
|
+
videos: number;
|
|
1012
|
+
/** Links fetched (with `fetch`). */
|
|
1013
|
+
fetched: number;
|
|
1014
|
+
}
|
|
1015
|
+
/** An entry's id as the spec recommends: <product>/<video>/<preset>/<shape|gif>. Stable across re-renders. */
|
|
1016
|
+
declare function catalogueId(e: Pick<CatalogueEntry, 'product' | 'video' | 'preset' | 'shape' | 'format'>): string;
|
|
1017
|
+
/** WebVTT cue end times, in seconds. Throws when it is not WebVTT. */
|
|
1018
|
+
declare function vttEnds(text: string): number[];
|
|
1019
|
+
/**
|
|
1020
|
+
* An mp4's top-level boxes from its first bytes: whether `moov` (what a player needs first) comes before `mdat` (the
|
|
1021
|
+
* media), and, when moov is all there, which codecs it names.
|
|
1022
|
+
*/
|
|
1023
|
+
declare function mp4Head(bytes: Uint8Array): {
|
|
1024
|
+
faststart: boolean | null;
|
|
1025
|
+
codecs: string[] | null;
|
|
1026
|
+
};
|
|
1027
|
+
interface CheckOptions {
|
|
1028
|
+
/** Fetch every link too (no cookies): reachable, its type, the captions' length, the mp4's head. */
|
|
1029
|
+
fetch?: boolean;
|
|
1030
|
+
/** The fetch to use (tests). */
|
|
1031
|
+
fetcher?: typeof fetch;
|
|
1032
|
+
/** Links fetched at once (default 6). */
|
|
1033
|
+
concurrency?: number;
|
|
1034
|
+
/** Allow http:// links (a local test server); the spec wants https. */
|
|
1035
|
+
allowHttp?: boolean;
|
|
1036
|
+
}
|
|
1037
|
+
/** Check a catalogue against trace-avatar-catalogue/1. With `fetch`, its links too. */
|
|
1038
|
+
declare function checkCatalogue(doc: unknown, o?: CheckOptions): Promise<CatalogueCheck>;
|
|
1039
|
+
|
|
1040
|
+
export { type Action, type Brand, CANVASES, CATALOGUE_FORMATS, CATALOGUE_KINDS, CATALOGUE_REQUIRED, CATALOGUE_SHAPES, CATALOGUE_SPEC, CORNERS, type CameraOptions, type Canvas, type CanvasSpec, type Capture, type CaptureOptions, type CapturedFrame, type CardOptions, type Catalogue, type CatalogueCheck, type CatalogueEntry, type CheckOptions, type Corner, type Cue, DEFAULT_BACKGROUND, DEFAULT_MAX_WAIT_MS, type EditOptions, type FinishOptions, type FrameStyle, GEMINI_TTS, type GifOptions, type GifResult, type GifWriter, type Image, type Layers, type Layout, type NarrationPlan, type OutFormat, type OutSpec, type Pcm, type Phase, type PlanOptions, type PlannedLine, type Rect, RenderError, type RenderOptions, type RenderOutput, type RenderResult, type RepairOutcome, type RepairSuggestion, type Script, type Segment, type Span, TRACK_RATE, type TimelineEvent, type Unresolved, type Voice, type Watermark, ZOOM_KINDS, actionsOf, badgeAt, blank, brandFile, brandOf, cached, cameraKeys, cameraPath, canvasOf, captionCues, capture, cardFrames, cardOf, catalogueId, chapterCues, checkCatalogue, createGifWriter, createLayers, crop, crossfade, cueAt, dataUri, drawRegion, durationOf, editList, encodeGif, encodeMp4, findFfmpeg, findPlayer, finish, fitWidth, formatOf, frameTimes, fromS16le, fromWav, geminiVoice, layoutOf, linesOf, mix, mp4Args, mp4Head, msOf, narrationText, openAiVoice, outputAt, overlay, pageAt, paletteOf, parseScript, pickFrames, pixel, planNarration, providerOf, render, repairGuide, repairScriptOf, resample, resize, runQa, sayVoice, sourceAt, spansOf, stallInspector, stepCues, suggestScript, toVtt, toWav, trimSilence, voiceOf, vttEnds, watermarkOf, withCards, withHolds };
|
package/dist/index.js
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
import {
|
|
2
2
|
CANVASES,
|
|
3
|
+
CATALOGUE_FORMATS,
|
|
4
|
+
CATALOGUE_KINDS,
|
|
5
|
+
CATALOGUE_REQUIRED,
|
|
6
|
+
CATALOGUE_SHAPES,
|
|
7
|
+
CATALOGUE_SPEC,
|
|
3
8
|
CORNERS,
|
|
4
9
|
DEFAULT_BACKGROUND,
|
|
5
10
|
DEFAULT_MAX_WAIT_MS,
|
|
@@ -18,8 +23,11 @@ import {
|
|
|
18
23
|
canvasOf,
|
|
19
24
|
captionCues,
|
|
20
25
|
capture,
|
|
26
|
+
cardFrames,
|
|
21
27
|
cardOf,
|
|
28
|
+
catalogueId,
|
|
22
29
|
chapterCues,
|
|
30
|
+
checkCatalogue,
|
|
23
31
|
createGifWriter,
|
|
24
32
|
createLayers,
|
|
25
33
|
crop,
|
|
@@ -44,6 +52,7 @@ import {
|
|
|
44
52
|
linesOf,
|
|
45
53
|
mix,
|
|
46
54
|
mp4Args,
|
|
55
|
+
mp4Head,
|
|
47
56
|
msOf,
|
|
48
57
|
narrationText,
|
|
49
58
|
openAiVoice,
|
|
@@ -72,11 +81,18 @@ import {
|
|
|
72
81
|
toWav,
|
|
73
82
|
trimSilence,
|
|
74
83
|
voiceOf,
|
|
84
|
+
vttEnds,
|
|
75
85
|
watermarkOf,
|
|
86
|
+
withCards,
|
|
76
87
|
withHolds
|
|
77
|
-
} from "./chunk-
|
|
88
|
+
} from "./chunk-PPVNEPXF.js";
|
|
78
89
|
export {
|
|
79
90
|
CANVASES,
|
|
91
|
+
CATALOGUE_FORMATS,
|
|
92
|
+
CATALOGUE_KINDS,
|
|
93
|
+
CATALOGUE_REQUIRED,
|
|
94
|
+
CATALOGUE_SHAPES,
|
|
95
|
+
CATALOGUE_SPEC,
|
|
80
96
|
CORNERS,
|
|
81
97
|
DEFAULT_BACKGROUND,
|
|
82
98
|
DEFAULT_MAX_WAIT_MS,
|
|
@@ -95,8 +111,11 @@ export {
|
|
|
95
111
|
canvasOf,
|
|
96
112
|
captionCues,
|
|
97
113
|
capture,
|
|
114
|
+
cardFrames,
|
|
98
115
|
cardOf,
|
|
116
|
+
catalogueId,
|
|
99
117
|
chapterCues,
|
|
118
|
+
checkCatalogue,
|
|
100
119
|
createGifWriter,
|
|
101
120
|
createLayers,
|
|
102
121
|
crop,
|
|
@@ -121,6 +140,7 @@ export {
|
|
|
121
140
|
linesOf,
|
|
122
141
|
mix,
|
|
123
142
|
mp4Args,
|
|
143
|
+
mp4Head,
|
|
124
144
|
msOf,
|
|
125
145
|
narrationText,
|
|
126
146
|
openAiVoice,
|
|
@@ -149,7 +169,9 @@ export {
|
|
|
149
169
|
toWav,
|
|
150
170
|
trimSilence,
|
|
151
171
|
voiceOf,
|
|
172
|
+
vttEnds,
|
|
152
173
|
watermarkOf,
|
|
174
|
+
withCards,
|
|
153
175
|
withHolds
|
|
154
176
|
};
|
|
155
177
|
//# sourceMappingURL=index.js.map
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "trace-avatar-render",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.7",
|
|
4
4
|
"description": "Render a trace-avatar guide to a GIF or MP4 by playing it on your real app in headless Chromium.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -13,10 +13,12 @@
|
|
|
13
13
|
"types": "./dist/index.d.ts",
|
|
14
14
|
"import": "./dist/index.js"
|
|
15
15
|
},
|
|
16
|
-
"./package.json": "./package.json"
|
|
16
|
+
"./package.json": "./package.json",
|
|
17
|
+
"./schemas/catalogue-1.json": "./schemas/catalogue-1.json"
|
|
17
18
|
},
|
|
18
19
|
"files": [
|
|
19
20
|
"dist",
|
|
21
|
+
"schemas",
|
|
20
22
|
"README.md",
|
|
21
23
|
"CHANGELOG.md",
|
|
22
24
|
"LICENSE"
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "https://traceavatar.com/schemas/catalogue-1.json",
|
|
4
|
+
"title": "trace-avatar-catalogue/1",
|
|
5
|
+
"description": "A product's published marketing videos: one entry per file and shape. `trace-avatar-render catalogue check` checks this and the rules a schema can't (unique ids, captions that fit the video, links that answer).",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"required": ["spec", "updated", "videos"],
|
|
8
|
+
"properties": {
|
|
9
|
+
"spec": { "const": "trace-avatar-catalogue/1" },
|
|
10
|
+
"updated": { "type": "string", "format": "date-time" },
|
|
11
|
+
"videos": { "type": "array", "items": { "$ref": "#/$defs/entry" } }
|
|
12
|
+
},
|
|
13
|
+
"$defs": {
|
|
14
|
+
"word": { "type": "string", "pattern": "^\\S+$" },
|
|
15
|
+
"https": { "type": "string", "format": "uri", "pattern": "^https://" },
|
|
16
|
+
"entry": {
|
|
17
|
+
"type": "object",
|
|
18
|
+
"required": ["id", "product", "video", "kind", "preset", "shape", "format", "url", "captionsBurned", "seconds", "narrated", "alt", "site", "made"],
|
|
19
|
+
"properties": {
|
|
20
|
+
"id": { "$ref": "#/$defs/word", "description": "Stable across re-renders: <product>/<video>/<preset>/<shape|gif>." },
|
|
21
|
+
"product": { "$ref": "#/$defs/word", "description": "The product it promotes." },
|
|
22
|
+
"video": { "$ref": "#/$defs/word", "description": "The video it is a cut of; its shapes share it." },
|
|
23
|
+
"kind": { "enum": ["intro", "demo", "guide", "onboarding", "pitch", "whats-new", "ad", "docs-gif", "qa", "support"] },
|
|
24
|
+
"preset": { "$ref": "#/$defs/word", "description": "The look: product (its own brand) or another." },
|
|
25
|
+
"shape": { "enum": ["16:9", "1:1", "4:5", "9:16", null], "description": "The canvas; null for a GIF." },
|
|
26
|
+
"format": { "enum": ["mp4", "gif"] },
|
|
27
|
+
"url": { "$ref": "#/$defs/https", "description": "The file. Content-addressed and cached forever is recommended." },
|
|
28
|
+
"poster": { "$ref": "#/$defs/https" },
|
|
29
|
+
"captions": { "$ref": "#/$defs/https", "description": "WebVTT, when the captions are not burned in." },
|
|
30
|
+
"language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "The captions' and narration's language; en when absent." },
|
|
31
|
+
"captionsBurned": { "type": "boolean" },
|
|
32
|
+
"seconds": { "type": "number", "exclusiveMinimum": 0 },
|
|
33
|
+
"narrated": { "type": "boolean" },
|
|
34
|
+
"title": { "type": ["string", "null"] },
|
|
35
|
+
"alt": { "type": "string", "minLength": 1, "description": "What it shows, plainly." },
|
|
36
|
+
"says": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "The video's own words, in order: its captions (the spoken lines when narrated) and its cards' lines." },
|
|
37
|
+
"site": { "$ref": "#/$defs/https" },
|
|
38
|
+
"endsWith": { "type": "string", "description": "What its last card says." },
|
|
39
|
+
"made": { "type": "string", "format": "date-time" }
|
|
40
|
+
},
|
|
41
|
+
"allOf": [
|
|
42
|
+
{ "if": { "properties": { "format": { "const": "gif" } } }, "then": { "properties": { "shape": { "const": null } } } },
|
|
43
|
+
{ "if": { "properties": { "format": { "const": "mp4" } } }, "then": { "properties": { "shape": { "enum": ["16:9", "1:1", "4:5", "9:16"] } } } },
|
|
44
|
+
{ "if": { "properties": { "captionsBurned": { "const": true } }, "required": ["captionsBurned"] }, "then": { "not": { "required": ["captions"] } } }
|
|
45
|
+
]
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
}
|