fix(cli): media-use voices says whose clones it lists, and --voice takes language codes (#7261)

* fix(cli): media-use voices says whose clones it lists, and --voice takes language codes

`media-use voices` lists every clone the account's workspace can use, a teammate's
included, and HeyGen does not say who made each one. The command's description and
output (`whose`) now say so, and the style-sampling remix rule no longer reads
"One clone: use it": a clone is used only when the person names it as their own.

`--voice en`, `en-US`, `zh`, `zh-CN` and `cmn` were sent to HeyGen as language names
it does not list, so it answered with a multilingual voice ("Gail in car") and the CLI
used it. Codes now map to the English language name HeyGen lists, and a multilingual
voice offered for a language the request did not name is refused with the fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HebQXPiLcYKQfvPWB3Fgxy

* chore(skills): regenerate the skills manifest

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HebQXPiLcYKQfvPWB3Fgxy

* refactor(cli): keep languageName and the voices note module-private

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HebQXPiLcYKQfvPWB3Fgxy

* fix(skills): a clone's id is not consent; use one only when the person says it is theirs

The remix guide used a voice id the person gave, or a unique prefix of one,
without asking whose clone it was. The workspace list includes teammates'
clones, so either path could voice a film with someone else's clone. Both
paths, and the `whose` line of `media-use voices`, now use a clone only when
the person says it is theirs or that its owner agreed. An id that is not a
clone in the list is a stock voice and is used as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HebQXPiLcYKQfvPWB3Fgxy

* fix(skills): an id missing from the voices list is not a stock voice

`media-use voices` returns one page of private voices (20 by default), so a
teammate's clone can be absent from it. The remix guide treated an absent id
as stock and used it without asking. Now a given id or prefix is used only
when the person says it is theirs, that its owner agreed, or that it is a
HeyGen stock voice; otherwise the agent asks in its one round of questions.
The `whose` line says the list is one page and absence proves nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HebQXPiLcYKQfvPWB3Fgxy

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
WaterrrForever
2026-11-06 09:07:45 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 3e86def58e
commit fc0b53361b
7 changed files with 124 additions and 8 deletions
@@ -116,7 +116,8 @@ export default defineCommand({
script: { type: "string", description: "avatar, voice: the words spoken" },
voice: {
type: "string",
description: "avatar, voice: a HeyGen voice id, or a language for its first voice in it",
description:
"avatar, voice: a HeyGen voice id, or a language (English, Chinese, en, zh-CN) for its first voice in it",
},
seconds: {
type: "string",
@@ -0,0 +1,51 @@
import { mkdtempSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
vi.mock("../../cloud/auth.js", () => ({
resolveCloudAuthHeaders: async () => ({ "x-api-key": "k" }),
refreshIfNeeded: async <T>(credential: T) => credential,
resolveCloudBaseUrl: () => "https://api.test",
}));
const { default: voices } = await import("./voices.js");
beforeEach(() => {
vi.stubEnv("HYPERFRAMES_CONFIG_DIR", mkdtempSync(join(tmpdir(), "hf-voices-test-")));
});
afterEach(() => {
vi.unstubAllGlobals();
vi.unstubAllEnvs();
vi.restoreAllMocks();
});
describe("media-use voices", () => {
it("says the list is the workspace's, not the person's, so a teammate's clone is never taken as theirs", async () => {
vi.stubGlobal(
"fetch",
async () =>
new Response(
JSON.stringify({
data: [{ voice_id: "v1", name: "Teammate clone", language: "English" }],
}),
{ status: 200, headers: { "content-type": "application/json" } },
),
);
const out: string[] = [];
vi.spyOn(console, "log").mockImplementation((line: string) => void out.push(line));
await voices.run!({ args: { json: true } } as never);
const printed = JSON.parse(out.join("\n"));
expect(printed.voices).toEqual([
{ voice_id: "v1", name: "Teammate clone", language: "English", gender: undefined },
]);
expect(printed.whose).toMatch(/a teammate's included/);
expect(printed.whose).toMatch(/never pick one by count, language or name/);
expect(printed.whose).toMatch(
/says it is theirs or that its owner agreed, whether they name it or give its id/,
);
expect(printed.whose).toMatch(
/an id missing here may still be a teammate's clone, never proof of a stock voice/,
);
});
});
@@ -4,14 +4,17 @@ import { jsonArg, num, runMeasure } from "../../measure/command.js";
import { ownVoices } from "../../heygen/v3.js";
export const examples: Example[] = [
["The voice clones the film's own account can speak with", "hyperframes media-use voices"],
["The voice clones the film's workspace can speak with", "hyperframes media-use voices"],
];
const WHOSE =
"Every clone this workspace can use, a teammate's included: HeyGen does not say who made one. Use a clone only when the person says it is theirs or that its owner agreed, whether they name it or give its id; never pick one by count, language or name. This is one page of at most --limit, so an id missing here may still be a teammate's clone, never proof of a stock voice.";
export default defineCommand({
meta: {
name: "voices",
description:
"List the voice clones on the HyperFrames account that makes the film. Never use `heygen voice list` for this: that is a separate sign-in and can be another account",
"List the voice clones the HyperFrames account's workspace can use, a teammate's included. Use one only when the person names it as their own. Never use `heygen voice list` for this: that is a separate sign-in and can be another account",
},
args: {
limit: { type: "string", description: "How many to list (default 20)" },
@@ -20,6 +23,7 @@ export default defineCommand({
async run({ args }) {
await runMeasure(async () => ({
voices: await ownVoices(num(args.limit, "--limit", 20)),
whose: WHOSE,
}));
},
});
+46 -1
View File
@@ -1021,7 +1021,12 @@ describe("foldShort", () => {
});
describe("pickVoice", () => {
const voice = (id: string, name: string) => ({ voice_id: id.repeat(32), name, gender: "female" });
const voice = (id: string, name: string, language?: string) => ({
voice_id: id.repeat(32),
name,
gender: "female",
language,
});
let catalog = [voice("a", "Lin"), voice("b", "Wei")];
const asked: string[] = [];
const posts: { key: string | null; body: Record<string, unknown> }[] = [];
@@ -1061,6 +1066,46 @@ describe("pickVoice", () => {
expect(asked[0]).toBe("https://api.test/v3/voices?type=public&language=Chinese&limit=1");
});
for (const [spelled, language] of [
["en", "English"],
["en-US", "English"],
["zh-CN", "Chinese"],
["cmn", "Chinese"],
] as const) {
it(`asks for ${language} voices when --voice is the language code ${spelled}, not for multilingual ones`, async () => {
heygen();
catalog = [voice("a", "Lin", language)];
const r = {
type: "voice" as const,
out: join(project, `assets/${spelled}.mp3`),
voice: spelled,
};
expect((await pickVoice(r)).name).toBe("Lin");
expect(new URL(asked[0]!).searchParams.get("language")).toBe(language);
});
}
it("refuses the multilingual voice HeyGen offers for a language it does not list, instead of using it", async () => {
heygen();
catalog = [voice("g", "Gail in car", "Multilingual")];
const r = { type: "voice" as const, out: join(project, "assets/m.mp3"), voice: "Mandarin" };
await expect(pickVoice(r)).rejects.toMatchObject({
message: "HeyGen has no public voice for Mandarin (it offered a Multilingual one)",
fix: expect.stringContaining("English or Chinese"),
});
});
it("takes a multilingual voice when the request names Multilingual", async () => {
heygen();
catalog = [voice("g", "Gail in car", "Multilingual")];
const r = {
type: "voice" as const,
out: join(project, "assets/ml.mp3"),
voice: "Multilingual",
};
expect((await pickVoice(r)).name).toBe("Gail in car");
});
it("says what to do when HeyGen will not list its voices", async () => {
vi.stubGlobal(
"fetch",
+17 -2
View File
@@ -616,12 +616,27 @@ export async function pickVoice(r: GenerateRequest): Promise<Voice> {
]);
const kept = keptVoice(project, request);
if (kept) return kept;
const [voice] = await publicVoices(r.voice, 1);
if (!voice) throw new Fix(`HeyGen has no public voice for ${r.voice}`, "--voice <voice id>");
const language = languageName(r.voice);
const [voice] = await publicVoices(language, 1);
const named = voice?.language?.toLowerCase() === language.toLowerCase();
if (!voice || (!named && voice.language?.toLowerCase() === "multilingual"))
throw new Fix(
`HeyGen has no public voice for ${r.voice}${voice ? ` (it offered a ${voice.language} one)` : ""}`,
"--voice <the language's English name, e.g. English or Chinese>, or --voice <voice id>",
);
keepVoice(project, request, voice);
return voice;
}
const LANGUAGE_TAG = /^([a-z]{2,3})(?:[-_][a-z0-9]{2,8})*$/i;
const LANGUAGE_NAMES = new Intl.DisplayNames(["en"], { type: "language", fallback: "none" });
function languageName(spelled: string): string {
const tag = LANGUAGE_TAG.exec(spelled.trim());
if (!tag) return spelled;
return LANGUAGE_NAMES.of(tag[1]!.toLowerCase()) ?? spelled;
}
export function checkRequest(r: GenerateRequest): void {
const route = ROUTES[r.type];
if (!route.ext.includes(extname(r.out).toLowerCase()))
+1 -1
View File
@@ -34,7 +34,7 @@
"files": 2
},
"style-sampling": {
"hash": "e54aca29ef95de2e",
"hash": "5d26c6211fdfc062",
"files": 2
}
}
+1 -1
View File
@@ -23,7 +23,7 @@ The person's message carries what it carries. Ask once, together, only what is s
- **Never the creator's face, voice, footage, wordmark or show name.** That rule is about the creator: the person's own clone, their own recording or a credited stock voice are all fine.
- **A presenter runs on the plan.** Their own HeyGen avatar if they have one (`npx hyperframes media-use avatars` lists the looks on the HyperFrames account making the film; never `heygen avatar list`, a separate sign-in that can be another account), otherwise Avatar IV from their photo, both through `npx hyperframes media-use generate --type avatar` with the finished voice, so the lips land on it. HeyGen Video 1 is the fallback when neither works.
- **Settle the voice before any research.** A HeyGen voice id the person gave is the voice: use it and ask nothing. Only part of one (an 8-character prefix): find the full id in `npx hyperframes media-use voices` and ask only when no clone or several match. Anything else: run `npx hyperframes media-use voices`, which lists the clones on the HyperFrames account making the film; never `heygen voice list`, a separate sign-in that can be another account. One clone: use it. Several: ask which. None, or not signed in: ask once for their voice id, a clone they make in HeyGen from 30 s to 3 min of their own reading, or their own recorded narration; with none of these, say in one line that you'll use a HeyGen stock voice, name it in the credits as AI-generated, and go on. Nothing is voiced for it before stop 1: at the voice step, `npx hyperframes media-use generate --type voice --voice <the script's language> --script "<first line>" --out .media/pick.mp3 --plan` names HeyGen's first public voice in that language without making anything; set the kit's voice id to its `voice_id` and credit that voice by name. Nothing else starts until this is settled.
- **Settle the voice before any research.** A HeyGen voice id the person gave, or an 8-character prefix of one, is used only when they say it is theirs, that its owner agreed to this film, or that it is a HeyGen stock voice. Having the id is not that, and an id missing from `npx hyperframes media-use voices` proves nothing (it lists one page), so when they have not said, ask it in the one round of questions. A prefix: find the full id in `npx hyperframes media-use voices --limit 100`, and ask when it matches none or several. A clone they name as theirs, or say its owner agreed to: find it there and use it. That list is every clone the HyperFrames account's workspace can use, a teammate's included, and does not say who made one, so never pick from it by count, language or name; never `heygen voice list`, a separate sign-in that can be another account. Nothing named, or not signed in: ask once for their voice id, a clone they make in HeyGen from 30 s to 3 min of their own reading, or their own recorded narration; with none of these, say in one line that you'll use a HeyGen stock voice, name it in the credits as AI-generated, and go on. Nothing is voiced for it before stop 1: at the voice step, `npx hyperframes media-use generate --type voice --voice <the script's language> --script "<first line>" --out .media/pick.mp3 --plan` names HeyGen's first public voice in that language without making anything; set the kit's voice id to its `voice_id` and credit that voice by name. Nothing else starts until this is settled.
- **Then say what's coming** in one short message that is not a question, and go on without waiting: the working title and hook, the length, and roughly how long it takes. No prices.
- **The length is the person's, and it beats the template's runtime.** Offer about 1 minute first: the cold open, the title beat and one chapter, the end card short. 2 to 4 minutes: REMIX.md's short cut. A full episode: the series' own runtime. Their own words ("90 seconds", "5 min"): that length. No length answered and none in the topic: about 1 minute, and offer the longer cut in the reply. Scale everything to it: script words (the template's script stats at that runtime), facts, sections, music cues, review rounds (one for a minute, two for a full episode); never pad or trim to reach the series' runtime instead.
- **Credits name only who the person names.** Roles and names come from the person, never from a voice list, an account or a placeholder; a role nobody named is left out.