fix(cli): escape audio and media-use output, pin model files (#8013)

* fix(cli): audio and media-use print control characters from project files as visible escapes

hyperframes audio, audio --read and media-use resolve (including
--candidates) printed file names, element ids, transcript words, model
descriptions and media manifest fields as they were. They now pass
through terminalText, so a control character shows as a visible \xNN
escape. The media-use engine runs without the CLI's packages, so it
carries a small copy of the helper. --json output is unchanged.

* fix(engine): playlist check refuses drive-relative and other colon-prefixed entries

ffmpeg reads an HLS or ffconcat entry with a colon before its first
separator as a URL or a drive, and opens it apart from the list's
folder. The folder check read entries such as C:Videos\a.mp4 or c:x.mp4
as names inside the folder and approved them. It now refuses any entry,
raw or percent-decoded, whose colon comes before its first /, \, ? or #,
as it already refuses absolute and parent-folder paths. http and https
segments are still kept.

* fix(cli): background-removal and Kokoro TTS model files are pinned to a sha256

The u2net_human_seg weights and the Kokoro model and voices files were
downloaded from release URLs and used whatever bytes arrived, and any
cached copy was trusted because it existed. Each file now has a pinned
size and sha256. A cached copy is checked before it is loaded and
downloaded again when it does not match. A download that does not
match is discarded with a message that names the file.

* fix(engine): playlist check reads entries from the folder ffmpeg uses

ffmpeg resolves a list's entries against its path cut at the first ? or
#. A list at proj/h#z/list.m3u8 naming ../h#z/x.ts was judged against
proj/h#z and approved, while ffmpeg opened proj/../h#z/x.ts. Entries are
now judged against the same cut folder. A list in a folder such as
"Take #2" still passes when its entries resolve inside that folder.

* fix(cli): a pinned model's cached copy is checked and removed under the download lock

ensurePinnedFile removed a cached copy that failed its check before the
download lock was taken, so a concurrent run could delete a file another
run had just published. downloadFile now takes a keepExisting check and
runs it under the lock: a copy that passes is kept, one that fails is
removed and downloaded again. The mismatch error now says the file does
not match its expected checksum, and that a retry helps only if the
download was interrupted or corrupted.

* fix(cli): audio escapes each field's line breaks, and media-use escapes recipe and stats output

The audio formatters escaped their output line by line, so a newline
inside a src, warning or transcript still printed as a real line break.
Each output line is now escaped whole with terminalText, which shows a
newline inside a field as \x0a. media-use resolve also escapes its
recipe lines and its --stats lines, which print recipe names, paths and
missed intents.

* fix(cli): media-use error messages show control characters as visible escapes

resolve printed error messages as they were, and some name project or
cache data, such as the known recipe names when a recipe is not found.
Every error: line now passes through terminalText, as the success lines
already do.

* ci: the edit accuracy filter includes the CLI model file check

The CLI's pinned model download now imports whisper/modelFile.ts, so a
change to it must run the edit accuracy bench too.

* test(cli): pinned model tests use private temp folders and rename like downloadFile

The tests wrote fixtures under fixed names in the shared temp folder,
and their download stand-in checked for a file before replacing it.
Each test now works in its own mkdtemp folder, and the stand-in asks
keepExisting directly and renames the part file into place, as
downloadFile does.

* test(cli): the media-use terminalText copy is checked against core's

The media-use engine keeps its own copy of terminalText. A CLI test now
compares the two over U+0000 to U+00A0, so a change to either fails
until both match. keepsDest moves above downloadFile's doc comment,
which belongs to downloadFile.
This commit is contained in:
Michael Wang
2026-11-17 07:16:03 +00:00
committed by GitHub
parent e21f56dcad
commit c4439890cf
21 changed files with 531 additions and 63 deletions
+1
View File
@@ -245,6 +245,7 @@ jobs:
- "packages/cli/src/server/**"
- "packages/cli/src/browser/**"
- "packages/cli/src/utils/**"
- "packages/cli/src/whisper/modelFile.ts"
- "packages/cli/src/ui/**"
- "packages/cli/src/{background-removal,registry,telemetry}/**"
- "packages/cli/src/capture/{captureCompositionFrame,captureTimeout,navigateForCapture,readBoundedResponse}.ts"
@@ -27,6 +27,21 @@ describe("sparkline", () => {
});
describe("formatReport", () => {
it("prints control characters from the project's src, id, errors and warnings as visible escapes", () => {
const text = formatReport({
version: 1,
items: [
item({ file: "a\x1b[2K.wav", ref: "#x\x07", warnings: ["w\x1b]52;c;aGk=\x07", "a\nb"] }),
item({ file: "gone\x9b.wav", ref: null, error: "missing \x1b[8m" }),
],
});
expect(text).toContain("a\\x1b[2K.wav #x\\x07");
expect(text).toContain("! w\\x1b]52;c;aGk=\\x07");
expect(text).toContain("! a\\x0ab");
expect(text).toContain("gone\\x9b.wav: missing \\x1b[8m");
for (const raw of ["\x07", "\x1b", "\x9b"]) expect(text).not.toContain(raw);
});
it("prints file seconds as film seconds through the clip's placement", () => {
const text = formatReport({
version: 1,
+2 -1
View File
@@ -1,3 +1,4 @@
import { terminalText } from "@hyperframes/core";
import type {
Beats,
Downbeats,
@@ -147,5 +148,5 @@ function formatItem(item: AudioItem): string[] {
export function formatReport(report: AudioReport): string {
if (report.items.length === 0) return "No audio matched.";
return report.items.map((item) => formatItem(item).join("\n")).join("\n\n");
return report.items.map((item) => formatItem(item).map(terminalText).join("\n")).join("\n\n");
}
@@ -41,6 +41,26 @@ function read(voiceLufs: number, musicLufs: number): ReadAudio {
}
describe("formatRead", () => {
it("prints control characters from the transcript, descriptions and file name as visible escapes", () => {
const base = read(-14, -18);
const text = formatRead({
...base,
file: "talk\x1b[2K.wav",
description: { overall: "calm\x1b]8;;https://x.test\x07", bgmPrompt: null },
voice: {
...base.voice!,
sentences: [{ ...base.voice!.sentences[0]!, text: "hi\x1b]52;c;aGk=\x07" }],
},
warnings: ["w\x1b[8m", "a\nb"],
});
expect(text).toContain("talk\\x1b[2K.wav");
expect(text).toContain("overall: calm\\x1b]8;;https://x.test\\x07");
expect(text).toContain('"hi\\x1b]52;c;aGk=\\x07"');
expect(text).toContain("! w\\x1b[8m");
expect(text).toContain("! a\\x0ab");
for (const raw of ["\x07", "\x1b"]) expect(text).not.toContain(raw);
});
it.each([
[-24, -20, "voice -24 LUFS, music -20 LUFS: music 4 dB over voice"],
[-14, -18, "voice -14 LUFS, music -18 LUFS: voice 4 dB over music"],
+4 -3
View File
@@ -1,3 +1,4 @@
import { terminalText } from "@hyperframes/core";
import type { Span } from "@hyperframes/core/audio-analysis";
import { semitones } from "./pitch.js";
import type {
@@ -272,7 +273,7 @@ export function formatRead(analysis: ReadAudio, range?: [number, number]): strin
const width = Math.max(0, ...lines.map((l) => when(l).length));
const body = lines.map((l) => `${when(l).padEnd(width)} ${l.kind.padEnd(KIND_WIDTH)} ${l.text}`);
const warnings = analysis.warnings.map((w) => `! ${w}`);
return [...header(analysis), "", ...body, ...(warnings.length ? ["", ...warnings] : [])].join(
"\n",
);
return [...header(analysis), "", ...body, ...(warnings.length ? ["", ...warnings] : [])]
.map(terminalText)
.join("\n");
}
@@ -0,0 +1,55 @@
import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { afterAll, afterEach, expect, it, vi } from "vitest";
import { ensureModel, modelPath } from "./manager.js";
const cache = await vi.hoisted(async () => {
const { mkdtempSync } = await import("node:fs");
const { tmpdir } = await import("node:os");
const dir = mkdtempSync(`${tmpdir()}/hf-bgrm-pin-`);
process.env["HYPERFRAMES_CACHE_DIR"] = dir;
return dir;
});
vi.mock("../utils/download.js", () => ({
downloadFile: vi.fn(
async (
_url: string,
dest: string,
options: {
keepExisting: (path: string) => Promise<boolean>;
verify: (path: string) => Promise<void>;
},
) => {
if (await options.keepExisting(dest)) return;
rmSync(dest, { force: true });
writeFileSync(`${dest}.part`, "swapped weights");
await options.verify(`${dest}.part`).catch((error: unknown) => {
rmSync(`${dest}.part`);
throw error;
});
renameSync(`${dest}.part`, dest);
},
),
}));
afterEach(() => rmSync(cache, { recursive: true, force: true }));
afterAll(() => {
delete process.env["HYPERFRAMES_CACHE_DIR"];
});
it("refuses downloaded weights that do not match the pinned sha256", async () => {
await expect(ensureModel()).rejects.toThrow(
/u2net_human_seg\.onnx was discarded because it does not match/,
);
expect(existsSync(modelPath())).toBe(false);
});
it("does not load cached weights that do not match the pinned sha256", async () => {
mkdirSync(join(modelPath(), ".."), { recursive: true });
writeFileSync(modelPath(), "swapped weights");
await expect(ensureModel()).rejects.toThrow(/was discarded because it does not match/);
expect(existsSync(modelPath())).toBe(false);
});
+14 -13
View File
@@ -1,7 +1,7 @@
import { existsSync, mkdirSync } from "node:fs";
import { platform, arch } from "node:os";
import { join } from "node:path";
import { downloadFile } from "../utils/download.js";
import { ensurePinnedFile } from "../utils/pinnedFile.js";
import type { ModelFile } from "../whisper/modelFile.js";
import { hyperframesCacheDir } from "@hyperframes/core/cache-dir";
export const MODELS_DIR = hyperframesCacheDir("background-removal", "models");
@@ -14,6 +14,14 @@ const MODEL_URLS: Record<ModelId, string> = {
"https://github.com/danielgatis/rembg/releases/download/v0.0.0/u2net_human_seg.onnx",
};
const MODEL_PINS: Record<ModelId, ModelFile> = {
u2net_human_seg: {
name: "u2net_human_seg.onnx",
bytes: 175_997_641,
sha256: "01eb6a29a5c4d8edb30b56adad9bb3a2a0535338e480724a213e0acfd2d1c73c",
},
};
export const MODEL_MEMORY_MB: Record<ModelId, number> = {
u2net_human_seg: 1500,
};
@@ -83,15 +91,8 @@ export async function ensureModel(
model: ModelId = DEFAULT_MODEL,
options?: { onProgress?: (message: string) => void },
): Promise<string> {
const dest = modelPath(model);
if (existsSync(dest)) return dest;
mkdirSync(MODELS_DIR, { recursive: true });
options?.onProgress?.(`Downloading ${model} weights (~168 MB)...`);
await downloadFile(MODEL_URLS[model], dest);
if (!existsSync(dest)) {
throw new Error(`Model download failed: ${model}`);
}
return dest;
return ensurePinnedFile(MODEL_URLS[model], modelPath(model), MODEL_PINS[model], {
downloading: `Downloading ${model} weights (~168 MB)...`,
onProgress: options?.onProgress,
});
}
+4 -1
View File
@@ -1,4 +1,5 @@
import { join, resolve } from "node:path";
import { terminalText } from "@hyperframes/core";
import { defineCommand } from "../utils/defineCommand.js";
import type {
AnalysisQuality,
@@ -205,7 +206,9 @@ async function read(files: string[], flags: AudioFlags) {
console.log(JSON.stringify(withMeta(result)));
return;
}
console.log(`${formatRead(result.analysis, range)}\n\nwhole recording: ${result.textPath}`);
console.log(
`${formatRead(result.analysis, range)}\n\nwhole recording: ${terminalText(result.textPath)}`,
);
}
export default defineCommand({
@@ -8,6 +8,7 @@
import { currentRecords } from "./manifest.mjs";
import { readGlobalManifest } from "./cache.mjs";
import { tokenOverlap, typesMatch } from "./match.mjs";
import { terminalText } from "./terminal-text.mjs";
export const CANDIDATE_CAP = 8;
@@ -78,8 +79,8 @@ export function formatCandidates(candidates, { truncated, total } = {}) {
const handle =
c.scope === "global" ? `--reuse ${String(c.sha).slice(0, 16)}` : c.path || `manifest:${c.id}`;
const m = meta(c);
lines.push(` [${c.scope}] ${c.description}${m ? ` (${m})` : ""}`);
lines.push(` ${handle}`);
lines.push(terminalText(` [${c.scope}] ${c.description}${m ? ` (${m})` : ""}`));
lines.push(terminalText(` ${handle}`));
}
if (truncated && total) {
lines.push("");
@@ -153,3 +153,19 @@ test("formatCandidates shows reuse handles by scope; empty message", () => {
assert.match(out, /--reuse ffffffffffffffff/);
assert.match(formatCandidates([], {}), /no reuse candidates/);
});
test("formatCandidates prints control characters from the manifest as visible escapes", () => {
const text = formatCandidates([
{
scope: "project",
id: "bgm_001",
path: ".media/audio/bgm/\x1b[2Kbgm_001.wav",
description: "calm piano\x1b]52;c;aGk=\x07",
score: 1,
},
]);
assert.ok(text.includes("calm piano\\x1b]52;c;aGk=\\x07"), text);
assert.ok(text.includes(".media/audio/bgm/\\x1b[2Kbgm_001.wav"), text);
for (const raw of ["\x07", "\x1b"])
assert.ok(!text.includes(raw), "no raw control character is left");
});
@@ -0,0 +1 @@
export function terminalText(value: unknown): string;
@@ -0,0 +1,12 @@
// The media-use engine runs without the CLI's packages installed, so it keeps its own copy of
// core's terminalText: control characters print as visible \xNN escapes, tabs stay as they are.
const isControlCode = (code) => (code < 0x20 && code !== 0x09) || (code >= 0x7f && code <= 0x9f);
export function terminalText(value) {
let shown = "";
for (const ch of String(value)) {
const code = ch.charCodeAt(0);
shown += isControlCode(code) ? `\\x${code.toString(16).padStart(2, "0")}` : ch;
}
return shown;
}
+21 -15
View File
@@ -69,6 +69,7 @@ import {
scoreMatch,
} from "./lib/sfx-provider.mjs";
import { writeSfxCredit } from "./lib/openverse.mjs";
import { terminalText } from "./lib/terminal-text.mjs";
import { mediaVectorRows, rankMediaRowsWithVectors } from "./lib/local-media-search.mjs";
const INGEST_TYPES = listTypes();
@@ -179,7 +180,7 @@ if (args.adopt) {
console.log("no new assets to adopt (assets/ empty or already registered)");
} else {
console.log(`adopted ${adopted.length} asset${adopted.length === 1 ? "" : "s"} from assets/`);
for (const r of adopted) console.log(` ${r.id} → ${r.path} (${r.type})`);
for (const r of adopted) console.log(terminalText(` ${r.id} → ${r.path} (${r.type})`));
}
process.exit(0);
}
@@ -280,11 +281,14 @@ if (type === "recipe") {
console.log(JSON.stringify({ ok: true, ...used }));
} else {
console.log(
`resolved recipe ${used.recipe.name} (v${used.recipe.version}, ${used.recipe.workflow})`,
terminalText(
`resolved recipe ${used.recipe.name} (v${used.recipe.version}, ${used.recipe.workflow})`,
),
);
console.log(` frame spec → ${used.frameSpecPath} (copied over)`);
console.log(` storyboard skeleton → ${used.skeletonPath}`);
if (used.briefSkeletonPath) console.log(` brief skeleton → ${used.briefSkeletonPath}`);
console.log(terminalText(` frame spec → ${used.frameSpecPath} (copied over)`));
console.log(terminalText(` storyboard skeleton → ${used.skeletonPath}`));
if (used.briefSkeletonPath)
console.log(terminalText(` brief skeleton → ${used.briefSkeletonPath}`));
}
process.exit(0);
} catch (err) {
@@ -553,7 +557,7 @@ async function run() {
}),
);
} else {
console.error(`error: ${msg}`);
console.error(terminalText(`error: ${msg}`));
}
process.exit(1);
}
@@ -671,7 +675,7 @@ function exitError(message, status = 1) {
if (args.json) {
console.log(JSON.stringify({ ok: false, error: message }));
} else {
console.error(`error: ${message}`);
console.error(terminalText(`error: ${message}`));
}
process.exit(status);
}
@@ -743,7 +747,7 @@ async function colorMiss(type, intent) {
if (args.json) {
console.log(JSON.stringify({ ok: false, error: msg }));
} else {
console.error(`error: ${msg}`);
console.error(terminalText(`error: ${msg}`));
}
process.exit(1);
}
@@ -1184,8 +1188,8 @@ function printStats(report) {
return;
}
for (const [type, misses] of entries) {
console.log(` ${type}:`);
for (const miss of misses) console.log(` ${miss.count} ${miss.intent}`);
console.log(terminalText(` ${type}:`));
for (const miss of misses) console.log(terminalText(` ${miss.count} ${miss.intent}`));
}
}
@@ -1196,7 +1200,7 @@ function printMap(label, values) {
console.log(" none");
return;
}
for (const [key, value] of entries) console.log(` ${key}: ${value}`);
for (const [key, value] of entries) console.log(terminalText(` ${key}: ${value}`));
}
function ffDoctorCheck(name, binary) {
@@ -1280,7 +1284,7 @@ async function reuseGlobal(shaArg) {
}
// Do not import an asset under the wrong type.
if (!typesMatch(rec.type, type)) {
console.error(`error: sha "${shaArg}" is a ${rec.type} asset, not ${type}`);
console.error(terminalText(`error: sha "${shaArg}" is a ${rec.type} asset, not ${type}`));
process.exit(2);
}
const ext = extname(rec.cached_path || "") || defaultExt(type);
@@ -1308,7 +1312,9 @@ function warnLowConfidence(record, match) {
? `found by its file name, resolved earlier for "${match.resolved_for}"`
: `found by its file name, sharing ${match.matched_words.length} of ${match.intent_words} words`;
console.error(
`media-use: low-confidence match for "${intent}": ${record.description || record.path} (${why}). Listen before placing it, or resolve again with other words.`,
terminalText(
`media-use: low-confidence match for "${intent}": ${record.description || record.path} (${why}). Listen before placing it, or resolve again with other words.`,
),
);
}
@@ -1367,7 +1373,7 @@ async function result(record, source, match = recordedMatch(record)) {
);
} else {
const meta = formatMeta(record, source);
console.log(`resolved ${record.id} → ${record.path || "inline"} (${meta})`);
console.log(terminalText(`resolved ${record.id} → ${record.path || "inline"} (${meta})`));
}
}
@@ -1399,7 +1405,7 @@ run().catch((err) => {
if (args.json) {
console.log(JSON.stringify({ ok: false, error: err.message }));
} else {
console.error(`error: ${err.message}`);
console.error(terminalText(`error: ${err.message}`));
}
process.exit(1);
});
@@ -524,6 +524,67 @@ test("project manifest hit skips providers", () => {
cleanup();
});
test("a manifest hit prints control characters from the record as visible escapes", () => {
setup();
const record = makeRecord({
id: "bgm_001\x1b]52;c;aGk=\x07",
provenance: { prompt: "cached query", provider: "test" },
});
appendRecord(tmp, record);
const filePath = join(tmp, record.path);
mkdirSync(join(filePath, ".."), { recursive: true });
writeFileSync(filePath, "cached audio");
const out = runResolve(["--type", "bgm", "--intent", "cached query", "--project", tmp]);
assert.ok(out.includes("resolved bgm_001\\x1b]52;c;aGk=\\x07 →"), out);
for (const raw of ["\x07", "\x1b"])
assert.ok(!out.includes(raw), "no raw control character reaches the terminal");
const json = JSON.parse(
runResolve(["--type", "bgm", "--intent", "cached query", "--project", tmp, "--json"]).trim(),
);
assert.equal(json.id, record.id, "--json keeps the record as it is");
cleanup();
});
test("recipe and stats output print control characters as visible escapes", () => {
setup();
try {
const recipe = join(tmp, ".media", "recipes", "promo");
mkdirSync(recipe, { recursive: true });
const name = "promo\x1b[2K";
writeFileSync(
join(recipe, "recipe.json"),
JSON.stringify({ name, version: 1, workflow: "w\x07" }),
);
writeFileSync(join(recipe, "frame.md"), "# frame\n");
const used = runResolve(["--type", "recipe", "--entity", "promo", "--project", tmp]);
assert.ok(used.includes("resolved recipe promo\\x1b[2K (v1, w\\x07)"), used);
const missing = spawnResolve(["--type", "recipe", "--entity", "nope", "--project", tmp]);
assert.notEqual(missing.status, 0);
assert.ok(missing.stderr.includes("known: promo\\x1b[2K"), missing.stderr);
for (const raw of ["\x07", "\x1b"])
assert.ok(!missing.stderr.includes(raw), "no raw control character reaches the terminal");
const home = join(process.env.HYPERFRAMES_MEDIA_HOME, ".media");
mkdirSync(home, { recursive: true });
const miss = {
ts: new Date().toISOString(),
type: "sfx\x1b[8m",
intent: "boom\x1b]52;c;agk=\x07",
};
writeFileSync(join(home, "misses.jsonl"), `${JSON.stringify(miss)}\n`);
const stats = runResolve(["--stats", "--project", tmp]);
assert.ok(stats.includes(" sfx\\x1b[8m:"), stats);
assert.ok(stats.includes("boom\\x1b]52;c;agk=\\x07"), stats);
for (const out of [used, stats])
for (const raw of ["\x07", "\x1b"])
assert.ok(!out.includes(raw), "no raw control character reaches the terminal");
} finally {
cleanup();
}
});
test("entity hit matches across icon/image (figma-imported brand marks)", () => {
setup();
const record = makeRecord({
@@ -0,0 +1,10 @@
import { terminalText as coreTerminalText } from "@hyperframes/core";
import { expect, it } from "vitest";
import { terminalText } from "./lib/terminal-text.mjs";
it("the media-use copy of terminalText escapes every character as core's does", () => {
for (let code = 0; code <= 0xa0; code++) {
const text = `a${String.fromCharCode(code)}b`;
expect(terminalText(text), `U+${code.toString(16)}`).toBe(coreTerminalText(text));
}
});
+78
View File
@@ -0,0 +1,78 @@
import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { afterAll, afterEach, expect, it, vi } from "vitest";
import { ensureModel, ensureVoices } from "./manager.js";
const cache = await vi.hoisted(async () => {
const { mkdtempSync } = await import("node:fs");
const { tmpdir } = await import("node:os");
const dir = mkdtempSync(`${tmpdir()}/hf-tts-pin-`);
process.env["HYPERFRAMES_CACHE_DIR"] = dir;
return dir;
});
vi.mock("../utils/download.js", () => ({
downloadFile: vi.fn(
async (
_url: string,
dest: string,
options: {
keepExisting: (path: string) => Promise<boolean>;
verify: (path: string) => Promise<void>;
},
) => {
if (await options.keepExisting(dest)) return;
rmSync(dest, { force: true });
writeFileSync(`${dest}.part`, "swapped");
await options.verify(`${dest}.part`).catch((error: unknown) => {
rmSync(`${dest}.part`);
throw error;
});
renameSync(`${dest}.part`, dest);
},
),
}));
const model = join(cache, "tts", "models", "kokoro-v1.0.onnx");
const voices = join(cache, "tts", "voices", "voices-v1.0.bin");
afterEach(() => rmSync(cache, { recursive: true, force: true }));
afterAll(() => {
delete process.env["HYPERFRAMES_CACHE_DIR"];
});
it.each([
[
"model",
() => ensureModel(),
model,
/kokoro-v1\.0\.onnx was discarded because it does not match/,
],
[
"voices",
() => ensureVoices(),
voices,
/voices-v1\.0\.bin was discarded because it does not match/,
],
])(
"refuses a downloaded %s file that does not match the pinned sha256",
async (_k, run, path, error) => {
await expect(run()).rejects.toThrow(error);
expect(existsSync(path)).toBe(false);
},
);
it.each([
["model", () => ensureModel(), model],
["voices", () => ensureVoices(), voices],
])(
"does not load a cached %s file that does not match the pinned sha256",
async (_k, run, path) => {
mkdirSync(join(path, ".."), { recursive: true });
writeFileSync(path, "swapped");
await expect(run()).rejects.toThrow(/was discarded because it does not match/);
expect(existsSync(path)).toBe(false);
},
);
+26 -27
View File
@@ -1,6 +1,6 @@
import { existsSync, mkdirSync } from "node:fs";
import { join } from "node:path";
import { downloadFile } from "../utils/download.js";
import { ensurePinnedFile } from "../utils/pinnedFile.js";
import type { ModelFile } from "../whisper/modelFile.js";
import { hyperframesCacheDir } from "@hyperframes/core/cache-dir";
const CACHE_DIR = hyperframesCacheDir("tts");
@@ -14,9 +14,23 @@ const MODEL_URLS: Record<string, string> = {
"https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/kokoro-v1.0.onnx",
};
const MODEL_PINS: Record<string, ModelFile> = {
"kokoro-v1.0": {
name: "kokoro-v1.0.onnx",
bytes: 325_532_387,
sha256: "7d5df8ecf7d4b1878015a32686053fd0eebe2bc377234608764cc0ef3636a6c5",
},
};
const VOICES_URL =
"https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/voices-v1.0.bin";
const VOICES_PIN: ModelFile = {
name: "voices-v1.0.bin",
bytes: 28_214_398,
sha256: "bca610b8308e8d99f32e6fe4197e7ec01679264efed0cac9140fe9c29f1fbf7d",
};
// Locale codes accepted by Kokoro's phonemizer (misaki for English,
// espeak-ng for everything else). Kept as a readonly tuple so the union
// type below stays driven by this single source.
@@ -103,25 +117,18 @@ export async function ensureModel(
model: string = DEFAULT_MODEL,
options?: { onProgress?: (message: string) => void },
): Promise<string> {
const modelPath = join(MODELS_DIR, `${model}.onnx`);
if (existsSync(modelPath)) return modelPath;
const url = MODEL_URLS[model];
if (!url) {
const pin = MODEL_PINS[model];
if (!url || !pin) {
throw new Error(
`Unknown TTS model: ${model}. Available: ${Object.keys(MODEL_URLS).join(", ")}`,
);
}
mkdirSync(MODELS_DIR, { recursive: true });
options?.onProgress?.(`Downloading TTS model ${model} (~311 MB)...`);
await downloadFile(url, modelPath);
if (!existsSync(modelPath)) {
throw new Error(`Model download failed: ${model}`);
}
return modelPath;
return ensurePinnedFile(url, join(MODELS_DIR, `${model}.onnx`), pin, {
downloading: `Downloading TTS model ${model} (~311 MB)...`,
onProgress: options?.onProgress,
});
}
/**
@@ -131,18 +138,10 @@ export async function ensureModel(
export async function ensureVoices(options?: {
onProgress?: (message: string) => void;
}): Promise<string> {
const voicesPath = join(VOICES_DIR, "voices-v1.0.bin");
if (existsSync(voicesPath)) return voicesPath;
mkdirSync(VOICES_DIR, { recursive: true });
options?.onProgress?.("Downloading voice data (~27 MB)...");
await downloadFile(VOICES_URL, voicesPath);
if (!existsSync(voicesPath)) {
throw new Error("Voice data download failed");
}
return voicesPath;
return ensurePinnedFile(VOICES_URL, join(VOICES_DIR, VOICES_PIN.name), VOICES_PIN, {
downloading: "Downloading voice data (~27 MB)...",
onProgress: options?.onProgress,
});
}
export { MODELS_DIR, DEFAULT_MODEL };
+37
View File
@@ -693,6 +693,43 @@ describe("resuming across runs", () => {
expect(readdirSync(dir)).toEqual(["model.onnx"]);
});
it("checks a file already at dest under the lock, and replaces it when the check refuses", async () => {
const dir = mkdtempSync(join(tmpdir(), "hyperframes-download-"));
tempDirs.push(dir);
const dest = join(dir, "model.onnx");
writeFileSync(dest, "stale");
mockGet.mockImplementation(rangedHost("hello", '"v1"', []));
const locked: boolean[] = [];
const keep = async (path: string) => {
locked.push(readdirSync(dir).includes("model.onnx.lock"));
return readFileSync(path, "utf8") === "hello";
};
await downloadFile(url, dest, { keepExisting: keep });
expect(readFileSync(dest, "utf8")).toBe("hello");
await downloadFile(url, dest, { keepExisting: keep });
expect(mockGet).toHaveBeenCalledTimes(1);
expect(locked).toEqual([true, true]);
});
it("removes a refused file at dest when the fresh download is refused too", async () => {
const dir = mkdtempSync(join(tmpdir(), "hyperframes-download-"));
tempDirs.push(dir);
const dest = join(dir, "model.onnx");
writeFileSync(dest, "stale");
mockGet.mockImplementation(rangedHost("hello", '"v1"', []));
await expect(
downloadFile(url, dest, {
keepExisting: async () => false,
verify: async () => Promise.reject(new Error("bad sha")),
}),
).rejects.toThrow("bad sha");
expect(readdirSync(dir)).toEqual([]);
});
it("discards a finished file its check refuses", async () => {
const { dir, dest } = stoppedRun("hel", '"v1"');
mockGet.mockImplementation(rangedHost("hello", '"v1"', []));
+14 -1
View File
@@ -33,6 +33,7 @@ export interface DownloadOptions {
signal?: AbortSignal;
/** Checks the finished file before it replaces `dest`; a throw discards it. */
verify?: (path: string) => Promise<void>;
keepExisting?: (path: string) => Promise<boolean>;
}
/** Every redirect a host may reasonably answer with, not just the two we saw first. */
@@ -425,6 +426,18 @@ async function downloadToPart(url: string, dest: string, options: DownloadOption
await publishPart(part, dest, options);
}
async function keepsDest(
dest: string,
waited: boolean,
options: DownloadOptions,
): Promise<boolean> {
if (!existsSync(dest)) return false;
if (!options.keepExisting) return waited;
if (await options.keepExisting(dest)) return true;
removePartialFile(dest);
return false;
}
/**
* Some networks drop every connection at the same byte, so a retry resumes from the partial file.
* The partial file and its validator survive a stopped run, so the next run resumes it too.
@@ -437,7 +450,7 @@ export async function downloadFile(
const lock = `${dest}.lock`;
const { owner, waited } = await acquireLock(lock, options.signal);
try {
if (!(waited && existsSync(dest))) await downloadToPart(url, dest, options);
if (!(await keepsDest(dest, waited, options))) await downloadToPart(url, dest, options);
} finally {
heldLocks.delete(owner);
if (readLock(lock) === owner) removePartialFile(lock);
+100
View File
@@ -0,0 +1,100 @@
import { createHash } from "node:crypto";
import {
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
readdirSync,
renameSync,
rmSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, expect, it, vi } from "vitest";
import { downloadFile } from "./download.js";
import { ensurePinnedFile } from "./pinnedFile.js";
const served = vi.hoisted(() => ({ bytes: "model" }));
vi.mock("./download.js", () => ({
downloadFile: vi.fn(
async (
_url: string,
dest: string,
options: {
keepExisting: (path: string) => Promise<boolean>;
verify: (path: string) => Promise<void>;
},
) => {
if (await options.keepExisting(dest)) return;
rmSync(dest, { force: true });
writeFileSync(`${dest}.part`, served.bytes);
await options.verify(`${dest}.part`).catch((error: unknown) => {
rmSync(`${dest}.part`);
throw error;
});
renameSync(`${dest}.part`, dest);
},
),
}));
let dir = "";
let dest = "";
const pin = {
name: "model.onnx",
bytes: 5,
sha256: createHash("sha256").update("model").digest("hex"),
};
const progress = { downloading: "Downloading model..." };
beforeEach(() => {
served.bytes = "model";
dir = mkdtempSync(join(tmpdir(), "hf-pinned-file-"));
dest = join(dir, "models", "model.onnx");
});
afterEach(() => {
rmSync(dir, { recursive: true, force: true });
vi.clearAllMocks();
});
it("uses a cached file that matches its pin without downloading it", async () => {
mkdirSync(join(dir, "models"));
writeFileSync(dest, "model");
await expect(ensurePinnedFile("https://x.test/m", dest, pin, progress)).resolves.toBe(dest);
expect(downloadFile).not.toHaveBeenCalled();
});
it("downloads a file that matches its pin", async () => {
await expect(ensurePinnedFile("https://x.test/m", dest, pin, progress)).resolves.toBe(dest);
expect(readFileSync(dest, "utf8")).toBe("model");
});
it("replaces a cached file of the same size that does not match its pin", async () => {
mkdirSync(join(dir, "models"));
writeFileSync(dest, "other");
const onProgress = vi.fn();
await ensurePinnedFile("https://x.test/m", dest, pin, { ...progress, onProgress });
expect(readFileSync(dest, "utf8")).toBe("model");
expect(onProgress).toHaveBeenCalledWith(
"The cached model.onnx does not match its pinned sha256; downloading it again...",
);
});
it("discards a download that does not match its pin and refuses it", async () => {
served.bytes = "swapped";
mkdirSync(join(dir, "models"));
writeFileSync(dest, "other");
await expect(ensurePinnedFile("https://x.test/m", dest, pin, progress)).rejects.toThrow(
"model.onnx was discarded because it does not match its expected size and sha256. " +
"Retrying helps only if the download was interrupted or corrupted.",
);
expect(existsSync(dest)).toBe(false);
expect(readdirSync(join(dir, "models"))).toEqual([]);
});
+37
View File
@@ -0,0 +1,37 @@
import { mkdirSync, statSync } from "node:fs";
import { dirname } from "node:path";
import { verifies, type ModelFile } from "../whisper/modelFile.js";
import { downloadFile } from "./download.js";
/**
* `dest` once it holds the pinned bytes: a cached copy that matches is used as it is, any other
* copy is replaced by a fresh download, and a download that does not match is discarded.
*/
export async function ensurePinnedFile(
url: string,
dest: string,
pin: ModelFile,
progress: { downloading: string; onProgress?: (message: string) => void },
): Promise<string> {
const cached = statSync(dest, { throwIfNoEntry: false }) !== undefined;
if (cached && (await verifies(dest, pin))) return dest;
mkdirSync(dirname(dest), { recursive: true });
progress.onProgress?.(
cached
? `The cached ${pin.name} does not match its pinned sha256; downloading it again...`
: progress.downloading,
);
await downloadFile(url, dest, {
keepExisting: (path) => verifies(path, pin),
verify: async (path) => {
if (!(await verifies(path, pin))) {
throw new Error(
`${pin.name} was discarded because it does not match its expected size and sha256. ` +
"Retrying helps only if the download was interrupted or corrupted.",
);
}
},
});
return dest;
}