dsh-hyperframes 0.3.1 → 0.4.0

package/skills/media-use/audio/references/tts.md

@@ -36,6 +36,10 @@ Use another voice only for a documented reason, and write the reason down.
 
 ## Available routes
 
+Gemini is an explicit alternative to the automatic provider order below. A
+request to use Gemini already chooses the provider; do not redirect that user
+to HeyGen sign-in. Read the Gemini section for its credential requirement.
+
 | Order | Provider          | Env trigger                                 | Voice IDs                                   | Word timestamps                           | Audio format         |
 | ----- | ----------------- | ------------------------------------------- | ------------------------------------------- | ----------------------------------------- | -------------------- |
 | 1     | HeyGen (Starfish) | `$HEYGEN_API_KEY` / `~/.heygen/credentials` | UUIDs from `GET /v3/voices?engine=starfish` | **Yes** (`word_timestamps[]` in response) | mp3 → wav via ffmpeg |
@@ -83,12 +87,86 @@ node skills/media-use/audio/scripts/heygen-tts.mjs --list   # public starfish vo
 
 ## When to use which provider
 
-| Goal                                                      | Use                                                 |
-| --------------------------------------------------------- | --------------------------------------------------- |
-| Best voice quality + word timestamps in one call          | **HeyGen**                                          |
-| Drop-in cloud TTS, big voice catalog                      | **ElevenLabs**                                      |
-| Offline, no API key, fast iteration                       | **Kokoro**                                          |
-| Non-English multilingual with deterministic phonemization | **Kokoro** (`ef_dora`, `jf_alpha`, `zf_xiaobei`, …) |
+| Goal                                                      | Use                                                       |
+| --------------------------------------------------------- | --------------------------------------------------------- |
+| Best voice quality + word timestamps in one call          | **HeyGen**                                                |
+| Drop-in cloud TTS, big voice catalog                      | **ElevenLabs**                                            |
+| Offline, no API key, fast iteration                       | **Kokoro**                                                |
+| Directed delivery with Gemini prebuilt or custom voices   | **Gemini** (explicit selection; transcription for timing) |
+| Non-English multilingual with deterministic phonemization | **Kokoro** (`ef_dora`, `jf_alpha`, `zf_xiaobei`, …)       |
+
+## Gemini narration
+
+Use the shared audio engine, not `hyperframes tts`. Authenticate with either:
+
+- `GEMINI_API_KEY` or `GOOGLE_API_KEY` (first set key wins).
+- A service-account JSON file at `GOOGLE_APPLICATION_CREDENTIALS`, or injected
+  JSON in `GCS_CREDS`. Install `google-auth requests` in the Python 3 environment
+  used by the helper. A configured file takes precedence over injected JSON.
+
+API keys take precedence over service accounts: unset both key variables to use
+OAuth. Never put credentials in a request file or composition. The helper
+obtains a fresh OAuth token for each generation with the
+`generative-language.retriever` scope. The quota project resolves from
+`GOOGLE_CLOUD_PROJECT`, then `GCLOUD_PROJECT_ID`, then the service-account JSON.
+User ADC files and metadata-server authentication are not supported.
+
+Both routes call the Gemini Developer Interactions API, not Cloud TTS or Vertex
+AI. Those APIs have separate model catalogs and access requirements.
+
+Save this as `audio_request.json` in the project:
+
+```json
+{
+  "provider": "gemini",
+  "tts_model": "gemini-3.8-flash-tts",
+  "voice": "Kore",
+  "lang": "en",
+  "style": "Warm, clear, conversational. Leave a short pause between sentences.",
+  "lines": [
+    { "id": "intro", "text": "Every word has a moment. Let the picture follow the voice." }
+  ],
+  "bgm": { "mode": "none" }
+}
+```
+
+```bash
+node <SKILL_DIR>/audio/scripts/audio.mjs \
+  --request ./audio_request.json --hyperframes . --out ./audio_meta.json --only tts
+```
+
+The engine saves `assets/voice/intro.wav`, measures its duration, and transcribes
+it into `voices[].words` in `audio_meta.json`. Check that every requested line
+has audio and nonempty word timings before building a captioned video. Review
+the timings against the actual audio; transcription is estimated alignment,
+not native TTS timestamps. Do not distribute words evenly across a clip.
+
+- **Models:** `gemini-3.8-flash-tts` (default), `gemini-3.8-flash-lite-tts`,
+  `gemini-3.1-flash-tts-preview`, `gemini-2.5-pro-preview-tts`, and
+  `gemini-2.5-flash-preview-tts`. Use these exact Developer API IDs; Cloud TTS
+  aliases such as `gemini-2.5-flash-tts` are not accepted.
+- **Voice:** `Kore` by default; pass another prebuilt voice or an existing custom
+  voice ID for 3.8. Older models require prebuilt voices. Creating or replicating
+  voices is outside this helper.
+- **Delivery:** Put directions in `style`, not in spoken `text`. Each line can
+  override `style`. 3.8 uses structured annotations; older models receive a
+  delivery prompt before the transcript. Check that directions were not spoken.
+  Use style for pacing; numeric `speed` must be omitted or 1.
+- **Audio:** 3.8 returns a complete WAV. Older models return mono 16-bit PCM,
+  which the helper wraps as WAV at the returned sample rate without resampling.
+  No generation calls run during playback or rendering.
+- **Timing:** This adapter requests no native word timestamps. It uses the
+  existing transcription pass. `lang` selects transcription language; Gemini
+  infers speech language from the text.
+- **Workflow adapters:** Product-launch, faceless-explainer, and PR-video audio
+  scripts accept `--provider gemini --voice Kore --tts-model gemini-3.8-flash-tts
+--style "Warm and clear"`.
+
+An API error is reported as a failed line; an explicitly chosen Gemini voice
+never silently falls back to another provider. Check the engine's anomalies
+and output metadata, not only its exit code.
+
+API contract: [Google's speech generation guide](https://ai.google.dev/gemini-api/docs/speech-generation).
 
 ## ffmpeg requirement
 

package/skills/media-use/audio/scripts/audio.mjs

@@ -15,7 +15,7 @@
 //
 // ── audio_request.json (input) ────────────────────────────────────────────────
 //   {
-//     "provider": "auto",          // auto|heygen|elevenlabs|kokoro (override: --provider)
+//     "provider": "auto",          // auto|heygen|elevenlabs|kokoro|gemini (override: --provider)
 //     "lang": "en", "speed": 1.0,
 //     "lines": [                   // one TTS unit each; id joins back to the caller's model
 //       { "id": "01", "text": "...", "sfx": ["whoosh", "ui click"] }
@@ -39,7 +39,7 @@
 // the generate path it is spawned detached (bgm_pending:true) — run wait-bgm.mjs
 // before assembling.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { heygenAuthHeaders, heygenCredential, loadEnvFromDir } from "./lib/heygen.mjs";
@@ -54,6 +54,7 @@ import {
 import { generateBgmDetached, inferBgmPrompt, retrieveBgm } from "./lib/bgm.mjs";
 import { resolveSfx } from "./lib/sfx.mjs";
 import { mapWithConcurrency } from "./lib/concurrency.mjs";
+import { openAudioMeta } from "./lib/audio-meta.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const argv = process.argv.slice(2);
@@ -112,10 +113,10 @@ const speed = Number(speedOverride ?? request.speed ?? 1.0) || 1.0;
 // ── env + HeyGen availability (the single switch) ─────────────────────────────
 loadEnvFromDir(hyperframesDir);
 const heygenOK = heygenCredential() !== null;
-const headers = heygenOK ? heygenAuthHeaders() : null;
 
 // ── merge base: preserve sections not selected by --only ──────────────────────
-const prev = existsSync(outPath) ? JSON.parse(readFileSync(outPath, "utf8")) : {};
+const audioMeta = openAudioMeta(outPath);
+const prev = audioMeta.value;
 const anomalies = [];
 
 // ── TTS ───────────────────────────────────────────────────────────────────────
@@ -151,6 +152,8 @@ if (only.has("tts") && lines.length) {
       voiceId,
       lang,
       speed,
+      model: flag("tts-model", request.tts_model),
+      style: flag("style", line.style ?? request.style),
       wavAbs: abs,
       hyperframesDir,
     });
@@ -208,7 +211,12 @@ if (only.has("bgm")) {
     console.error(`· bgm: disabled`);
   } else if (mode === "retrieve") {
     try {
-      bgm = await retrieveBgm({ query: request.bgm?.query, headers, hyperframesDir, hasVoice });
+      bgm = await retrieveBgm({
+        query: request.bgm?.query,
+        headers: heygenAuthHeaders(),
+        hyperframesDir,
+        hasVoice,
+      });
       if (bgm) {
         bgmFields.bgm_provider = "heygen";
         bgmFields.bgm_mode = "retrieve";
@@ -260,6 +268,7 @@ if (only.has("sfx")) {
       .map((name) => ({ id: String(l.id), name: String(name).trim() }))
       .filter((c) => c.name),
   );
+  const headers = heygenOK && cues.length ? heygenAuthHeaders() : null;
   const res = await resolveSfx({ cues, heygenOK, headers, hyperframesDir, sfxLibDir });
   sfx = res.sfx;
   anomalies.push(...res.anomalies);
@@ -279,7 +288,7 @@ const meta = {
   total_duration_s: totalDuration,
 };
 mkdirSync(dirname(outPath), { recursive: true });
-writeFileSync(outPath, JSON.stringify(meta, null, 2));
+audioMeta.write(meta);
 
 console.log(`✓ audio engine → ${outPath}`);
 console.log(`  heygen: ${heygenOK ? "yes" : "no"}  ·  ran: ${[...only].join(",")}`);

package/skills/media-use/audio/scripts/gemini-pipeline.test.mjs

@@ -0,0 +1,113 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { mkdtempSync, writeFileSync, readFileSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+
+// Exercise the actual engine and provider together; only the paid API and
+// external audio tools are fixtures. This is not a live synthesis/render test.
+for (const expired of [false, true]) {
+  for (const only of ["tts", "tts,bgm,sfx"]) {
+    test(`Gemini engine returns caption metadata with ${expired ? "expired" : "absent"} HeyGen credentials (${only})`, (t) => {
+      const dir = mkdtempSync(join(tmpdir(), "hf-gemini-pipeline-"));
+      t.after(() => rmSync(dir, { recursive: true, force: true }));
+      const config = join(dir, "heygen");
+      mkdirSync(config);
+      if (expired)
+        writeFileSync(
+          join(config, "credentials"),
+          JSON.stringify({
+            oauth: { access_token: "expired-fixture", expires_at: "2000-01-01T00:00:00Z" },
+          }),
+        );
+      const bin = join(dir, "bin");
+      mkdirSync(bin);
+      const preload = join(dir, "fetch.mjs");
+      writeFileSync(
+        preload,
+        `
+import assert from 'node:assert/strict';
+globalThis.fetch = async (url, options) => {
+  assert.equal(url, 'https://generativelanguage.googleapis.com/v1beta/interactions');
+  const body = JSON.parse(options.body);
+  assert.equal(body.model, 'gemini-3.8-flash-lite-tts');
+  assert.equal(body.input[0].content[0].annotations[0].style, 'Line direction');
+  const bytes = Buffer.alloc(48);
+  bytes.write('RIFF'); bytes.write('WAVE', 8);
+  return Response.json({status:'completed', steps:[{type:'model_output', content:[
+    {type:'audio', mime_type:'audio/wav', data:bytes.toString('base64')}
+  ]}]});
+};
+`,
+      );
+      writeFileSync(
+        join(bin, "npx"),
+        `#!${process.execPath}
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const args = process.argv.slice(2);
+assert.deepEqual(args.slice(0, 3), ['hyperframes', 'transcribe', 'assets/voice/intro.wav']);
+assert.ok(fs.existsSync(args[2]));
+assert.equal(args[args.indexOf('--model')+1], 'small.en');
+fs.writeFileSync(path.join(args[args.indexOf('--dir')+1], 'transcript.json'), JSON.stringify([
+ {text:'Hello',start:0.1,end:0.4}, {text:'there.',start:0.5,end:0.9}
+]));
+`,
+        { mode: 0o755 },
+      );
+      writeFileSync(join(bin, "ffprobe"), "#!/bin/sh\necho 1.25\n", { mode: 0o755 });
+      writeFileSync(join(dir, ".env"), "");
+      writeFileSync(
+        join(dir, "audio_request.json"),
+        JSON.stringify({
+          provider: "gemini",
+          tts_model: "gemini-3.8-flash-lite-tts",
+          style: "Global direction",
+          lines: [{ id: "intro", text: "Hello there.", style: "Line direction" }],
+          bgm: { mode: "none" },
+        }),
+      );
+      const result = spawnSync(
+        process.execPath,
+        [
+          "--import",
+          preload,
+          new URL("./audio.mjs", import.meta.url).pathname,
+          "--hyperframes",
+          dir,
+          "--only",
+          only,
+        ],
+        {
+          encoding: "utf8",
+          env: {
+            ...process.env,
+            HEYGEN_CONFIG_DIR: config,
+            HEYGEN_API_KEY: "",
+            HYPERFRAMES_API_KEY: "",
+            GEMINI_API_KEY: "fixture-key",
+            PATH: `${bin}:${process.env.PATH}`,
+          },
+        },
+      );
+      assert.equal(result.status, 0, result.stderr);
+      const meta = JSON.parse(readFileSync(join(dir, "audio_meta.json"), "utf8"));
+      assert.equal(meta.tts_provider, "gemini");
+      assert.equal(meta.voice_id, "Kore");
+      assert.deepEqual(meta.voices, [
+        {
+          id: "intro",
+          path: "assets/voice/intro.wav",
+          duration_s: 1.25,
+          words: [
+            { id: "w0", text: "Hello", start: 0.1, end: 0.4 },
+            { id: "w1", text: "there.", start: 0.5, end: 0.9 },
+          ],
+        },
+      ]);
+      assert.equal(meta.total_duration_s, 1.25);
+    });
+  }
+}

package/skills/media-use/audio/scripts/lib/audio-meta.mjs

@@ -0,0 +1,39 @@
+import { closeSync, ftruncateSync, openSync, readFileSync, writeSync } from "node:fs";
+
+// Keep the merge base and output on the same file even if its pathname changes
+// while audio generation runs. The CLI owns this handle until write or exit.
+export function openAudioMeta(path) {
+  let fd;
+  try {
+    fd = openSync(path, "r+");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  let value = {};
+  if (fd !== undefined) {
+    try {
+      value = JSON.parse(readFileSync(fd, "utf8"));
+    } catch (error) {
+      closeSync(fd);
+      throw error;
+    }
+  }
+  return {
+    value,
+    write(meta) {
+      const bytes = Buffer.from(JSON.stringify(meta, null, 2));
+      // Defer new-file creation until generation succeeds. Never overwrite a
+      // file (or follow a link) that appeared since the missing merge base.
+      if (fd === undefined) fd = openSync(path, "wx");
+      try {
+        let offset = 0;
+        while (offset < bytes.length) {
+          offset += writeSync(fd, bytes, offset, bytes.length - offset, offset);
+        }
+        ftruncateSync(fd, bytes.length);
+      } finally {
+        closeSync(fd);
+      }
+    },
+  };
+}

package/skills/media-use/audio/scripts/lib/audio-meta.test.mjs

@@ -0,0 +1,136 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { openAudioMeta } from "./audio-meta.mjs";
+
+function fixture(t) {
+  const dir = mkdtempSync(join(tmpdir(), "audio-meta-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+test("updates the read file from byte zero, truncates, and retains its mode", (t) => {
+  const path = join(fixture(t), "meta.json");
+  writeFileSync(path, JSON.stringify({ voices: ["long existing voice metadata"] }), {
+    mode: 0o600,
+  });
+  const originalMode = statSync(path).mode;
+  const handle = openAudioMeta(path);
+  assert.deepEqual(handle.value, { voices: ["long existing voice metadata"] });
+  handle.write({ voices: ["声"] });
+  assert.equal(readFileSync(path, "utf8"), JSON.stringify({ voices: ["声"] }, null, 2));
+  assert.equal(statSync(path).mode, originalMode);
+});
+
+test("pathname replacement cannot redirect the existing-file write", (t) => {
+  const dir = fixture(t);
+  const path = join(dir, "meta.json");
+  const moved = join(dir, "original.json");
+  writeFileSync(path, "{}");
+  const handle = openAudioMeta(path);
+  renameSync(path, moved);
+  writeFileSync(path, "replacement must survive");
+  handle.write({ voices: [] });
+  assert.equal(readFileSync(path, "utf8"), "replacement must survive");
+  assert.deepEqual(JSON.parse(readFileSync(moved, "utf8")), { voices: [] });
+});
+
+test("existing symlink outputs retain their original target even after retargeting", (t) => {
+  const dir = fixture(t);
+  const path = join(dir, "meta.json");
+  const target = join(dir, "target.json");
+  const victim = join(dir, "victim.json");
+  writeFileSync(target, "{}");
+  writeFileSync(victim, "untouched");
+  symlinkSync(target, path);
+  const handle = openAudioMeta(path);
+  rmSync(path);
+  symlinkSync(victim, path);
+  handle.write({ bgm: null });
+  assert.equal(readFileSync(victim, "utf8"), "untouched");
+  assert.deepEqual(JSON.parse(readFileSync(target, "utf8")), { bgm: null });
+});
+
+test("missing output is created only when saved", (t) => {
+  const path = join(fixture(t), "meta.json");
+  const handle = openAudioMeta(path);
+  assert.deepEqual(handle.value, {});
+  assert.throws(() => statSync(path), { code: "ENOENT" });
+  handle.write({ sfx: [] });
+  assert.deepEqual(JSON.parse(readFileSync(path, "utf8")), { sfx: [] });
+});
+
+for (const replacement of ["file", "symlink"]) {
+  test(`new output does not overwrite a racing ${replacement}`, (t) => {
+    const dir = fixture(t);
+    const path = join(dir, "meta.json");
+    const victim = join(dir, "victim.json");
+    const handle = openAudioMeta(path);
+    writeFileSync(victim, "untouched");
+    if (replacement === "symlink") symlinkSync(victim, path);
+    else writeFileSync(path, "untouched");
+    assert.throws(() => handle.write({}), { code: "EEXIST" });
+    assert.equal(readFileSync(path, "utf8"), "untouched");
+    assert.equal(readFileSync(victim, "utf8"), "untouched");
+  });
+}
+
+test("malformed merge base remains an error without changing bytes", (t) => {
+  const path = join(fixture(t), "meta.json");
+  writeFileSync(path, "bad json");
+  assert.throws(() => openAudioMeta(path), SyntaxError);
+  assert.equal(readFileSync(path, "utf8"), "bad json");
+});
+
+test("CLI partial run retains unselected voices, BGM and SFX", (t) => {
+  const dir = fixture(t);
+  const path = join(dir, "meta.json");
+  const request = join(dir, "request.json");
+  const previous = {
+    voices: [{ id: "a", duration_s: 2 }],
+    bgm: { path: "bgm.wav" },
+    sfx: [{ name: "click" }],
+    tts_provider: "kokoro",
+    voice_id: "voice-a",
+  };
+  writeFileSync(path, JSON.stringify(previous));
+  writeFileSync(request, "{}");
+  const result = spawnSync(
+    process.execPath,
+    [
+      fileURLToPath(new URL("../audio.mjs", import.meta.url)),
+      "--request",
+      request,
+      "--hyperframes",
+      dir,
+      "--out",
+      path,
+      "--only",
+      "none",
+    ],
+    {
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        HEYGEN_CONFIG_DIR: dir,
+        HEYGEN_API_KEY: "",
+        HYPERFRAMES_API_KEY: "",
+      },
+    },
+  );
+  assert.equal(result.status, 0, result.stderr);
+  const actual = JSON.parse(readFileSync(path, "utf8"));
+  for (const key of Object.keys(previous)) assert.deepEqual(actual[key], previous[key]);
+});

package/skills/media-use/audio/scripts/lib/bgm-volume.mjs

@@ -0,0 +1,4 @@
+// Music sits under narration; a silent film brings music forward.
+export const BGM_BED_VOLUME = 0.12;
+export const BGM_SILENT_VOLUME = 0.9;
+export const bgmDefaultVolume = (hasVoice) => (hasVoice ? BGM_BED_VOLUME : BGM_SILENT_VOLUME);

package/skills/media-use/audio/scripts/lib/bgm.mjs

@@ -20,12 +20,8 @@ import { pythonInvocation } from "./python.mjs";
 const r3 = (x) => Number(x.toFixed(3));
 const lyriaKey = () => process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY || "";
 
-// Default BGM level. Under narration music is a bed that must stay under the
-// voice — 0.12 linear ≈ -18 dB. A silent film (no voice) has no voice to duck
-// beneath, so BGM sits forward at 0.9. Callers may override per composition.
-export const BGM_BED_VOLUME = 0.12;
-export const BGM_SILENT_VOLUME = 0.9;
-export const bgmDefaultVolume = (hasVoice) => (hasVoice ? BGM_BED_VOLUME : BGM_SILENT_VOLUME);
+import { bgmDefaultVolume } from "./bgm-volume.mjs";
+export { BGM_BED_VOLUME, BGM_SILENT_VOLUME, bgmDefaultVolume } from "./bgm-volume.mjs";
 
 const BGM_PY_DEPS = ["transformers", "torch", "soundfile", "numpy"];
 const BGM_PY_PROBE =

package/skills/media-use/audio/scripts/lib/gemini-auth.mjs

@@ -0,0 +1,43 @@
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { pythonInvocation } from "./python.mjs";
+
+export function geminiConfigured() {
+  return Boolean(
+    process.env.GEMINI_API_KEY ||
+    process.env.GOOGLE_API_KEY ||
+    process.env.GOOGLE_APPLICATION_CREDENTIALS ||
+    process.env.GCS_CREDS,
+  );
+}
+
+export function geminiAuth({ run = spawnSync } = {}) {
+  const key = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
+  if (key) return { headers: { "x-goog-api-key": key }, secret: key };
+  if (!geminiConfigured()) {
+    throw new Error(
+      "Gemini TTS needs GEMINI_API_KEY or GOOGLE_API_KEY, or service-account credentials (GOOGLE_APPLICATION_CREDENTIALS or GCS_CREDS)",
+    );
+  }
+  const { cmd, args } = pythonInvocation([
+    fileURLToPath(new URL("./gemini-auth.py", import.meta.url)),
+  ]);
+  const result = run(cmd, args, { encoding: "utf8", timeout: 60_000, maxBuffer: 1024 * 1024 });
+  let data;
+  try {
+    data = JSON.parse(result.stdout);
+  } catch {
+    throw new Error(
+      "Gemini service-account authentication failed; check Python and install google-auth requests",
+    );
+  }
+  if (result.status !== 0 || !data.token) {
+    // Do not echo subprocess output: it could contain credentials.
+    throw new Error(
+      "Gemini service-account authentication failed; check service-account JSON, permissions, and Python packages google-auth requests",
+    );
+  }
+  const headers = { Authorization: `Bearer ${data.token}` };
+  if (data.project) headers["x-goog-user-project"] = data.project;
+  return { headers, secret: data.token };
+}

package/skills/media-use/audio/scripts/lib/gemini-auth.py

@@ -0,0 +1,52 @@
+"""Obtain Gemini OAuth headers without persisting credentials or tokens."""
+
+import json
+import os
+import sys
+
+# Keep the credential subprocess protocol UTF-8 on every platform.
+for _stream in (sys.stdout, sys.stderr):
+    if hasattr(_stream, "reconfigure"):
+        _stream.reconfigure(encoding="utf-8", errors=_stream.errors)
+
+
+def authenticate():
+    try:
+        from google.auth.transport.requests import Request
+        from google.oauth2 import service_account
+    except ImportError:
+        return {"error": "Service-account auth needs Python packages: pip install google-auth requests"}
+
+    try:
+        path = os.environ.get("GOOGLE_APPLICATION_CREDENTIALS")
+        if path:
+            with open(path, encoding="utf-8") as source:
+                info = json.load(source)
+        else:
+            info = json.loads(os.environ["GCS_CREDS"])
+        if info.get("type") != "service_account":
+            return {"error": "Gemini requires service-account JSON, not user ADC credentials"}
+        # Only exchange credentials with Google's OAuth server.
+        info["token_uri"] = "https://oauth2.googleapis.com/token"
+        credentials = service_account.Credentials.from_service_account_info(
+            info,
+            scopes=[
+                "https://www.googleapis.com/auth/generative-language.retriever",
+            ],
+        )
+        credentials.refresh(Request())
+        project = (
+            os.environ.get("GOOGLE_CLOUD_PROJECT")
+            or os.environ.get("GCLOUD_PROJECT_ID")
+            or info.get("project_id")
+        )
+        return {"token": credentials.token, "project": project}
+    except Exception:
+        # Library exceptions can contain credential data. Never forward them.
+        return {"error": "Gemini service-account authentication failed; check credentials, permissions, and network access"}
+
+
+if __name__ == "__main__":
+    result = authenticate()
+    print(json.dumps(result))
+    sys.exit(1 if "error" in result else 0)

package/skills/media-use/audio/scripts/lib/gemini-auth.test.mjs

@@ -0,0 +1,86 @@
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { pythonInvocation } from "./python.mjs";
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { geminiAuth, geminiConfigured } from "./gemini-auth.mjs";
+import { pickProvider } from "./tts.mjs";
+
+function env(t) {
+  const saved = { ...process.env };
+  for (const key of [
+    "GEMINI_API_KEY",
+    "GOOGLE_API_KEY",
+    "GOOGLE_APPLICATION_CREDENTIALS",
+    "GCS_CREDS",
+  ])
+    delete process.env[key];
+  t.after(() => {
+    process.env = saved;
+  });
+}
+
+test("API keys take precedence over service accounts without invoking Python", (t) => {
+  env(t);
+  process.env.GEMINI_API_KEY = "gemini-key";
+  process.env.GOOGLE_API_KEY = "google-key";
+  process.env.GCS_CREDS = "private-json";
+  const run = () => assert.fail("must not spawn Python");
+  assert.deepEqual(geminiAuth({ run }).headers, { "x-goog-api-key": "gemini-key" });
+  delete process.env.GEMINI_API_KEY;
+  assert.deepEqual(geminiAuth({ run }).headers, { "x-goog-api-key": "google-key" });
+});
+
+test("service-account configuration selects Gemini and returns scoped helper headers", (t) => {
+  env(t);
+  assert.equal(geminiConfigured(), false);
+  assert.throws(() => geminiAuth(), /needs GEMINI_API_KEY/);
+  for (const key of ["GOOGLE_APPLICATION_CREDENTIALS", "GCS_CREDS"]) {
+    process.env[key] = "credential-source";
+    assert.equal(pickProvider("gemini"), "gemini");
+    const auth = geminiAuth({
+      run: (_, args, options) => {
+        assert.ok(args.at(-1).endsWith("gemini-auth.py"));
+        assert.ok(!args.includes("credential-source"));
+        assert.equal(options.timeout, 60000);
+        return {
+          status: 0,
+          stdout: JSON.stringify({ token: "access-token", project: "quota-project" }),
+        };
+      },
+    });
+    assert.deepEqual(auth.headers, {
+      Authorization: "Bearer access-token",
+      "x-goog-user-project": "quota-project",
+    });
+    delete process.env[key];
+  }
+});
+
+test("failed, malformed, or missing Python output cannot leak secrets or fall back", (t) => {
+  env(t);
+  process.env.GCS_CREDS = "private-json";
+  for (const result of [
+    { status: 1, stdout: '{"error":"private-json"}', stderr: "private-json" },
+    { status: null, stdout: "private-json", error: new Error("private-json") },
+    { status: 0, stdout: "{}" },
+  ]) {
+    assert.throws(
+      () => geminiAuth({ run: () => result }),
+      (error) => {
+        assert.match(error.message, /authentication failed/);
+        assert.ok(!error.message.includes("private-json"));
+        return true;
+      },
+    );
+  }
+});
+
+// Keep the Python credential-boundary suite reachable from the normal Node CI runner.
+test("Python service-account boundary validates credentials, scope, transport and errors", () => {
+  const { cmd, args } = pythonInvocation([
+    fileURLToPath(new URL("./gemini-auth_test.py", import.meta.url)),
+  ]);
+  const result = spawnSync(cmd, args, { encoding: "utf8", timeout: 30_000 });
+  assert.equal(result.status, 0, result.stderr || result.error?.message);
+});