hyperframes 0.8.69 → 0.8.70

package/dist/hyperframes-player.global.js

@@ -1,4 +1,4 @@
-"use strict";var HyperframesPlayer=(()=>{var Se=Object.defineProperty;var fn=Object.getOwnPropertyDescriptor;var hn=Object.getOwnPropertyNames;var bn=Object.prototype.hasOwnProperty;var gn=(n,e)=>{for(var t in e)Se(n,t,{get:e[t],enumerable:!0})},_n=(n,e,t,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of hn(e))!bn.call(n,r)&&r!==t&&Se(n,r,{get:()=>e[r],enumerable:!(i=fn(e,r))||i.enumerable});return n};var yn=n=>_n(Se({},"__esModule",{value:!0}),n);var Xi={};gn(Xi,{HyperframesPlayer:()=>Ee,SPEED_PRESETS:()=>we,formatSpeed:()=>G,formatTime:()=>ie});function ct(n){return n.hasRuntime||n.runtimeInjected?!1:!!(n.hasNestedCompositions||n.hasTimelines&&n.attempts>=5)}function H(n){return typeof n=="object"&&n!==null}function mt(n){return H(n)&&typeof n.getDuration=="function"}function pt(n){return H(n)&&typeof n.duration=="function"&&typeof n.time=="function"&&typeof n.seek=="function"&&typeof n.play=="function"&&typeof n.pause=="function"}var L="https://cdn.jsdelivr.net/npm/@hyperframes/core@0.8.69/dist/hyperframe.runtime.iife.js";function V(n){if(n===null)return null;let e=Number.parseInt(n,10);return Number.isFinite(e)&&e>0?e:null}function vn(n){let e=n?.querySelector("[data-composition-id][data-width][data-height]")??n?.querySelector("[data-width][data-height]");if(!e)return null;let t=V(e.getAttribute("data-width")),i=V(e.getAttribute("data-height"));return t!==null&&i!==null?{width:t,height:i}:null}var ne=class{constructor(e,t){this._iframe=e;this._callbacks=t}_iframe;_callbacks;_interval=null;_runtimeInjected=!1;get runtimeInjected(){return this._runtimeInjected}start(){this.stop(),this._runtimeInjected=!1;let e=0;this._interval=setInterval(()=>{e++;try{let t=this._iframe.contentWindow;if(!t)return;let i=!!(t.__hf||t.__player),r=!!(t.__timelines&&Object.keys(t.__timelines).length>0),o=!!this._iframe.contentDocument?.querySelector("[data-composition-src]");if(ct({hasRuntime:i,hasTimelines:r,hasNestedCompositions:o,runtimeInjected:this._runtimeInjected,attempts:e})){this._injectRuntime();return}if(this._runtimeInjected&&!i)return;let a=this._resolvePlaybackDurationAdapter(t);if(a&&a.getDuration()>0){this.stop();let s=vn(this._iframe.contentDocument);this._callbacks.onReady({duration:a.getDuration(),adapter:a,compositionSize:s});return}}catch{}e>=40&&(this.stop(),this._callbacks.onError("Composition timeline not found after 8s"))},200)}stop(){this._interval!==null&&(clearInterval(this._interval),this._interval=null)}resolveDirectTimelineAdapter(){try{let e=this._iframe.contentWindow;return e?this._resolveDirectTimelineAdapterFromWindow(e):null}catch{return null}}resolveDirectTimelineAdapterFromWindow(e){return this._resolveDirectTimelineAdapterFromWindow(e)}hasRuntimeBridge(e){return Reflect.get(e,"__hf")!==void 0||H(Reflect.get(e,"__player"))}_injectRuntime(){this._runtimeInjected=!0;try{let e=this._iframe.contentDocument;if(!e)return;let t=e.createElement("script");t.src=L,(e.head||e.documentElement).appendChild(t),this._callbacks.onRuntimeInjected?.()}catch{}}_resolveDirectTimelineAdapterFromWindow(e){if(this.hasRuntimeBridge(e))return null;let t=Reflect.get(e,"__timelines");if(!H(t))return null;let i=Object.keys(t);if(i.length===0)return null;let r=this._iframe.contentDocument?.querySelector("[data-composition-id]")?.getAttribute("data-composition-id"),o=r&&r in t?r:i[i.length-1],a=t[o];return pt(a)?a:null}_resolvePlaybackDurationAdapter(e){let t=Reflect.get(e,"__player");if(mt(t))return{kind:"runtime",getDuration:()=>t.getDuration()};let i=this._resolveDirectTimelineAdapterFromWindow(e);return i?{kind:"direct-timeline",timeline:i,getDuration:()=>i.duration()}:null}};var ft=`
+"use strict";var HyperframesPlayer=(()=>{var Se=Object.defineProperty;var fn=Object.getOwnPropertyDescriptor;var hn=Object.getOwnPropertyNames;var bn=Object.prototype.hasOwnProperty;var gn=(n,e)=>{for(var t in e)Se(n,t,{get:e[t],enumerable:!0})},_n=(n,e,t,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of hn(e))!bn.call(n,r)&&r!==t&&Se(n,r,{get:()=>e[r],enumerable:!(i=fn(e,r))||i.enumerable});return n};var yn=n=>_n(Se({},"__esModule",{value:!0}),n);var Xi={};gn(Xi,{HyperframesPlayer:()=>Ee,SPEED_PRESETS:()=>we,formatSpeed:()=>G,formatTime:()=>ie});function ct(n){return n.hasRuntime||n.runtimeInjected?!1:!!(n.hasNestedCompositions||n.hasTimelines&&n.attempts>=5)}function H(n){return typeof n=="object"&&n!==null}function mt(n){return H(n)&&typeof n.getDuration=="function"}function pt(n){return H(n)&&typeof n.duration=="function"&&typeof n.time=="function"&&typeof n.seek=="function"&&typeof n.play=="function"&&typeof n.pause=="function"}var L="https://cdn.jsdelivr.net/npm/@hyperframes/core@0.8.70/dist/hyperframe.runtime.iife.js";function V(n){if(n===null)return null;let e=Number.parseInt(n,10);return Number.isFinite(e)&&e>0?e:null}function vn(n){let e=n?.querySelector("[data-composition-id][data-width][data-height]")??n?.querySelector("[data-width][data-height]");if(!e)return null;let t=V(e.getAttribute("data-width")),i=V(e.getAttribute("data-height"));return t!==null&&i!==null?{width:t,height:i}:null}var ne=class{constructor(e,t){this._iframe=e;this._callbacks=t}_iframe;_callbacks;_interval=null;_runtimeInjected=!1;get runtimeInjected(){return this._runtimeInjected}start(){this.stop(),this._runtimeInjected=!1;let e=0;this._interval=setInterval(()=>{e++;try{let t=this._iframe.contentWindow;if(!t)return;let i=!!(t.__hf||t.__player),r=!!(t.__timelines&&Object.keys(t.__timelines).length>0),o=!!this._iframe.contentDocument?.querySelector("[data-composition-src]");if(ct({hasRuntime:i,hasTimelines:r,hasNestedCompositions:o,runtimeInjected:this._runtimeInjected,attempts:e})){this._injectRuntime();return}if(this._runtimeInjected&&!i)return;let a=this._resolvePlaybackDurationAdapter(t);if(a&&a.getDuration()>0){this.stop();let s=vn(this._iframe.contentDocument);this._callbacks.onReady({duration:a.getDuration(),adapter:a,compositionSize:s});return}}catch{}e>=40&&(this.stop(),this._callbacks.onError("Composition timeline not found after 8s"))},200)}stop(){this._interval!==null&&(clearInterval(this._interval),this._interval=null)}resolveDirectTimelineAdapter(){try{let e=this._iframe.contentWindow;return e?this._resolveDirectTimelineAdapterFromWindow(e):null}catch{return null}}resolveDirectTimelineAdapterFromWindow(e){return this._resolveDirectTimelineAdapterFromWindow(e)}hasRuntimeBridge(e){return Reflect.get(e,"__hf")!==void 0||H(Reflect.get(e,"__player"))}_injectRuntime(){this._runtimeInjected=!0;try{let e=this._iframe.contentDocument;if(!e)return;let t=e.createElement("script");t.src=L,(e.head||e.documentElement).appendChild(t),this._callbacks.onRuntimeInjected?.()}catch{}}_resolveDirectTimelineAdapterFromWindow(e){if(this.hasRuntimeBridge(e))return null;let t=Reflect.get(e,"__timelines");if(!H(t))return null;let i=Object.keys(t);if(i.length===0)return null;let r=this._iframe.contentDocument?.querySelector("[data-composition-id]")?.getAttribute("data-composition-id"),o=r&&r in t?r:i[i.length-1],a=t[o];return pt(a)?a:null}_resolvePlaybackDurationAdapter(e){let t=Reflect.get(e,"__player");if(mt(t))return{kind:"runtime",getDuration:()=>t.getDuration()};let i=this._resolveDirectTimelineAdapterFromWindow(e);return i?{kind:"direct-timeline",timeline:i,getDuration:()=>i.duration()}:null}};var ft=`
   :host {
     display: block;
     position: relative;

package/dist/skills/media-use/audio/references/tts-to-captions.md

@@ -14,9 +14,14 @@ node skills/media-use/audio/scripts/heygen-tts.mjs \
 
 `narration.words.json` is already in the `[{ id, text, start, end }]` shape the captions pipeline consumes — no separate transcribe pass.
 
-## Path B — ElevenLabs / Kokoro (TTS → Whisper)
+## Path B — Gemini / ElevenLabs / Kokoro (TTS → transcription)
 
-These providers don't return word data. Generate the audio, then transcribe:
+These adapters supply audio without word data. The shared audio engine runs
+transcription automatically when timings are absent. For Gemini, use the
+request in [Text to speech](tts.md#gemini-narration), then consume
+`audio_meta.json` → `voices[].words`.
+
+For a standalone local Kokoro generation, generate the audio, then transcribe:
 
 ```bash
 npx hyperframes tts script.txt --voice af_heart --output narration.wav
@@ -24,3 +29,7 @@ npx hyperframes transcribe narration.wav --model small.en   # voice af_heart is
 ```
 
 Whisper extracts precise word boundaries from the generated audio, so caption timing matches delivery without hand-tuning. Match `--model` to the voice's language (use `small.en` for `a`/`b` prefixes, `small --language <code>` otherwise). Then consume `transcript.json` via the caption references in `captions/`.
+
+For Gemini, verify that transcription preserved the script, especially names,
+numbers, and delivery pauses. If `words` is empty, resolve the transcription
+failure before captioning. Generate and align again after changing the read.

package/dist/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/dist/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"] }
@@ -113,7 +113,6 @@ 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 audioMeta = openAudioMeta(outPath);
@@ -153,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,
     });
@@ -210,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";
@@ -262,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);

package/dist/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/dist/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/dist/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/dist/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);
+});

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

@@ -0,0 +1,90 @@
+"""Credential-boundary tests; stub Google's transport, never use real secrets."""
+
+import importlib.util
+import json
+import os
+import sys
+from pathlib import Path
+import tempfile
+import types
+import unittest
+from unittest.mock import Mock, patch
+
+
+# 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)
+
+spec = importlib.util.spec_from_file_location("gemini_auth", Path(__file__).with_name("gemini-auth.py"))
+auth = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(auth)
+
+
+class AuthenticationTests(unittest.TestCase):
+    def setUp(self):
+        self.info = {"type": "service_account", "project_id": "account-project", "token_uri": "https://untrusted.invalid/token"}
+        self.credentials = Mock(token="fixture-token")
+        self.factory = Mock(return_value=self.credentials)
+        self.request = Mock(return_value=object())
+        transport = types.ModuleType("google.auth.transport.requests")
+        transport.Request = self.request
+        oauth = types.ModuleType("google.oauth2")
+        oauth.service_account = types.SimpleNamespace(Credentials=types.SimpleNamespace(from_service_account_info=self.factory))
+        modules = {name: types.ModuleType(name) for name in ("google", "google.auth", "google.auth.transport")}
+        modules.update({"google.auth.transport.requests": transport, "google.oauth2": oauth})
+        self.addCleanup(patch.stopall)
+        patch.dict("sys.modules", modules).start()
+        patch.dict(os.environ, {"GCS_CREDS": json.dumps(self.info)}, clear=True).start()
+
+    def test_scope_endpoint_and_refresh(self):
+        self.assertEqual(auth.authenticate(), {"token": "fixture-token", "project": "account-project"})
+        info = self.factory.call_args.args[0]
+        self.assertEqual(info["token_uri"], "https://oauth2.googleapis.com/token")
+        self.assertEqual(self.factory.call_args.kwargs["scopes"], ["https://www.googleapis.com/auth/generative-language.retriever"])
+        self.credentials.refresh.assert_called_once_with(self.request.return_value)
+
+    def test_file_takes_precedence_over_json_environment(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "service.json"
+            path.write_text(json.dumps({**self.info, "project_id": "file-project"}), encoding="utf-8")
+            os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = str(path)
+            os.environ["GCS_CREDS"] = "invalid-json"
+            self.assertEqual(auth.authenticate()["project"], "file-project")
+
+    def test_quota_project_precedence(self):
+        os.environ["GCLOUD_PROJECT_ID"] = "alias-project"
+        self.assertEqual(auth.authenticate()["project"], "alias-project")
+        os.environ["GOOGLE_CLOUD_PROJECT"] = "explicit-project"
+        self.assertEqual(auth.authenticate()["project"], "explicit-project")
+
+    def test_user_adc_is_rejected_before_exchange(self):
+        os.environ["GCS_CREDS"] = json.dumps({"type": "authorized_user"})
+        self.assertIn("service-account JSON", auth.authenticate()["error"])
+        self.factory.assert_not_called()
+
+    def test_invalid_json_or_missing_file_does_not_fall_back(self):
+        os.environ["GCS_CREDS"] = "private-invalid-json"
+        self.assertIn("error", auth.authenticate())
+        os.environ["GCS_CREDS"] = json.dumps(self.info)
+        os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/missing/service-account-fixture.json"
+        self.assertIn("error", auth.authenticate())
+        self.factory.assert_not_called()
+
+    def test_library_errors_are_redacted(self):
+        for boundary in (self.factory, self.credentials.refresh):
+            with self.subTest(boundary=boundary):
+                boundary.side_effect = RuntimeError("private-key-and-token")
+                result = auth.authenticate()
+                self.assertIn("error", result)
+                self.assertNotIn("private-key-and-token", json.dumps(result))
+                boundary.side_effect = None
+
+    def test_missing_dependency_has_actionable_error(self):
+        with patch.dict("sys.modules", {"google.auth.transport.requests": None}):
+            self.assertIn("pip install google-auth requests", auth.authenticate()["error"])
+        self.factory.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()