@ignix-social/editor 0.1.0

package/vendor/hyperframes/dist/skills/media-use/audio/scripts/lib/gemini-tts.mjs

@@ -0,0 +1,122 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { geminiAuth } from "./gemini-auth.mjs";
+
+export const GEMINI_TTS_MODEL = "gemini-3.8-flash-tts";
+
+export const GEMINI_TTS_MODELS = [
+  GEMINI_TTS_MODEL,
+  "gemini-3.8-flash-lite-tts",
+  "gemini-3.1-flash-tts-preview",
+  "gemini-2.5-pro-preview-tts",
+  "gemini-2.5-flash-preview-tts",
+];
+
+// 3.8 returns WAV; older models return PCM that we wrap without resampling.
+// The shared engine transcribes the saved audio for word timings.
+export async function synthesizeGemini(
+  { text, voiceId = "Kore", model = GEMINI_TTS_MODEL, style, speed = 1, wavAbs },
+  { fetchImpl = fetch, authenticate = geminiAuth } = {},
+) {
+  let secret;
+  try {
+    if (!GEMINI_TTS_MODELS.includes(model)) {
+      throw new Error(`Unsupported Gemini TTS model: ${model}`);
+    }
+    if (speed !== 1) throw new Error("Gemini TTS uses style for pacing; omit speed or use 1");
+    const modern = model.startsWith("gemini-3.8-");
+    if (!modern && /^(voice_|voicekey_)/.test(voiceId)) {
+      throw new Error(
+        "Custom Gemini voices require a 3.8 TTS model; use a prebuilt voice with older models",
+      );
+    }
+    const auth = authenticate();
+    secret = auth.secret;
+    const content = {
+      type: "text",
+      text:
+        !modern && style ? `Read the following text with this delivery: ${style}\n\n${text}` : text,
+    };
+    if (modern && style) content.annotations = [{ type: "speech_metadata", style }];
+    const response = await fetchImpl(
+      "https://generativelanguage.googleapis.com/v1beta/interactions",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...auth.headers },
+        signal: AbortSignal.timeout(120_000),
+        body: JSON.stringify({
+          model,
+          input: [{ type: "user_input", content: [content] }],
+          response_format: modern ? { type: "audio", mime_type: "audio/wav" } : { type: "audio" },
+          generation_config: { speech_config: [{ voice: voiceId }] },
+          store: false,
+        }),
+      },
+    );
+    if (!response.ok) {
+      const detail = await response.text();
+      throw new Error(`Gemini TTS HTTP ${response.status}: ${detail}`);
+    }
+    const payload = await response.json();
+    if (payload.status !== "completed") {
+      throw new Error(`Gemini TTS did not complete (${payload.status ?? "missing status"})`);
+    }
+    const audio = (payload.steps ?? [])
+      .filter((step) => step.type === "model_output")
+      .flatMap((step) => step.content ?? [])
+      .filter((part) => part.type === "audio");
+    if (audio.length !== 1 || !audio[0].data) {
+      throw new Error("Gemini TTS returned no single audio block");
+    }
+    let bytes = Buffer.from(audio[0].data, "base64");
+    if (!modern && /^audio\/l16(?:;|$)/i.test(audio[0].mime_type ?? "")) {
+      bytes = pcmToWav(bytes, audio[0].mime_type);
+    } else if (audio[0].mime_type !== "audio/wav") {
+      throw new Error("Gemini TTS returned an unsupported audio format");
+    }
+    if (
+      bytes.length <= 44 ||
+      bytes.toString("ascii", 0, 4) !== "RIFF" ||
+      bytes.toString("ascii", 8, 12) !== "WAVE"
+    ) {
+      throw new Error("Gemini TTS returned invalid WAV audio");
+    }
+    mkdirSync(dirname(wavAbs), { recursive: true });
+    writeFileSync(wavAbs, bytes);
+    return { ok: true, words: null };
+  } catch (error) {
+    // Error responses must never echo the credential into logs or metadata.
+    const message = String(error?.message ?? error);
+    return {
+      ok: false,
+      words: null,
+      error: secret ? message.split(secret).join("[redacted]") : message,
+    };
+  }
+}
+
+function pcmToWav(pcm, mime) {
+  const rate = Number(/(?:^|;)\s*rate=(\d+)(?:;|$)/i.exec(mime)?.[1]);
+  const channels = /(?:^|;)\s*channels=([^;]+)/i.exec(mime)?.[1];
+  const codec = /(?:^|;)\s*codec=([^;]+)/i.exec(mime)?.[1];
+  if ((channels && channels.trim() !== "1") || (codec && codec.trim() !== "pcm")) {
+    throw new Error("Gemini TTS returned unsupported PCM channels or codec");
+  }
+  if (!Number.isInteger(rate) || rate < 8000 || rate > 96000 || !pcm.length || pcm.length % 2) {
+    throw new Error("Gemini TTS returned invalid PCM audio or sample rate");
+  }
+  const header = Buffer.alloc(44);
+  header.write("RIFF");
+  header.writeUInt32LE(36 + pcm.length, 4);
+  header.write("WAVEfmt ", 8);
+  header.writeUInt32LE(16, 16);
+  header.writeUInt16LE(1, 20);
+  header.writeUInt16LE(1, 22);
+  header.writeUInt32LE(rate, 24);
+  header.writeUInt32LE(rate * 2, 28);
+  header.writeUInt16LE(2, 32);
+  header.writeUInt16LE(16, 34);
+  header.write("data", 36);
+  header.writeUInt32LE(pcm.length, 40);
+  return Buffer.concat([header, pcm]);
+}

package/vendor/hyperframes/dist/skills/media-use/audio/scripts/lib/gemini-tts.test.mjs

@@ -0,0 +1,243 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { synthesizeGemini, GEMINI_TTS_MODEL } from "./gemini-tts.mjs";
+import { pickProvider, resolveVoiceId, synthesizeOne } from "./tts.mjs";
+
+function fixture(t) {
+  const dir = mkdtempSync(join(tmpdir(), "gemini-tts-"));
+  const saved = { ...process.env };
+  process.env.GEMINI_API_KEY = "test-gemini-key";
+  delete process.env.GOOGLE_API_KEY;
+  delete process.env.GOOGLE_APPLICATION_CREDENTIALS;
+  delete process.env.GCS_CREDS;
+  t.after(() => {
+    process.env = saved;
+    rmSync(dir, { recursive: true, force: true });
+  });
+  const wav = Buffer.alloc(48);
+  wav.write("RIFF");
+  wav.writeUInt32LE(40, 4);
+  wav.write("WAVEfmt ", 8);
+  wav.writeUInt32LE(16, 16);
+  wav.writeUInt16LE(1, 20);
+  wav.writeUInt16LE(1, 22);
+  wav.writeUInt32LE(24000, 24);
+  wav.writeUInt32LE(48000, 28);
+  wav.writeUInt16LE(2, 32);
+  wav.writeUInt16LE(16, 34);
+  wav.write("data", 36);
+  wav.writeUInt32LE(4, 40);
+  const audio = { type: "audio", mime_type: "audio/wav", data: wav.toString("base64") };
+  const payload = { status: "completed", steps: [{ type: "model_output", content: [audio] }] };
+  return {
+    wav,
+    audio,
+    payload,
+    args: { text: "Hello there.", voiceId: "Kore", wavAbs: join(dir, "voice", "one.wav") },
+  };
+}
+
+test("Gemini preserves verbatim text, directs style separately, saves WAV and requests transcription", async (t) => {
+  const { wav, payload, args } = fixture(t);
+  t.mock.method(globalThis, "fetch", async (url, options) => {
+    assert.equal(url, "https://generativelanguage.googleapis.com/v1beta/interactions");
+    assert.equal(options.headers["x-goog-api-key"], "test-gemini-key");
+    const body = JSON.parse(options.body);
+    assert.equal(body.model, GEMINI_TTS_MODEL);
+    assert.equal(body.store, false);
+    assert.deepEqual(body.input[0].content, [
+      {
+        type: "text",
+        text: args.text,
+        annotations: [{ type: "speech_metadata", style: "Warm and calm" }],
+      },
+    ]);
+    assert.deepEqual(body.generation_config.speech_config, [{ voice: "Kore" }]);
+    assert.equal(body.response_format.mime_type, "audio/wav");
+    return Response.json(payload);
+  });
+  const result = await synthesizeOne({ ...args, provider: "gemini", style: "Warm and calm" });
+  assert.deepEqual(result, { ok: true, words: null });
+  assert.deepEqual(readFileSync(args.wavAbs), wav);
+});
+
+test("Flash-Lite and GOOGLE_API_KEY work without a Gemini key", async (t) => {
+  const { payload, args } = fixture(t);
+  delete process.env.GEMINI_API_KEY;
+  process.env.GOOGLE_API_KEY = "test-google-key";
+  assert.equal(pickProvider("gemini"), "gemini");
+  assert.equal(await resolveVoiceId({ provider: "gemini" }), "Kore");
+  const result = await synthesizeGemini(
+    { ...args, model: "gemini-3.8-flash-lite-tts" },
+    {
+      fetchImpl: async (_, options) => {
+        assert.equal(options.headers["x-goog-api-key"], "test-google-key");
+        const body = JSON.parse(options.body);
+        assert.equal(body.model, "gemini-3.8-flash-lite-tts");
+        assert.equal(body.input[0].content[0].annotations, undefined);
+        return Response.json(payload);
+      },
+    },
+  );
+  assert.equal(result.ok, true);
+});
+
+test("Gemini remains opt-in even with a key and preserves explicitly chosen voices", async (t) => {
+  fixture(t);
+  assert.notEqual(pickProvider(), "gemini");
+  assert.equal(
+    await resolveVoiceId({ provider: "gemini", userVoice: "voice_custom" }),
+    "voice_custom",
+  );
+  delete process.env.GEMINI_API_KEY;
+  assert.throws(() => pickProvider("gemini"), /GEMINI_API_KEY or GOOGLE_API_KEY/);
+});
+
+test("invalid config fails before spending a generation request", async (t) => {
+  const { args } = fixture(t);
+  const deps = { fetchImpl: () => assert.fail("must not call the API") };
+  for (const change of [{ model: "gemini-2.5-flash" }, { speed: 1.2 }]) {
+    const result = await synthesizeGemini({ ...args, ...change }, deps);
+    assert.equal(result.ok, false);
+    assert.ok(result.error);
+  }
+  delete process.env.GEMINI_API_KEY;
+  assert.match((await synthesizeGemini(args, deps)).error, /needs GEMINI_API_KEY/);
+  assert.equal(existsSync(args.wavAbs), false);
+});
+
+test("HTTP and network failures stay actionable without leaking the key", async (t) => {
+  const { args } = fixture(t);
+  const result = await synthesizeGemini(args, {
+    fetchImpl: async () => new Response("quota exceeded test-gemini-key", { status: 429 }),
+  });
+  assert.equal(result.ok, false);
+  assert.match(result.error, /HTTP 429: quota exceeded/);
+  assert.ok(!result.error.includes("test-gemini-key"));
+  const timeout = await synthesizeGemini(args, {
+    fetchImpl: async () => {
+      throw new Error("timed out");
+    },
+  });
+  assert.match(timeout.error, /timed out/);
+  assert.equal(existsSync(args.wavAbs), false);
+});
+
+test("incomplete, missing, raw PCM and malformed audio cannot become a successful WAV", async (t) => {
+  const { args, payload, audio } = fixture(t);
+  const cases = [
+    { ...payload, status: "incomplete" },
+    { status: "completed", steps: [] },
+    ...[{ ...audio, mime_type: "audio/l16" }, { ...audio, data: "not audio" }, audio].map(
+      (part, i) => ({
+        status: "completed",
+        steps: [{ type: "model_output", content: i === 2 ? [part, part] : [part] }],
+      }),
+    ),
+  ];
+  for (const body of cases) {
+    const result = await synthesizeGemini(args, { fetchImpl: async () => Response.json(body) });
+    assert.equal(result.ok, false);
+    assert.equal(existsSync(args.wavAbs), false);
+  }
+});
+
+for (const model of [
+  "gemini-3.1-flash-tts-preview",
+  "gemini-2.5-pro-preview-tts",
+  "gemini-2.5-flash-preview-tts",
+]) {
+  test(`${model} uses legacy delivery prompts and wraps PCM as mono WAV`, async (t) => {
+    const { args, wav } = fixture(t);
+    const pcm = wav.subarray(44);
+    const result = await synthesizeGemini(
+      { ...args, model, style: "Warm and clear" },
+      {
+        fetchImpl: async (_, options) => {
+          const body = JSON.parse(options.body);
+          assert.deepEqual(body.response_format, { type: "audio" });
+          assert.equal(body.input[0].content[0].annotations, undefined);
+          assert.ok(body.input[0].content[0].text.endsWith(args.text));
+          assert.ok(body.input[0].content[0].text.includes("Warm and clear"));
+          return Response.json({
+            status: "completed",
+            steps: [
+              {
+                type: "model_output",
+                content: [
+                  {
+                    type: "audio",
+                    mime_type: "audio/L16;codec=pcm;rate=24000",
+                    data: pcm.toString("base64"),
+                  },
+                ],
+              },
+            ],
+          });
+        },
+      },
+    );
+    assert.equal(result.ok, true, result.error);
+    assert.deepEqual(readFileSync(args.wavAbs), wav);
+  });
+}
+
+test("service-account bearer and quota project reach synthesis, and token errors are redacted", async (t) => {
+  const { args, payload } = fixture(t);
+  const authenticate = () => ({
+    headers: { Authorization: "Bearer secret-token", "x-goog-user-project": "test-project" },
+    secret: "secret-token",
+  });
+  const ok = await synthesizeGemini(args, {
+    authenticate,
+    fetchImpl: async (_, options) => {
+      assert.equal(options.headers.Authorization, "Bearer secret-token");
+      assert.equal(options.headers["x-goog-user-project"], "test-project");
+      assert.equal(options.headers["x-goog-api-key"], undefined);
+      return Response.json(payload);
+    },
+  });
+  assert.equal(ok.ok, true);
+  const failed = await synthesizeGemini(args, {
+    authenticate,
+    fetchImpl: async () => new Response("denied secret-token", { status: 403 }),
+  });
+  assert.match(failed.error, /HTTP 403/);
+  assert.ok(!failed.error.includes("secret-token"));
+});
+
+test("older models reject unsupported PCM and custom voices", async (t) => {
+  const { args } = fixture(t);
+  for (const mime of [
+    "audio/l16",
+    "audio/l16;rate=0",
+    "audio/l16;rate=24000;channels=2",
+    "audio/l16;rate=24000;codec=other",
+  ]) {
+    const result = await synthesizeGemini(
+      { ...args, model: "gemini-3.1-flash-tts-preview" },
+      {
+        fetchImpl: async () =>
+          Response.json({
+            status: "completed",
+            steps: [
+              {
+                type: "model_output",
+                content: [{ type: "audio", mime_type: mime, data: "AAAAAA==" }],
+              },
+            ],
+          }),
+      },
+    );
+    assert.equal(result.ok, false);
+    assert.equal(existsSync(args.wavAbs), false);
+  }
+  const result = await synthesizeGemini(
+    { ...args, model: "gemini-2.5-pro-preview-tts", voiceId: "voice_custom" },
+    { fetchImpl: () => assert.fail("must not generate") },
+  );
+  assert.match(result.error, /Custom Gemini voices require/);
+});

package/vendor/hyperframes/dist/skills/media-use/audio/scripts/lib/heygen.mjs

@@ -0,0 +1,197 @@
+import { fetchMedia } from "../../../scripts/lib/media-fetch.mjs";
+// heygen.mjs — vendored HeyGen REST helpers (auth + transport) for the audio
+// pipeline. The credential resolver matches the hyperframes CLI auth: first
+// usable source wins — a host-injected OAuth $HEYGEN_ACCESS_TOKEN (Bearer) →
+// $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY → a nearby .env → ~/.heygen/
+// credentials (oauth → Bearer, else api_key → X-Api-Key; $HEYGEN_CONFIG_DIR
+// overrides the dir). Vendored so the skill ships standalone. Pure node.
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+export const HEYGEN_BASE = "https://api.heygen.com/v3";
+export const HEYGEN_CLI_SOURCE_HEADERS = { "X-HeyGen-Source": "cli" };
+// Tool-attribution sent on EVERY media-use HeyGen call regardless of auth type, so
+// the backend can isolate media-use consumption from other free TTS / avatar video.
+// Unconditional — a paying user's media-use call is still media-use — unlike the
+// OAuth-only cli-source header above, which also gates the free allowance.
+export const HEYGEN_CLIENT_SOURCE_HEADERS = { "X-HeyGen-Client-Source": "media-use" };
+
+// A missing `.env`, or a `.env` folder (some home dirs have one), is no env file: null. Read without checking first,
+// so the file cannot change between a check and the read.
+function envFileText(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (error) {
+    if (["ENOENT", "ENOTDIR", "EISDIR"].includes(error.code)) return null;
+    throw error;
+  }
+}
+
+// Walk up ≤5 dirs from startDir; load the first .env (shell env always wins).
+export function loadEnvFromDir(startDir) {
+  let dir = resolve(startDir);
+  for (let i = 0; i < 5; i++) {
+    const text = envFileText(join(dir, ".env"));
+    if (text != null) {
+      for (const raw of text.split("\n")) {
+        let line = raw.trim();
+        if (!line || line.startsWith("#")) continue;
+        if (line.startsWith("export ")) line = line.slice(7).trim();
+        const eq = line.indexOf("=");
+        if (eq < 1) continue;
+        const key = line.slice(0, eq).trim();
+        let val = line.slice(eq + 1).trim();
+        if (val.startsWith('"') || val.startsWith("'")) {
+          const q = val[0];
+          const end = val.indexOf(q, 1);
+          val = end > 0 ? val.slice(1, end) : val.slice(1);
+        }
+        if (!(key in process.env)) process.env[key] = val;
+      }
+      return;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+}
+
+// → { headers } | { expired: true } | null. Never throws.
+export function heygenCredential() {
+  const cred = resolveCredential();
+  return cred?.unreadable ? null : cred;
+}
+
+// heygenCredential's answer, or { unreadable: { file, code } } when the credentials path exists but cannot be read
+// (a folder, a locked ~/.heygen), so heygenAuthHeaders can say to fix that path: logging in again would fail there too.
+// Read without checking first, so the file cannot change between a check and the read.
+function resolveCredential() {
+  const accessToken = process.env.HEYGEN_ACCESS_TOKEN;
+  if (accessToken) return { headers: { Authorization: `Bearer ${accessToken}` } };
+  const envKey = process.env.HEYGEN_API_KEY || process.env.HYPERFRAMES_API_KEY;
+  if (envKey) return { headers: { "X-Api-Key": envKey } };
+
+  const file = join(process.env.HEYGEN_CONFIG_DIR || join(homedir(), ".heygen"), "credentials");
+  let raw;
+  try {
+    raw = readFileSync(file, "utf8").trim();
+  } catch (error) {
+    return error.code === "ENOENT" ? null : { unreadable: { file, code: error.code } };
+  }
+  if (!raw) return null;
+  if (!raw.startsWith("{")) return { headers: { "X-Api-Key": raw } };
+
+  // A malformed credentials file (partial write / wrong shape) must degrade to
+  // "no credential", not crash the engine at startup.
+  let cred;
+  try {
+    cred = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const oauth = cred.oauth;
+  if (oauth?.access_token) {
+    const expired = oauth.expires_at && new Date(oauth.expires_at).getTime() - 60_000 < Date.now();
+    if (!expired) return { headers: { Authorization: `Bearer ${oauth.access_token}` } };
+    if (!cred.api_key) return { expired: true };
+  }
+  if (cred.api_key) return { headers: { "X-Api-Key": cred.api_key } };
+  return null;
+}
+
+// → "oauth" | "api_key" | null. Same oauth-vs-api-key check heygenAuthHeaders()
+// makes internally, exposed on its own so callers that only need to *tag* the
+// auth path (telemetry) don't have to parse headers back apart. Never throws:
+// no credential (or an expired one) is just `null`, same as a fresh resolve
+// with nothing to tag.
+export function heygenAuthMethod() {
+  const cred = heygenCredential();
+  if (!cred?.headers) return null;
+  return "Authorization" in cred.headers ? "oauth" : "api_key";
+}
+
+// → auth headers object, or throw with a fix hint.
+export function heygenAuthHeaders() {
+  const cred = resolveCredential();
+  if (cred?.headers) {
+    // Only tag OAuth (Bearer) traffic as cli-source — the backend uses it to
+    // grant the free allowance for OAuth requests and ignores it for API-key
+    // (X-Api-Key) traffic, where it's dead metadata.
+    const isOauth = "Authorization" in cred.headers;
+    return isOauth
+      ? { ...cred.headers, ...HEYGEN_CLI_SOURCE_HEADERS, ...HEYGEN_CLIENT_SOURCE_HEADERS }
+      : { ...cred.headers, ...HEYGEN_CLIENT_SOURCE_HEADERS };
+  }
+  if (cred?.unreadable)
+    throw new Error(
+      `HeyGen credentials at ${cred.unreadable.file} can't be read (${cred.unreadable.code}) — fix or remove that path, then run \`npx hyperframes auth login\``,
+    );
+  if (cred?.expired)
+    throw new Error(
+      "HeyGen OAuth token expired — run `npx hyperframes auth refresh` (or `npx hyperframes auth login`)",
+    );
+  throw new Error(
+    "no HeyGen credentials — set $HEYGEN_API_KEY, or run `npx hyperframes auth login` (writes ~/.heygen/credentials)",
+  );
+}
+
+// Authed JSON request against the v3 API; throws on a non-OK status.
+export async function heygenJSON(path, { method = "GET", headers = {}, body } = {}) {
+  const opts = { method, headers: { ...HEYGEN_CLIENT_SOURCE_HEADERS, ...headers } };
+  if (body !== undefined) {
+    opts.headers["Content-Type"] = "application/json";
+    opts.body = JSON.stringify(body);
+  }
+  const res = await fetch(`${HEYGEN_BASE}${path}`, opts);
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    const message = `HeyGen ${method} ${path} → HTTP ${res.status}${detail ? `\n${detail.slice(0, 300)}` : ""}`;
+    throw Object.assign(new Error(message), { status: res.status, body: detail });
+  }
+  // A DELETE may answer 204 with no body.
+  const text = await res.text();
+  return text ? JSON.parse(text) : {};
+}
+
+// HeyGen's own words for a failed call: its {"error":{"message"}}, else the raw body, else the error's message.
+export function heygenMessage(e) {
+  if (!e?.body) return e?.message ? String(e.message) : String(e);
+  try {
+    return JSON.parse(e.body).error?.message ?? e.body;
+  } catch {
+    return e.body;
+  }
+}
+
+// Download a (presigned) URL to destPath; returns byte length.
+export async function downloadTo(url, destPath) {
+  const res = await fetchMedia(url);
+  if (!res.ok) throw new Error(`download HTTP ${res.status}: ${String(url).slice(0, 80)}`);
+  const bytes = Buffer.from(await res.arrayBuffer());
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, bytes);
+  return bytes.length;
+}
+
+// Retrieval search over HeyGen's audio catalog (NOT generation). type =
+// "music" | "sound_effects". Returns the ranked results array (best first); each
+// item has a presigned `audio_url` (+ `duration`, `description`, `name`, `score`).
+// `query` is required (≥1 char, empty → HTTP 400) and `limit` is capped at 50.
+// `minScore`: omit to use the server default (0.7). That default is TOO HIGH for
+// sound_effects — good SFX hits score ~0.5–0.67, so callers wanting SFX should
+// pass a lower floor (~0.4); music scores high and is fine at the default.
+export async function searchSounds(query, type, headers, { limit = 5, minScore } = {}) {
+  const params = new URLSearchParams({ query, type, limit: String(limit) });
+  if (minScore != null) params.set("min_score", String(minScore));
+  const payload = await heygenJSON(`/audio/sounds?${params.toString()}`, { headers });
+  // `data` comes back as a ranked array (best first). Older responses keyed it by
+  // numeric index ("0","1",…); normalize both shapes to an array (empty → []).
+  const data = payload?.data ?? payload;
+  if (Array.isArray(data)) return data;
+  if (data && typeof data === "object") return Object.values(data);
+  throw new Error(
+    `unexpected /audio/sounds shape — top keys: ${Object.keys(payload ?? {}).join(", ")}`,
+  );
+}