Skip to content

Commit 9fb140e

Browse files
committed
fix(media-use): wire --avatar-id/--voice-id CLI flags and close video-provider auth/cache gaps
- resolve.mjs never implemented the --avatar-id/--voice-id override that operations.md documented, so following the docs crashed with ERR_PARSE_ARGS_UNKNOWN_OPTION; wire the flags through to ctx. - defaultAvatarId/defaultStarfishVoiceId cached a failed discovery lookup as a permanent null, disabling heygen.video after one transient miss; cache only a truthy id, matching the same fix in voice-provider.mjs's defaultVoiceId. - the avatar-video onboarding nudge only fired on a video-create failure, never when avatar/voice discovery itself was unauthenticated (the common unauthenticated case) -- propagate the discovery failure reason so onboarding fires either way. - dedupe the CLI-shelling JSON helper (heygen-cli.mjs's new runHeygenJson) and the local-model argv-template builder (local-models.mjs's new buildArgv) instead of leaving byte-identical copies in each provider.
1 parent e1a91f3 commit 9fb140e

10 files changed

Lines changed: 165 additions & 76 deletions

‎skills-manifest.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@
4646
"files": 10
4747
},
4848
"media-use": {
49-
"hash": "022c8e6ca929dcf1",
49+
"hash": "60a3e05409c3ed40",
5050
"files": 139
5151
},
5252
"motion-graphics": {

‎skills/media-use/scripts/lib/heygen-cli.mjs‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { execFileSync } from "node:child_process";
12
import { track } from "./telemetry.mjs";
23

34
// v0.3.0 is the first CLI that can use an OAuth session; v0.1.x/0.2.x reject it
@@ -133,6 +134,30 @@ export async function flushHeygenFailureTracking() {
133134
await Promise.all(pendingFailureTracking);
134135
}
135136

137+
// Shared discovery/generation helper for the CLI-shelling providers (voice,
138+
// avatar-video): run a heygen JSON subcommand, report+classify on failure,
139+
// and hand the caller the classified reason via onError (used by callers that
140+
// need to distinguish e.g. not_authenticated from other failures).
141+
export function runHeygenJson(bin, argv, label, onError) {
142+
let out;
143+
try {
144+
out = execFileSync(bin, argv, {
145+
encoding: "utf8",
146+
timeout: 120000,
147+
stdio: ["pipe", "pipe", "pipe"],
148+
});
149+
} catch (err) {
150+
reportHeygenFailure(err, `${bin} ${label}`);
151+
onError?.(classifyHeygenErrorCode(err));
152+
return null;
153+
}
154+
try {
155+
return JSON.parse(out);
156+
} catch {
157+
return null;
158+
}
159+
}
160+
136161
export function firstSemver(text) {
137162
const match = String(text || "").match(/\bv?(\d+)\.(\d+)\.(\d+)\b/);
138163
return match ? `${match[1]}.${match[2]}.${match[3]}` : null;

‎skills/media-use/scripts/lib/heygen-video-provider.mjs‎

Lines changed: 27 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -7,55 +7,54 @@ import {
77
HEYGEN_AUTH_COMMAND,
88
HEYGEN_CLIENT_SOURCE_ARGV,
99
reportHeygenFailure,
10+
runHeygenJson,
1011
} from "./heygen-cli.mjs";
1112

12-
function runJson(bin, argv, label) {
13-
let out;
14-
try {
15-
out = execFileSync(bin, argv, {
16-
encoding: "utf8",
17-
timeout: 120000,
18-
stdio: ["pipe", "pipe", "pipe"],
19-
});
20-
} catch (err) {
21-
reportHeygenFailure(err, `${bin} ${label}`);
22-
return null;
23-
}
24-
try {
25-
return JSON.parse(out);
26-
} catch {
27-
return null;
28-
}
29-
}
30-
13+
// Cache only a truthy id -- a transient discovery failure must not poison the
14+
// cache with `null` and permanently disable heygen.video for the rest of the
15+
// process. `onError` lets the caller distinguish not_authenticated (and nudge
16+
// onboarding) from any other discovery failure.
3117
let cachedAvatarId;
32-
function defaultAvatarId() {
33-
if (cachedAvatarId !== undefined) return cachedAvatarId;
34-
const j = runJson(
18+
function defaultAvatarId(onError) {
19+
if (cachedAvatarId) return cachedAvatarId;
20+
const j = runHeygenJson(
3521
"heygen",
3622
["avatar", "list", "--ownership", "public", "--limit", "1"],
3723
"avatar list",
24+
onError,
3825
);
3926
cachedAvatarId = j?.data?.[0]?.avatar_id || null;
4027
return cachedAvatarId;
4128
}
4229

4330
let cachedStarfishVoiceId;
44-
function defaultStarfishVoiceId() {
45-
if (cachedStarfishVoiceId !== undefined) return cachedStarfishVoiceId;
46-
const j = runJson(
31+
function defaultStarfishVoiceId(onError) {
32+
if (cachedStarfishVoiceId) return cachedStarfishVoiceId;
33+
const j = runHeygenJson(
4734
"heygen",
4835
["voice", "list", "--engine", "starfish", "--limit", "1"],
4936
"voice list",
37+
onError,
5038
);
5139
cachedStarfishVoiceId = j?.data?.[0]?.voice_id || null;
5240
return cachedStarfishVoiceId;
5341
}
5442

5543
export async function heygenVideoGenerate(intent, ctx) {
56-
const avatarId = ctx?.avatarId || defaultAvatarId();
57-
const voiceId = ctx?.voiceId || defaultStarfishVoiceId();
58-
if (!avatarId || !voiceId) return null;
44+
let discoveryFailureReason = null;
45+
const captureReason = (reason) => {
46+
discoveryFailureReason ??= reason;
47+
};
48+
const avatarId = ctx?.avatarId || defaultAvatarId(captureReason);
49+
const voiceId = ctx?.voiceId || defaultStarfishVoiceId(captureReason);
50+
if (!avatarId || !voiceId) {
51+
if (discoveryFailureReason === "not_authenticated") {
52+
console.error(
53+
`media-use: avatar video is free for new API users — sign in: ${HEYGEN_AUTH_COMMAND}`,
54+
);
55+
}
56+
return null;
57+
}
5958

6059
let out;
6160
try {

‎skills/media-use/scripts/lib/heygen-video-provider.test.mjs‎

Lines changed: 58 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,19 @@ async function listenVideoServer() {
3737
};
3838
}
3939

40+
async function listenFailingVideoServer() {
41+
const server = http.createServer((req, res) => {
42+
res.writeHead(500).end();
43+
});
44+
await new Promise((resolve) => server.listen(0, resolve));
45+
const address = server.address();
46+
assert.ok(address && typeof address !== "string");
47+
return {
48+
server,
49+
url: `http://127.0.0.1:${address.port}/video.mp4`,
50+
};
51+
}
52+
4053
function closeServer(server) {
4154
return new Promise((resolve, reject) => {
4255
server.close((err) => (err ? reject(err) : resolve()));
@@ -52,6 +65,7 @@ async function withFakeHeygen(options, run) {
5265
HEYGEN_CAPTURE_PATH: process.env.HEYGEN_CAPTURE_PATH,
5366
HEYGEN_VIDEO_MODE: process.env.HEYGEN_VIDEO_MODE,
5467
HEYGEN_VIDEO_RESPONSE: process.env.HEYGEN_VIDEO_RESPONSE,
68+
HEYGEN_DISCOVERY_MODE: process.env.HEYGEN_DISCOVERY_MODE,
5569
HYPERFRAMES_NO_TELEMETRY: process.env.HYPERFRAMES_NO_TELEMETRY,
5670
};
5771

@@ -60,7 +74,12 @@ async function withFakeHeygen(options, run) {
6074
`#!/bin/sh
6175
printf '%s\\n' "$*" >> "$HEYGEN_CAPTURE_PATH"
6276
case "$*" in
63-
*"avatar list"*) printf '%s\\n' '{"data":[{"avatar_id":"avatar-public-1"}]}' ;;
77+
*"avatar list"*)
78+
case "$HEYGEN_DISCOVERY_MODE" in
79+
auth) printf '%s\\n' 'HTTP 401 Unauthorized' >&2; exit 1 ;;
80+
*) printf '%s\\n' '{"data":[{"avatar_id":"avatar-public-1"}]}' ;;
81+
esac
82+
;;
6483
*"voice list"*) printf '%s\\n' '{"data":[{"voice_id":"voice-starfish-1"}]}' ;;
6584
*"video create"*)
6685
case "$HEYGEN_VIDEO_MODE" in
@@ -77,6 +96,7 @@ esac
7796
process.env.HEYGEN_CAPTURE_PATH = capturePath;
7897
process.env.HEYGEN_VIDEO_MODE = options.mode ?? "success";
7998
process.env.HEYGEN_VIDEO_RESPONSE = options.response ?? "";
99+
process.env.HEYGEN_DISCOVERY_MODE = options.discoveryMode ?? "";
80100
process.env.HYPERFRAMES_NO_TELEMETRY = "1";
81101

82102
try {
@@ -275,3 +295,40 @@ test("falls through on non-JSON and error responses", async (t) => {
275295
});
276296
}
277297
});
298+
299+
test("onboards and returns null when avatar/voice discovery itself is unauthenticated", async (t) => {
300+
const errors = [];
301+
t.mock.method(console, "error", (message) => errors.push(message));
302+
303+
await withFakeHeygen({ discoveryMode: "auth" }, async ({ invocations }) => {
304+
const heygenVideoGenerate = await freshGenerate();
305+
const result = await heygenVideoGenerate("Discovery auth failure", {});
306+
307+
assert.equal(result, null);
308+
assert.ok(errors.includes(ONBOARDING_MESSAGE));
309+
const calls = invocations();
310+
assert.equal(
311+
calls.filter((call) => call.includes("video create")).length,
312+
0,
313+
"must not attempt video create once discovery is unauthenticated",
314+
);
315+
assert.match(calls[0], /^avatar list /);
316+
});
317+
});
318+
319+
test("download failure after a successful create returns null and logs a diagnostic", async () => {
320+
const { server, url } = await listenFailingVideoServer();
321+
try {
322+
await withFakeHeygen({ response: JSON.stringify({ data: { video_url: url } }) }, async () => {
323+
const heygenVideoGenerate = await freshGenerate();
324+
const result = await heygenVideoGenerate("Download failure", {
325+
avatarId: "avatar-override",
326+
voiceId: "voice-override",
327+
});
328+
329+
assert.equal(result, null);
330+
});
331+
} finally {
332+
await closeServer(server);
333+
}
334+
});

‎skills/media-use/scripts/lib/local-models.mjs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,6 +205,17 @@ export function listModels(capability) {
205205
return tableFor(capability).slice();
206206
}
207207

208+
// Tokenize an `invoke` template on whitespace first, then substitute each
209+
// token, so a `{prompt}`/`{model_path}` value with spaces stays a single argv
210+
// entry. Shared by every local-model provider (mflux, LTX) that builds argv
211+
// from a MODELS[...].invoke template.
212+
export function buildArgv(template, vars) {
213+
return template
214+
.trim()
215+
.split(/\s+/)
216+
.map((tok) => tok.replace(/\{(\w+)\}/g, (_, k) => (k in vars ? String(vars[k]) : `{${k}}`)));
217+
}
218+
208219
/** Does this machine meet a model's needs? Apple Silicon unified memory counts as VRAM. */
209220
export function meetsSpecs(model, specs) {
210221
const n = model.needs || {};

‎skills/media-use/scripts/lib/ltx-video-provider.mjs‎

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,7 @@ import { existsSync } from "node:fs";
33
import { tmpdir } from "node:os";
44
import { join } from "node:path";
55
import { probeSpecs } from "./specs.mjs";
6-
import { selectModel } from "./local-models.mjs";
7-
8-
// Tokenize the invoke template on whitespace first, then substitute each token,
9-
// so a prompt with spaces stays a single argv entry.
10-
function buildArgv(template, vars) {
11-
return template
12-
.trim()
13-
.split(/\s+/)
14-
.map((tok) => tok.replace(/\{(\w+)\}/g, (_, k) => (k in vars ? String(vars[k]) : `{${k}}`)));
15-
}
6+
import { buildArgv, selectModel } from "./local-models.mjs";
167

178
export async function ltxVideoGenerate(
189
intent,

‎skills/media-use/scripts/lib/mflux-provider.mjs‎

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import { existsSync } from "node:fs";
33
import { tmpdir } from "node:os";
44
import { join } from "node:path";
55
import { probeSpecs } from "./specs.mjs";
6-
import { selectModel } from "./local-models.mjs";
6+
import { buildArgv, selectModel } from "./local-models.mjs";
77

88
// Local image generation via mflux (FLUX-on-MLX), the Mac-native runner.
99
// Spec-gated: selectModel("imagegen", specs) returns the best FLUX-class model
@@ -15,15 +15,6 @@ import { selectModel } from "./local-models.mjs";
1515
// non-gated community 4-bit re-uploads; the repo is resolved to a local snapshot
1616
// (hf download, idempotent) because a bare repo id breaks mlx unflatten.
1717

18-
// Tokenize the invoke template on whitespace FIRST, then substitute each token,
19-
// so a {prompt}/{model_path} value with spaces stays a single argv entry.
20-
function buildArgv(template, vars) {
21-
return template
22-
.trim()
23-
.split(/\s+/)
24-
.map((tok) => tok.replace(/\{(\w+)\}/g, (_, k) => (k in vars ? String(vars[k]) : `{${k}}`)));
25-
}
26-
2718
// Resolve an HF repo to its local snapshot dir. `hf download` is idempotent and
2819
// prints the snapshot path as its last line.
2920
function resolveSnapshot(repo) {

‎skills/media-use/scripts/lib/voice-provider.mjs‎

Lines changed: 7 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,9 @@
1-
import { execFileSync } from "node:child_process";
2-
import { HEYGEN_CLIENT_SOURCE_ARGV, reportHeygenFailure } from "./heygen-cli.mjs";
1+
import { HEYGEN_CLIENT_SOURCE_ARGV, runHeygenJson } from "./heygen-cli.mjs";
32

43
// Voice / TTS generation via the HeyGen CLI — the only external CLI media-use
54
// shells (CLI-only invariant: media-use holds no keys; the CLI owns auth).
65
// Flags verified against `heygen voice speech create --help` (v0.3.0).
76

8-
function runJson(bin, argv, label) {
9-
let out;
10-
try {
11-
out = execFileSync(bin, argv, {
12-
encoding: "utf8",
13-
timeout: 120000,
14-
stdio: ["pipe", "pipe", "pipe"],
15-
});
16-
} catch (err) {
17-
reportHeygenFailure(err, `${bin} ${label}`);
18-
return null;
19-
}
20-
try {
21-
return JSON.parse(out);
22-
} catch {
23-
return null;
24-
}
25-
}
26-
277
function result(url, duration, provider, intent) {
288
if (!url) return null;
299
return {
@@ -41,11 +21,13 @@ function result(url, duration, provider, intent) {
4121
// HeyGen TTS requires a starfish-engine voice. Default to the first one the
4222
// catalog returns (deterministic order); pass ctx.voiceId to override.
4323
// ponytail: listed once per process; the resolved asset is frozen + cached after
44-
// first use, so the network list only happens on a cache miss.
24+
// first use, so the network list only happens on a cache miss. Cache only a
25+
// truthy id -- a transient list failure must not poison the cache with `null`
26+
// and permanently disable TTS for the rest of the process.
4527
let cachedVoiceId;
4628
function defaultVoiceId() {
47-
if (cachedVoiceId !== undefined) return cachedVoiceId;
48-
const j = runJson(
29+
if (cachedVoiceId) return cachedVoiceId;
30+
const j = runHeygenJson(
4931
"heygen",
5032
["voice", "list", "--engine", "starfish", "--limit", "1"],
5133
"voice list",
@@ -57,7 +39,7 @@ function defaultVoiceId() {
5739
export async function heygenTtsGenerate(intent, ctx) {
5840
const voiceId = ctx?.voiceId || defaultVoiceId();
5941
if (!voiceId) return null;
60-
const p = runJson(
42+
const p = runHeygenJson(
6143
"heygen",
6244
[
6345
...HEYGEN_CLIENT_SOURCE_ARGV,

‎skills/media-use/scripts/resolve.mjs‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,8 @@ const { values: args } = parseArgs({
7474
for: { type: "string" },
7575
"local-only": { type: "boolean", default: false },
7676
provider: { type: "string" },
77+
"avatar-id": { type: "string" },
78+
"voice-id": { type: "string" },
7779
json: { type: "boolean", default: false },
7880
help: { type: "boolean", short: "h", default: false },
7981
},
@@ -108,6 +110,8 @@ Options:
108110
suggestions (grade only)
109111
--local-only Offline: skip every network provider
110112
--provider Force one generator (e.g. codex, mflux, kokoro, heygen)
113+
--avatar-id Override the default avatar for heygen.video generation
114+
--voice-id Override the default voice for voice/heygen.video generation
111115
--json Output JSON instead of one-line result
112116
--help, -h Show this help`);
113117
process.exit(0);
@@ -354,7 +358,14 @@ async function run() {
354358
// Offline guard: --local-only skips every remote provider (HeyGen catalog),
355359
// leaving the project + global cache and any local provider.
356360
const localOnly = args["local-only"];
357-
const ctx = { entity, projectDir, localOnly, provider: args.provider };
361+
const ctx = {
362+
entity,
363+
projectDir,
364+
localOnly,
365+
provider: args.provider,
366+
avatarId: args["avatar-id"],
367+
voiceId: args["voice-id"],
368+
};
358369

359370
// Adherence nudge (offline, no auto-reuse): the exact-cache floor missed and
360371
// we're about to fetch/generate. If lexically-similar assets already exist,

‎skills/media-use/scripts/resolve.test.mjs‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -510,6 +510,28 @@ test("--from uses .mp4 as the default video extension", () => {
510510
cleanup();
511511
});
512512

513+
test("--avatar-id/--voice-id parse as real CLI flags (regression guard: docs promise them, parseArgs must not reject them)", () => {
514+
setup();
515+
const result = spawnResolve(
516+
[
517+
"--type",
518+
"video",
519+
"--intent",
520+
"regression guard",
521+
"--local-only",
522+
"--avatar-id",
523+
"avatar-override",
524+
"--voice-id",
525+
"voice-override",
526+
"--project",
527+
tmp,
528+
],
529+
{ stdio: "pipe" },
530+
);
531+
assert.doesNotMatch(result.stderr || "", /ERR_PARSE_ARGS_UNKNOWN_OPTION/);
532+
cleanup();
533+
});
534+
513535
test("unknown type error lists grade and lut", () => {
514536
try {
515537
runResolve(["--type", "bogus", "--intent", "x"], { stdio: "pipe" });

0 commit comments

Comments
 (0)