trace-avatar-render 0.1.6 → 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 +12 -1
- package/README.md +33 -0
- package/dist/{chunk-ZNHFXKD3.js → chunk-PPVNEPXF.js} +162 -2
- 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 +83 -1
- package/dist/index.js +19 -1
- package/package.json +4 -2
- package/schemas/catalogue-1.json +48 -0
- package/dist/chunk-ZNHFXKD3.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,17 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
## 0.1.
|
|
3
|
+
## 0.1.7 (unreleased)
|
|
4
|
+
|
|
5
|
+
- **The clip catalogue, `trace-avatar-catalogue/1`** (`schemas/catalogue-1.json`, also at
|
|
6
|
+
https://traceavatar.com/schemas/catalogue-1.json): a public JSON file of a product's published videos, one entry per
|
|
7
|
+
file and shape, with each clip's own words (`says`), so a scheduler can post it and write about it truthfully.
|
|
8
|
+
- `trace-avatar-render catalogue check <file|url> [--fetch]` checks one: every field, unique ids, burned captions
|
|
9
|
+
with no captions file. With `--fetch` it checks the links too: they answer without cookies, with the right type;
|
|
10
|
+
the captions end within the video; the mp4 is H.264 (with AAC sound when narrated) and starts playing before it
|
|
11
|
+
has all loaded (`moov` first).
|
|
12
|
+
- `checkCatalogue()`, `catalogueId()`, `vttEnds()`, `mp4Head()` in the library.
|
|
13
|
+
|
|
14
|
+
## 0.1.6 (12 Nov 2026)
|
|
4
15
|
|
|
5
16
|
- **Cards between scenes** (`Capture.cards` in `finish()`; `withCards`, `cardFrames`): a card shown for its time at a
|
|
6
17
|
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,39 @@ 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
|
+
## A clip catalogue
|
|
159
|
+
|
|
160
|
+
Published videos are listed in a **clip catalogue**: a public JSON file (`trace-avatar-catalogue/1`, schema in
|
|
161
|
+
[`schemas/catalogue-1.json`](schemas/catalogue-1.json), also at https://traceavatar.com/schemas/catalogue-1.json).
|
|
162
|
+
It has one entry per file and shape, each with its link, length, captions, description (`alt`) and its own words in
|
|
163
|
+
order (`says`), so a scheduler can pick a clip and write a post that matches it.
|
|
164
|
+
|
|
165
|
+
```json
|
|
166
|
+
{ "spec": "trace-avatar-catalogue/1", "updated": "2026-11-12T22:54:29Z", "videos": [{
|
|
167
|
+
"id": "acme/ad-paid/product/1:1", "product": "acme", "video": "ad-paid", "kind": "ad", "preset": "product",
|
|
168
|
+
"shape": "1:1", "format": "mp4", "url": "https://cdn.acme.com/ad-paid-1x1-0123456789.mp4",
|
|
169
|
+
"poster": "https://cdn.acme.com/ad-paid-1x1-aaaaaaaaaa.png", "captions": "https://cdn.acme.com/ad-paid-1x1-bbbbbbbbbb.vtt",
|
|
170
|
+
"language": "en", "captionsBurned": false, "seconds": 12.5, "narrated": true, "title": null,
|
|
171
|
+
"alt": "Acme ad: an invoice marked paid the moment the transfer lands.",
|
|
172
|
+
"says": ["Get paid the day you send it.", "Marked paid when the transfer lands."],
|
|
173
|
+
"site": "https://acme.com", "endsWith": "For more info visit acme.com", "made": "2026-11-12T21:54:32Z" }] }
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
- `id` stays the same when a clip is re-rendered (`<product>/<video>/<preset>/<shape|gif>`); `url` changes. Name files
|
|
177
|
+
by their content and cache them forever; cache the catalogue itself briefly.
|
|
178
|
+
- `captions` is WebVTT, present only when the words aren't burned in (`captionsBurned`).
|
|
179
|
+
- `says` is what the viewer reads or hears: the captions (the spoken lines when narrated) and the cards' lines.
|
|
180
|
+
- Unknown fields are allowed.
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
trace-avatar-render catalogue check catalogue.json # every field, unique ids
|
|
184
|
+
trace-avatar-render catalogue check https://…/catalogue.json --fetch
|
|
185
|
+
# …and every link: answers without cookies with the right type; captions end within the video;
|
|
186
|
+
# the mp4 is H.264 (AAC when narrated) with its moov first (-movflags +faststart)
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
`checkCatalogue(doc, { fetch })` does the same from code (`{ ok, problems, warnings }`).
|
|
190
|
+
|
|
158
191
|
## From code
|
|
159
192
|
|
|
160
193
|
```js
|
|
@@ -1949,6 +1949,157 @@ async function voiceOf(spec, env = process.env, o = {}) {
|
|
|
1949
1949
|
throw new Error(`--voice is gateway[:gemini[/<model>][:<voice>]], openai:<model>[:<voice>], say[:<voice>], or a .js file (got "${spec}")`);
|
|
1950
1950
|
}
|
|
1951
1951
|
|
|
1952
|
+
// src/catalogue.ts
|
|
1953
|
+
var CATALOGUE_SPEC = "trace-avatar-catalogue/1";
|
|
1954
|
+
var CATALOGUE_KINDS = ["intro", "demo", "guide", "onboarding", "pitch", "whats-new", "ad", "docs-gif", "qa", "support"];
|
|
1955
|
+
var CATALOGUE_SHAPES = ["16:9", "1:1", "4:5", "9:16"];
|
|
1956
|
+
var CATALOGUE_FORMATS = ["mp4", "gif"];
|
|
1957
|
+
var CATALOGUE_REQUIRED = ["id", "product", "video", "kind", "preset", "shape", "format", "url", "captionsBurned", "seconds", "narrated", "alt", "site", "made"];
|
|
1958
|
+
function catalogueId(e) {
|
|
1959
|
+
return `${e.product}/${e.video}/${e.preset}/${e.format === "gif" || !e.shape ? "gif" : e.shape}`;
|
|
1960
|
+
}
|
|
1961
|
+
var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
|
|
1962
|
+
var isTime = (v) => typeof v === "string" && /^\d{4}-\d{2}-\d{2}T/.test(v) && !Number.isNaN(Date.parse(v));
|
|
1963
|
+
var isHttps = (v) => {
|
|
1964
|
+
if (typeof v !== "string") return false;
|
|
1965
|
+
try {
|
|
1966
|
+
return new URL(v).protocol === "https:";
|
|
1967
|
+
} catch {
|
|
1968
|
+
return false;
|
|
1969
|
+
}
|
|
1970
|
+
};
|
|
1971
|
+
function checkShape(doc, problems, warnings, https) {
|
|
1972
|
+
if (!isObj(doc)) {
|
|
1973
|
+
problems.push("a catalogue is a JSON object { spec, updated, videos }");
|
|
1974
|
+
return [];
|
|
1975
|
+
}
|
|
1976
|
+
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}`);
|
|
1977
|
+
if (!isTime(doc.updated)) problems.push("updated is an ISO time");
|
|
1978
|
+
if (!Array.isArray(doc.videos)) {
|
|
1979
|
+
problems.push("videos is a list");
|
|
1980
|
+
return [];
|
|
1981
|
+
}
|
|
1982
|
+
const ids = /* @__PURE__ */ new Map();
|
|
1983
|
+
const tuples = /* @__PURE__ */ new Map();
|
|
1984
|
+
const good = [];
|
|
1985
|
+
doc.videos.forEach((v, i) => {
|
|
1986
|
+
const at = `videos[${i}]${isObj(v) && typeof v.id === "string" ? ` (${v.id})` : ""}`;
|
|
1987
|
+
if (!isObj(v)) {
|
|
1988
|
+
problems.push(`${at}: an entry is an object`);
|
|
1989
|
+
return;
|
|
1990
|
+
}
|
|
1991
|
+
const before = problems.length;
|
|
1992
|
+
const p = (m) => problems.push(`${at}: ${m}`);
|
|
1993
|
+
for (const k of CATALOGUE_REQUIRED) if (v[k] === void 0) p(`no ${k}`);
|
|
1994
|
+
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`);
|
|
1995
|
+
if (v.kind !== void 0 && !CATALOGUE_KINDS.includes(v.kind)) p(`kind is one of ${CATALOGUE_KINDS.join(", ")}`);
|
|
1996
|
+
if (v.format !== void 0 && !CATALOGUE_FORMATS.includes(v.format)) p("format is mp4 or gif");
|
|
1997
|
+
if (v.format === "gif" && v.shape !== null && v.shape !== void 0) p("a GIF has no shape (null)");
|
|
1998
|
+
if (v.format === "mp4" && !CATALOGUE_SHAPES.includes(v.shape)) p(`an mp4's shape is one of ${CATALOGUE_SHAPES.join(", ")}`);
|
|
1999
|
+
for (const k of ["url", "site"]) if (v[k] !== void 0 && !https(v[k])) p(`${k} is an https link`);
|
|
2000
|
+
for (const k of ["poster", "captions"]) if (v[k] !== void 0 && !https(v[k])) p(`${k} is an https link`);
|
|
2001
|
+
if (v.captionsBurned !== void 0 && typeof v.captionsBurned !== "boolean") p("captionsBurned is true or false");
|
|
2002
|
+
if (v.narrated !== void 0 && typeof v.narrated !== "boolean") p("narrated is true or false");
|
|
2003
|
+
if (v.captions !== void 0 && v.captionsBurned === true) p("captions are burned in, so it has no captions file");
|
|
2004
|
+
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");
|
|
2005
|
+
if (v.language !== void 0 && !(typeof v.language === "string" && /^[a-z]{2}$/.test(v.language))) p("language is two lowercase letters, e.g. en");
|
|
2006
|
+
if (v.title !== void 0 && v.title !== null && typeof v.title !== "string") p("title is text or null");
|
|
2007
|
+
if (v.alt !== void 0 && !(typeof v.alt === "string" && v.alt.trim())) p("alt says what it shows");
|
|
2008
|
+
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");
|
|
2009
|
+
if (v.endsWith !== void 0 && typeof v.endsWith !== "string") p("endsWith is text");
|
|
2010
|
+
if (v.made !== void 0 && !isTime(v.made)) p("made is an ISO time");
|
|
2011
|
+
if (problems.length > before) return;
|
|
2012
|
+
const e = v;
|
|
2013
|
+
const seen = ids.get(e.id);
|
|
2014
|
+
if (seen !== void 0) p(`id used twice (videos[${seen}])`);
|
|
2015
|
+
else ids.set(e.id, i);
|
|
2016
|
+
const tuple = `${e.product}/${e.video}/${e.preset}/${e.shape}/${e.format}`;
|
|
2017
|
+
const twin = tuples.get(tuple);
|
|
2018
|
+
if (twin !== void 0) p(`the same product, video, preset, shape and format as videos[${twin}]`);
|
|
2019
|
+
else tuples.set(tuple, i);
|
|
2020
|
+
if (e.id !== catalogueId(e)) warnings.push(`${at}: the id ${catalogueId(e)} is recommended (stable across re-renders)`);
|
|
2021
|
+
if (e.format === "mp4" && !e.captionsBurned && !e.captions && e.says?.length) warnings.push(`${at}: it has words but no captions file`);
|
|
2022
|
+
good.push(e);
|
|
2023
|
+
});
|
|
2024
|
+
return good;
|
|
2025
|
+
}
|
|
2026
|
+
function vttEnds(text) {
|
|
2027
|
+
if (!/^?WEBVTT(?:[ \t].*)?(?:\r?\n|$)/.test(text)) throw new Error("not WebVTT (it does not start with WEBVTT)");
|
|
2028
|
+
const ends = [];
|
|
2029
|
+
const re = /(?:(\d+):)?(\d{2}):(\d{2})\.(\d{3})\s+-->\s+(?:(\d+):)?(\d{2}):(\d{2})\.(\d{3})/g;
|
|
2030
|
+
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);
|
|
2031
|
+
return ends;
|
|
2032
|
+
}
|
|
2033
|
+
function mp4Head(bytes) {
|
|
2034
|
+
const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
|
|
2035
|
+
const name = (at2) => String.fromCharCode(bytes[at2], bytes[at2 + 1], bytes[at2 + 2], bytes[at2 + 3]);
|
|
2036
|
+
let at = 0;
|
|
2037
|
+
while (at + 8 <= bytes.length) {
|
|
2038
|
+
let size = dv.getUint32(at);
|
|
2039
|
+
const type = name(at + 4);
|
|
2040
|
+
if (size === 1 && at + 16 <= bytes.length) size = Number(dv.getBigUint64(at + 8));
|
|
2041
|
+
if (type === "mdat") return { faststart: false, codecs: null };
|
|
2042
|
+
if (type === "moov") {
|
|
2043
|
+
if (size < 8 || at + size > bytes.length) return { faststart: true, codecs: null };
|
|
2044
|
+
const body = new TextDecoder("latin1").decode(bytes.subarray(at, at + size));
|
|
2045
|
+
return { faststart: true, codecs: ["avc1", "avc3", "hvc1", "hev1", "mp4a", "Opus"].filter((c) => body.includes(c)) };
|
|
2046
|
+
}
|
|
2047
|
+
if (size < 8) break;
|
|
2048
|
+
at += size;
|
|
2049
|
+
}
|
|
2050
|
+
return { faststart: null, codecs: null };
|
|
2051
|
+
}
|
|
2052
|
+
var TYPES = { mp4: /^video\/mp4\b/, gif: /^image\/gif\b/, poster: /^image\/(png|jpeg|webp)\b/, captions: /^text\/vtt\b/ };
|
|
2053
|
+
async function each(items, n, fn) {
|
|
2054
|
+
let i = 0;
|
|
2055
|
+
await Promise.all(Array.from({ length: Math.min(n, items.length) }, async () => {
|
|
2056
|
+
while (i < items.length) await fn(items[i++]);
|
|
2057
|
+
}));
|
|
2058
|
+
}
|
|
2059
|
+
async function checkCatalogue(doc, o = {}) {
|
|
2060
|
+
const problems = [];
|
|
2061
|
+
const warnings = [];
|
|
2062
|
+
const https = o.allowHttp ? (v) => isHttps(v) || typeof v === "string" && /^http:\/\//.test(v) : isHttps;
|
|
2063
|
+
const entries = checkShape(doc, problems, warnings, https);
|
|
2064
|
+
let fetched = 0;
|
|
2065
|
+
if (o.fetch) {
|
|
2066
|
+
const f = o.fetcher ?? fetch;
|
|
2067
|
+
const jobs = [];
|
|
2068
|
+
for (const e of entries) {
|
|
2069
|
+
jobs.push({ e, what: e.format, url: e.url });
|
|
2070
|
+
if (e.poster) jobs.push({ e, what: "poster", url: e.poster });
|
|
2071
|
+
if (e.captions) jobs.push({ e, what: "captions", url: e.captions });
|
|
2072
|
+
}
|
|
2073
|
+
await each(jobs, o.concurrency ?? 6, async ({ e, what, url }) => {
|
|
2074
|
+
const at = `${e.id} ${what}`;
|
|
2075
|
+
try {
|
|
2076
|
+
const res = await f(url, { headers: what === "captions" ? {} : { range: "bytes=0-262143" }, redirect: "follow" });
|
|
2077
|
+
fetched += 1;
|
|
2078
|
+
if (!res.ok) {
|
|
2079
|
+
problems.push(`${at}: ${url} answered ${res.status}`);
|
|
2080
|
+
return;
|
|
2081
|
+
}
|
|
2082
|
+
const type = res.headers.get("content-type") ?? "";
|
|
2083
|
+
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"}`);
|
|
2084
|
+
if (what === "captions") {
|
|
2085
|
+
const ends = vttEnds(await res.text());
|
|
2086
|
+
if (!ends.length) warnings.push(`${at}: the captions have no cues`);
|
|
2087
|
+
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`);
|
|
2088
|
+
} else if (what === "mp4") {
|
|
2089
|
+
const head = mp4Head(new Uint8Array(await res.arrayBuffer()));
|
|
2090
|
+
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)`);
|
|
2091
|
+
else if (head.faststart === null) warnings.push(`${at}: could not read its first boxes`);
|
|
2092
|
+
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`);
|
|
2093
|
+
if (head.codecs && e.narrated && !head.codecs.includes("mp4a")) problems.push(`${at}: narrated, but no AAC sound`);
|
|
2094
|
+
} else await res.body?.cancel();
|
|
2095
|
+
} catch (err) {
|
|
2096
|
+
problems.push(`${at}: ${err.message}`);
|
|
2097
|
+
}
|
|
2098
|
+
});
|
|
2099
|
+
}
|
|
2100
|
+
return { ok: !problems.length, problems, warnings, videos: entries.length, fetched };
|
|
2101
|
+
}
|
|
2102
|
+
|
|
1952
2103
|
export {
|
|
1953
2104
|
ZOOM_KINDS,
|
|
1954
2105
|
cameraKeys,
|
|
@@ -2026,6 +2177,15 @@ export {
|
|
|
2026
2177
|
openAiVoice,
|
|
2027
2178
|
sayVoice,
|
|
2028
2179
|
cached,
|
|
2029
|
-
voiceOf
|
|
2180
|
+
voiceOf,
|
|
2181
|
+
CATALOGUE_SPEC,
|
|
2182
|
+
CATALOGUE_KINDS,
|
|
2183
|
+
CATALOGUE_SHAPES,
|
|
2184
|
+
CATALOGUE_FORMATS,
|
|
2185
|
+
CATALOGUE_REQUIRED,
|
|
2186
|
+
catalogueId,
|
|
2187
|
+
vttEnds,
|
|
2188
|
+
mp4Head,
|
|
2189
|
+
checkCatalogue
|
|
2030
2190
|
};
|
|
2031
|
-
//# sourceMappingURL=chunk-
|
|
2191
|
+
//# sourceMappingURL=chunk-PPVNEPXF.js.map
|