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.
package/CHANGELOG.md CHANGED
@@ -1,6 +1,40 @@
1
1
  # Changelog
2
2
 
3
- ## 0.1.6 (unreleased)
3
+ ## 0.2.0 (unreleased)
4
+
5
+ - **Campaigns** (`campaign.json`): a product's marketing videos, made on the real app in every look and shape.
6
+ - `trace-avatar-render campaign check | make | status [campaign.json]`, and `readCampaign`, `makeCampaign`,
7
+ `statusOf`, `rendersOf`, `filesOf`, `endsWithOf`, `saysOf` from code.
8
+ - Per video and look: one desktop capture written as 16:9, 1:1 and 4:5 (captions as a file), and a phone capture
9
+ (390×844) for 9:16 with captions burned in. A video is a guide or a director script.
10
+ - The app: started with `--start` (`app.start`, ready at `app.ready` or when it prints `app.readyText`), put back
11
+ to a known state before each video (`app.reset`: `{ post }` or `{ run }`, with the video's `reset` as its body),
12
+ signed in with `app.storageState` or a session module (`storageStateFor(url, options)`), shown under its public
13
+ name (`app.alias`), with prop folders served at its address (`app.routes`).
14
+ - Looks are named brand files; a look's `endsWith` (or its brand's end card) is what its videos end with.
15
+ - Progress in `<out>/progress.json` while it runs; a run stopped part way carries on (`--fresh` starts over);
16
+ `<out>/made.json` lists what was made. It stops before capturing anything when there's no ffmpeg or the voice
17
+ can't be reached.
18
+ - **Director videos** (`direct()`): a script plays a person using the app — `d.scene`, `d.card`, `d.click`,
19
+ `d.type`, `d.hover`, `d.press`, `d.read`, `d.skip`, `d.open`, `d.window`, `d.expect` (with `@playwright/test`) —
20
+ with the cursor drawn on afterwards; narrated, the captions say the spoken lines. Writes `<id>.scenes.json`.
21
+ `lookOptions()` gives finish() options from a brand and the video's flags.
22
+ - **Narrated from a script, captions say the spoken lines** (render, `--script`): each step's caption is its line,
23
+ so the captions file and burned-in captions show what is heard (they kept the steps' own words).
24
+ - **ffmpeg**: `ffmpeg-static` is an optional dependency, used when there's no `FFMPEG` and no ffmpeg on the PATH.
25
+
26
+ ## 0.1.7 (13 Nov 2026)
27
+
28
+ - **The clip catalogue, `trace-avatar-catalogue/1`** (`schemas/catalogue-1.json`, also at
29
+ https://traceavatar.com/schemas/catalogue-1.json): a public JSON file of a product's published videos, one entry per
30
+ file and shape, with each clip's own words (`says`), so a scheduler can post it and write about it truthfully.
31
+ - `trace-avatar-render catalogue check <file|url> [--fetch]` checks one: every field, unique ids, burned captions
32
+ with no captions file. With `--fetch` it checks the links too: they answer without cookies, with the right type;
33
+ the captions end within the video; the mp4 is H.264 (with AAC sound when narrated) and starts playing before it
34
+ has all loaded (`moov` first).
35
+ - `checkCatalogue()`, `catalogueId()`, `vttEnds()`, `mp4Head()` in the library.
36
+
37
+ ## 0.1.6 (12 Nov 2026)
4
38
 
5
39
  - **Cards between scenes** (`Capture.cards` in `finish()`; `withCards`, `cardFrames`): a card shown for its time at a
6
40
  moment of the capture, in the title and end cards' look, fading in and out. A narrated card lasts as long as its
package/README.md CHANGED
@@ -155,6 +155,91 @@ frames move with the holds. GIFs from the same render keep the original timing.
155
155
  `<out>.narration.txt`. `suggest --task narration` drafts spoken lines from the steps (nothing typed is sent) for a
156
156
  person to edit and pass with `--script`.
157
157
 
158
+ ## Campaigns
159
+
160
+ A product's marketing videos, in every look and shape, from one `campaign.json`:
161
+
162
+ ```json
163
+ {
164
+ "product": "acme", "site": "https://acme.com", "narrator": "gateway",
165
+ "app": {
166
+ "name": "Acme", "url": "http://127.0.0.1:3000", "dir": "..", "start": ["npm", "run", "demo"], "ready": "/login",
167
+ "guides": "demo/guides.json", "storageState": "demo/storage-state.json",
168
+ "reset": { "post": "http://127.0.0.1:3001/demo/reset" }, "alias": "acme.com"
169
+ },
170
+ "looks": { "product": { "brand": "brands/acme.json" } },
171
+ "videos": [
172
+ { "id": "intro", "kind": "intro", "guide": "send-your-first-invoice", "mode": "perform",
173
+ "shapes": ["16:9", "1:1", "9:16"], "voice": { "product": "scripts/intro.json" }, "polish": ["--title-card"],
174
+ "alt": "Acme sends a first invoice: the customer picked, two lines added, then Send." },
175
+ { "id": "ad-paid", "kind": "ad", "director": "directors/ad-paid.mjs", "page": "/invoices",
176
+ "shapes": ["9:16", "1:1"], "voice": { "product": "scripts/ad-paid.json" }, "reset": { "start": "paid" },
177
+ "alt": "Acme ad: an invoice marked paid the moment the transfer lands." }
178
+ ]
179
+ }
180
+ ```
181
+
182
+ ```bash
183
+ trace-avatar-render campaign check # every problem at once (guides, scripts' lines, looks …)
184
+ trace-avatar-render campaign make --start # start the app, make every render; or name video ids
185
+ trace-avatar-render campaign status # from another terminal: done, failed, what it's on now
186
+ ```
187
+
188
+ - Each video is made per look. The desktop shapes (16:9, 1:1, 4:5) come from one capture, each on its own canvas,
189
+ with captions as a file; 9:16 is captured again at a phone's size with its captions burned in.
190
+ - A video is a **guide** (an id in `app.guides`, or a `.trace.json`) or a **director script**:
191
+
192
+ ```js
193
+ export default async function (d) {
194
+ await d.card('Get paid the day you send it.'); // a card between scenes, spoken when narrated
195
+ await d.scene('Pick the customer, add two lines, send.', async () => {
196
+ await d.click(d.page.getByRole('button', { name: 'New invoice' })); // real mouse events; cursor drawn after
197
+ await d.type(d.page.getByLabel('Customer'), 'Ada Stores');
198
+ await d.read(600);
199
+ });
200
+ await d.skip(async () => { /* a long wait, cut to a jump */ });
201
+ }
202
+ ```
203
+
204
+ Line *n* of a narration script is scene *n* (cards count). Narrated, the captions are the spoken lines.
205
+ - `app.reset` puts the app back before every video (the video's `reset` is the body), so a video made twice looks
206
+ the same. `app.alias` shows it under its public name, answered locally.
207
+ - Files go to `out/<product>/` with `made.json`, each render's `.scenes.json` (its words in order, for a
208
+ catalogue's `says`) and `progress.json`. A run stopped part way carries on; `--fresh` starts over.
209
+
210
+ ## A clip catalogue
211
+
212
+ Published videos are listed in a **clip catalogue**: a public JSON file (`trace-avatar-catalogue/1`, schema in
213
+ [`schemas/catalogue-1.json`](schemas/catalogue-1.json), also at https://traceavatar.com/schemas/catalogue-1.json).
214
+ It has one entry per file and shape, each with its link, length, captions, description (`alt`) and its own words in
215
+ order (`says`), so a scheduler can pick a clip and write a post that matches it.
216
+
217
+ ```json
218
+ { "spec": "trace-avatar-catalogue/1", "updated": "2026-11-12T22:54:29Z", "videos": [{
219
+ "id": "acme/ad-paid/product/1:1", "product": "acme", "video": "ad-paid", "kind": "ad", "preset": "product",
220
+ "shape": "1:1", "format": "mp4", "url": "https://cdn.acme.com/ad-paid-1x1-0123456789.mp4",
221
+ "poster": "https://cdn.acme.com/ad-paid-1x1-aaaaaaaaaa.png", "captions": "https://cdn.acme.com/ad-paid-1x1-bbbbbbbbbb.vtt",
222
+ "language": "en", "captionsBurned": false, "seconds": 12.5, "narrated": true, "title": null,
223
+ "alt": "Acme ad: an invoice marked paid the moment the transfer lands.",
224
+ "says": ["Get paid the day you send it.", "Marked paid when the transfer lands."],
225
+ "site": "https://acme.com", "endsWith": "For more info visit acme.com", "made": "2026-11-12T21:54:32Z" }] }
226
+ ```
227
+
228
+ - `id` stays the same when a clip is re-rendered (`<product>/<video>/<preset>/<shape|gif>`); `url` changes. Name files
229
+ by their content and cache them forever; cache the catalogue itself briefly.
230
+ - `captions` is WebVTT, present only when the words aren't burned in (`captionsBurned`).
231
+ - `says` is what the viewer reads or hears: the captions (the spoken lines when narrated) and the cards' lines.
232
+ - Unknown fields are allowed.
233
+
234
+ ```bash
235
+ trace-avatar-render catalogue check catalogue.json # every field, unique ids
236
+ trace-avatar-render catalogue check https://…/catalogue.json --fetch
237
+ # …and every link: answers without cookies with the right type; captions end within the video;
238
+ # the mp4 is H.264 (AAC when narrated) with its moov first (-movflags +faststart)
239
+ ```
240
+
241
+ `checkCatalogue(doc, { fetch })` does the same from code (`{ ok, problems, warnings }`).
242
+
158
243
  ## From code
159
244
 
160
245
  ```js