zilmate 1.9.9 → 1.10.2

package/.agents/skills/hyperframes-media/scripts/lib/heygen.mjs

@@ -0,0 +1,131 @@
+// heygen.mjs — vendored HeyGen REST helpers (auth + transport) for the audio
+// pipeline. The credential resolver is copied from hyperframes-media's
+// heygen-tts.mjs (and matches the hyperframes CLI auth): first usable source
+// wins — $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 { existsSync, 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";
+
+// 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 envPath = join(dir, ".env");
+    if (existsSync(envPath)) {
+      for (const raw of readFileSync(envPath, "utf8").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 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");
+  if (!existsSync(file)) return null;
+  const raw = readFileSync(file, "utf8").trim();
+  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 — this function never throws.
+  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;
+}
+
+// → auth headers object, or throw with a fix hint.
+export function heygenAuthHeaders() {
+  const cred = heygenCredential();
+  if (cred?.headers) return cred.headers;
+  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: { ...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(() => "");
+    throw new Error(
+      `HeyGen ${method} ${path} → HTTP ${res.status}${detail ? `\n${detail.slice(0, 300)}` : ""}`,
+    );
+  }
+  return res.json();
+}
+
+// Download a (presigned) URL to destPath; returns byte length.
+export async function downloadTo(url, destPath) {
+  const res = await fetch(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(", ")}`,
+  );
+}

package/.agents/skills/hyperframes-media/scripts/lib/sfx.mjs

@@ -0,0 +1,128 @@
+// sfx.mjs — sound effects for the media audio engine. Provider-gated (NOT a
+// per-cue merge): the decision is made once, by whether HeyGen is configured —
+// mirroring how TTS and BGM degrade.
+//
+//   HeyGen credential present  →  retrieve EVERY cue from HeyGen's audio library
+//        (/v3/audio/sounds, type=sound_effects, min_score=0.4). The bundled
+//        library is NOT consulted.
+//   HeyGen credential absent   →  resolve cues against the bundled 21-file
+//        library (assets/sfx/manifest.json), copying matched files into the
+//        project. Offline, deterministic, free.
+//
+// A cue that matches nothing is skipped (recorded as an anomaly); SFX never
+// blocks a render. Every cue sits at volume ~0.35, under voice + BGM.
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { downloadTo, searchSounds } from "./heygen.mjs";
+
+const SFX_VOLUME = 0.35;
+const slug = (s) =>
+  s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40) || "x";
+const r3 = (x) => Number(x.toFixed(3));
+
+// cues: [{ id, name }] (id = the line/frame/scene the cue fires in). Returns
+// { sfx: [{ id, name, file, source, offset_s, duration_s, volume }], anomalies }.
+export async function resolveSfx({ cues, heygenOK, headers, hyperframesDir, sfxLibDir }) {
+  const sfx = [];
+  const anomalies = [];
+  const destDir = join(hyperframesDir, "assets", "sfx");
+
+  // Dedupe identical (id,name) cues — the same effect named twice in one line
+  // downloads/copies once.
+  const seen = new Set();
+  const uniq = cues.filter((c) => {
+    const k = `${c.id}:${c.name}`;
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+
+  if (heygenOK) {
+    for (const { id, name } of uniq) {
+      try {
+        // SFX hits score low (~0.5–0.67), below the API's default 0.7 which
+        // silently drops most named cues — floor to 0.4. (BGM/music score high
+        // and keep the default.)
+        const results = await searchSounds(name, "sound_effects", headers, {
+          limit: 3,
+          minScore: 0.4,
+        });
+        if (!results.length) {
+          anomalies.push(`sfx "${name}" (id ${id}): no HeyGen match — skipped`);
+          continue;
+        }
+        const top = results[0];
+        const file = `assets/sfx/${slug(name)}.mp3`;
+        await downloadTo(top.audio_url, join(hyperframesDir, file));
+        sfx.push({
+          id,
+          name,
+          file,
+          source: "heygen",
+          offset_s: 0,
+          duration_s: typeof top.duration === "number" ? r3(top.duration) : 1.0,
+          volume: SFX_VOLUME,
+        });
+      } catch (e) {
+        anomalies.push(`sfx "${name}" (id ${id}): retrieval failed — ${e.message}`);
+      }
+    }
+    return { sfx, anomalies };
+  }
+
+  // ── offline: bundled library ──
+  const manifestPath = join(sfxLibDir, "manifest.json");
+  if (!existsSync(manifestPath)) {
+    if (uniq.length)
+      anomalies.push(`no HeyGen credential and no SFX library at ${sfxLibDir} — all cues dropped`);
+    return { sfx, anomalies };
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (e) {
+    anomalies.push(`SFX manifest parse failed (${e.message}) — all cues dropped`);
+    return { sfx, anomalies };
+  }
+  // Build lookups: by manifest key, by file basename, and by slug of either, so
+  // a cue can name "whoosh", "whoosh.mp3", or "ui click" (→ slug match).
+  const byKey = new Map();
+  for (const [key, entry] of Object.entries(manifest)) {
+    if (!entry?.file || !isFinite(entry.duration)) continue;
+    const rec = { key, file: entry.file, duration: entry.duration };
+    byKey.set(key, rec);
+    byKey.set(entry.file, rec);
+    byKey.set(slug(key), rec);
+    byKey.set(slug(entry.file.replace(/\.\w+$/, "")), rec);
+  }
+  mkdirSync(destDir, { recursive: true });
+  for (const { id, name } of uniq) {
+    const hit = byKey.get(name) ?? byKey.get(slug(name));
+    if (!hit) {
+      const known = [...new Set([...byKey.values()].map((v) => v.key))].slice(0, 8).join(", ");
+      anomalies.push(
+        `sfx "${name}" (id ${id}): not in bundled library — skipped (have: ${known}…)`,
+      );
+      continue;
+    }
+    const src = join(sfxLibDir, hit.file);
+    const destRel = `assets/sfx/${hit.file}`;
+    const dest = join(hyperframesDir, destRel);
+    if (existsSync(src) && !existsSync(dest)) copyFileSync(src, dest);
+    sfx.push({
+      id,
+      name,
+      file: destRel,
+      source: "local",
+      offset_s: 0,
+      duration_s: r3(hit.duration),
+      volume: SFX_VOLUME,
+    });
+  }
+  return { sfx, anomalies };
+}

package/.agents/skills/hyperframes-media/scripts/lib/tts.mjs

@@ -0,0 +1,220 @@
+// tts.mjs — multi-provider TTS for the media audio engine. The provider chain,
+// auto-detected from env, is the one documented in ../SKILL.md:
+//
+//   1. HeyGen (Starfish)  — $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen.
+//        Direct v3 REST (NOT `hyperframes tts`, which in the published build is
+//        Kokoro-only and silently ignores a HeyGen key). Returns word_timestamps
+//        in the same call, so no separate transcribe pass.
+//   2. ElevenLabs         — $ELEVENLABS_API_KEY + `pip install elevenlabs`. No
+//        word timings → caller chains transcribeWav().
+//   3. Kokoro-82M (local) — always available, via the published `hyperframes tts`
+//        CLI. No word timings → caller chains transcribeWav().
+//
+// "HeyGen available" is decided by CREDENTIAL presence (heygenCredential), never
+// by the CLI — see the note above.
+
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { heygenAuthHeaders, heygenCredential, heygenJSON } from "./heygen.mjs";
+
+// ── provider detection ────────────────────────────────────────────────────────
+export function heygenAvailable() {
+  return heygenCredential() !== null;
+}
+export function elevenlabsAvailable() {
+  if (!process.env.ELEVENLABS_API_KEY) return false;
+  const r = spawnSync("python3", ["-c", "import elevenlabs"], { stdio: "ignore" });
+  return r.status === 0;
+}
+
+// First available provider wins; an explicit choice is honored (and validated).
+export function pickProvider(userProvider) {
+  if (userProvider) {
+    if (!["heygen", "elevenlabs", "kokoro"].includes(userProvider))
+      throw new Error(`invalid provider "${userProvider}" (heygen | elevenlabs | kokoro)`);
+    if (userProvider === "heygen" && !heygenAvailable())
+      throw new Error(
+        "provider=heygen but no HeyGen credentials (set $HEYGEN_API_KEY or run `npx hyperframes auth login`)",
+      );
+    if (userProvider === "elevenlabs" && !process.env.ELEVENLABS_API_KEY)
+      throw new Error("provider=elevenlabs but $ELEVENLABS_API_KEY is not set");
+    return userProvider;
+  }
+  return heygenAvailable() ? "heygen" : elevenlabsAvailable() ? "elevenlabs" : "kokoro";
+}
+
+// ── voice resolution ──────────────────────────────────────────────────────────
+// HeyGen /v3/voices/speech only accepts STARFISH voice_ids; auto-pick the first
+// English public starfish voice when none is pinned. ElevenLabs/Kokoro have
+// their own defaults.
+export async function resolveVoiceId({ provider, userVoice, lang = "en" }) {
+  if (userVoice) return userVoice;
+  if (provider === "elevenlabs") return "21m00Tcm4TlvDq8ikWAM"; // Rachel
+  if (provider === "kokoro") {
+    if (lang === "en") return "am_michael";
+    throw new Error("Kokoro non-English needs an explicit --voice (see references/tts.md)");
+  }
+  // heygen — pin a fixed English default so the choice is deterministic. The old
+  // "first English voice the API returns" drifts whenever HeyGen re-sorts the
+  // public catalog. Marcia (mature, low female). Override with --voice / request.voice.
+  if (lang === "en") return "05f19352e8f74b0392a8f411eba40de1"; // Marcia · English · female
+  // Non-English: no fixed default — fall back to the first matching catalog voice.
+  const payload = await heygenJSON(`/voices?engine=starfish&type=public&limit=50`, {
+    headers: heygenAuthHeaders(),
+  });
+  const voices = payload.data ?? payload.voices ?? [];
+  const pick = voices.find((v) => v.language === "English") ?? voices[0];
+  if (!pick) throw new Error("no public starfish voice to default to — pass --voice");
+  return pick.voice_id;
+}
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+export function withWordIds(words) {
+  return (words ?? []).map((w, i) => ({ id: `w${i}`, text: w.text, start: w.start, end: w.end }));
+}
+
+export function ffprobeDuration(absPath) {
+  const r = spawnSync(
+    "ffprobe",
+    ["-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", absPath],
+    { encoding: "utf8" },
+  );
+  if (r.status !== 0) return NaN;
+  return parseFloat(String(r.stdout).trim());
+}
+
+function spawnP(cmd, args, opts) {
+  return new Promise((resolve) => {
+    const p = spawn(cmd, args, { stdio: "ignore", ...opts });
+    p.on("exit", (code) => resolve({ status: code ?? -1 }));
+    p.on("error", () => resolve({ status: -1 }));
+  });
+}
+
+// mp3/whatever bytes → wav 44.1k mono at destWav (ffmpeg detects true format).
+function transcodeToWav(bytes, destWav) {
+  const td = mkdtempSync(join(tmpdir(), "hf-tts-"));
+  const tmp = join(td, "a.mp3");
+  writeFileSync(tmp, bytes);
+  mkdirSync(dirname(destWav), { recursive: true });
+  const ff = spawnSync(
+    "ffmpeg",
+    ["-y", "-loglevel", "error", "-i", tmp, "-ar", "44100", "-ac", "1", destWav],
+    { stdio: "ignore" },
+  );
+  rmSync(td, { recursive: true, force: true });
+  return ff.status === 0 && existsSync(destWav);
+}
+
+const ELEVENLABS_PY = `
+import os, sys
+from elevenlabs.client import ElevenLabs
+from elevenlabs import save
+client = ElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"])
+text = open(sys.argv[1]).read()
+audio = client.text_to_speech.convert(
+    text=text, voice_id=sys.argv[2],
+    model_id="eleven_multilingual_v2", output_format="mp3_44100_128",
+)
+save(audio, sys.argv[3])
+`;
+
+// ── synthesize one line ───────────────────────────────────────────────────────
+// Writes wav at wavAbs. Returns { ok, words } — words is the raw
+// [{text,start,end}] array for HeyGen (native), or null for ElevenLabs/Kokoro
+// (caller must transcribeWav). Never throws; failures return { ok:false }.
+export async function synthesizeOne({
+  provider,
+  text,
+  voiceId,
+  lang = "en",
+  speed = 1.0,
+  wavAbs,
+  hyperframesDir,
+}) {
+  if (provider === "heygen") return synthesizeHeygen({ text, voiceId, lang, speed, wavAbs });
+  if (provider === "elevenlabs") {
+    const r = await spawnP(
+      "python3",
+      ["-c", ELEVENLABS_PY, writeTmpText(text), voiceId, wavAbs],
+      {},
+    );
+    return { ok: r.status === 0 && existsSync(wavAbs), words: null };
+  }
+  // kokoro — via the published CLI; --output is relative to the project dir.
+  const wavRel = relTo(hyperframesDir, wavAbs);
+  const args = ["hyperframes", "tts", writeTmpText(text), "--voice", voiceId, "--output", wavRel];
+  if (lang !== "en") args.push("--lang", lang);
+  const r = await spawnP("npx", args, { cwd: hyperframesDir });
+  return { ok: r.status === 0 && existsSync(wavAbs), words: null };
+}
+
+async function synthesizeHeygen({ text, voiceId, lang, speed, wavAbs }) {
+  try {
+    const body = { text, voice_id: voiceId, speed };
+    if (lang !== "en") body.language = lang;
+    const payload = await heygenJSON(`/voices/speech`, {
+      method: "POST",
+      headers: heygenAuthHeaders(),
+      body,
+    });
+    const inner = payload.data ?? payload;
+    if (!inner.audio_url) return { ok: false, words: null };
+    const res = await fetch(inner.audio_url);
+    if (!res.ok) return { ok: false, words: null };
+    const bytes = Buffer.from(await res.arrayBuffer());
+    // .wav output → transcode to 44.1k mono; .mp3 → raw bytes (no ffmpeg). The
+    // engine always asks for .wav; the standalone heygen-tts CLI may ask for .mp3.
+    if (wavAbs.endsWith(".wav")) {
+      if (!transcodeToWav(bytes, wavAbs)) return { ok: false, words: null };
+    } else {
+      mkdirSync(dirname(wavAbs), { recursive: true });
+      writeFileSync(wavAbs, bytes);
+    }
+    const words = Array.isArray(inner.word_timestamps)
+      ? inner.word_timestamps
+          .filter((w) => w && typeof w.word === "string" && isFinite(w.start) && isFinite(w.end))
+          .filter((w) => !/^<.*>$/.test(w.word.trim())) // drop <start>/<end> sentinels
+          .map((w) => ({ text: w.word, start: w.start, end: w.end }))
+      : [];
+    return { ok: true, words };
+  } catch {
+    return { ok: false, words: null };
+  }
+}
+
+// ElevenLabs/Kokoro have no word timings — run Whisper over the wav. Returns the
+// flat [{id,text,start,end}] word array, or null. Each call uses a throwaway
+// --dir so parallel scenes don't collide on transcript.json.
+export async function transcribeWav({ wavRel, lang = "en", hyperframesDir }) {
+  const model = lang === "en" ? "small.en" : "small";
+  const td = mkdtempSync(join(tmpdir(), "hf-trans-"));
+  const args = ["hyperframes", "transcribe", wavRel, "--model", model, "--dir", td];
+  if (lang !== "en") args.push("--language", lang);
+  const r = await spawnP("npx", args, { cwd: hyperframesDir });
+  let words = null;
+  if (r.status === 0) {
+    const src = join(td, "transcript.json");
+    if (existsSync(src)) {
+      try {
+        const arr = JSON.parse(readFileSync(src, "utf8"));
+        if (Array.isArray(arr) && arr.length) words = arr;
+      } catch {}
+    }
+  }
+  rmSync(td, { recursive: true, force: true });
+  return words;
+}
+
+// ── tiny local utils ──────────────────────────────────────────────────────────
+function writeTmpText(text) {
+  const td = mkdtempSync(join(tmpdir(), "hf-txt-"));
+  const p = join(td, "line.txt");
+  writeFileSync(p, text);
+  return p;
+}
+function relTo(base, abs) {
+  return abs.startsWith(base + "/") ? abs.slice(base.length + 1) : abs;
+}

package/.agents/skills/hyperframes-media/scripts/lyria-recipe.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Generate BGM using Google Lyria RealTime API.
+
+Usage:
+    python lyria-recipe.py --output <path> --duration <seconds> [tuning flags]
+
+Requires:
+    $GOOGLE_API_KEY or $GEMINI_API_KEY environment variable (treated as aliases).
+    pip install google-genai python-dotenv. audio.mjs Step 4b installs these on
+    demand when a key is set but google.genai is not importable; if that install
+    fails it falls back to local MusicGen rather than leaving the video with no BGM.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+import wave
+from pathlib import Path
+
+DEFAULT_PROMPT = "Uplifting corporate tech, bright and modern, gentle piano with synth pads"
+SAMPLE_RATE = 48000
+CHANNELS = 2
+SAMPLE_WIDTH = 2  # 16-bit
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Generate BGM via Google Lyria RealTime.")
+    p.add_argument("--output", required=True, help="Output WAV path.")
+    p.add_argument("--duration", type=float, required=True, help="Target duration in seconds.")
+    p.add_argument("--prompt", default=DEFAULT_PROMPT, help="Mood / instrumentation prompt.")
+    p.add_argument("--negative-prompt", default=None, help="Styles to exclude (optional).")
+    p.add_argument("--bpm", type=int, default=110)
+    p.add_argument("--brightness", type=float, default=0.8, help="0-1, higher = brighter mood.")
+    p.add_argument("--density", type=float, default=0.5, help="0-1, higher = fuller mix.")
+    p.add_argument(
+        "--scale",
+        default="MAJOR",
+        help="MAJOR / MINOR / PENTATONIC / etc. — see google.genai.types.Scale. Pass empty string for none.",
+    )
+    return p.parse_args()
+
+
+async def generate_bgm(args: argparse.Namespace) -> dict:
+    from google import genai
+    from google.genai import types
+
+    api_key = os.environ.get("GOOGLE_API_KEY") or os.environ.get("GEMINI_API_KEY") or ""
+    if not api_key:
+        raise RuntimeError("Neither GOOGLE_API_KEY nor GEMINI_API_KEY is set.")
+
+    client = genai.Client(
+        api_key=api_key,
+        http_options={"api_version": "v1alpha"},
+    )
+
+    out_path = Path(args.output)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    target_bytes = int(args.duration * SAMPLE_RATE * CHANNELS * SAMPLE_WIDTH)
+
+    cfg: dict = {"bpm": args.bpm, "temperature": 1.0}
+    if args.density is not None:
+        cfg["density"] = args.density
+    if args.brightness is not None:
+        cfg["brightness"] = args.brightness
+    if args.scale:
+        scale_enum = getattr(types.Scale, args.scale, None)
+        if scale_enum:
+            cfg["scale"] = scale_enum
+
+    prompts = [types.WeightedPrompt(text=args.prompt, weight=1.0)]
+    if args.negative_prompt:
+        prompts.append(types.WeightedPrompt(text=args.negative_prompt, weight=-1.0))
+
+    buf = bytearray()
+    timeout = args.duration + 8
+
+    async with client.aio.live.music.connect(
+        model="models/lyria-realtime-exp",
+    ) as session:
+        await session.set_weighted_prompts(prompts=prompts)
+        await session.set_music_generation_config(
+            config=types.LiveMusicGenerationConfig(**cfg),
+        )
+        await session.play()
+
+        async def collect():
+            while len(buf) < target_bytes:
+                async for msg in session.receive():
+                    sc = msg.server_content
+                    if sc and sc.audio_chunks:
+                        for chunk in sc.audio_chunks:
+                            buf.extend(chunk.data)
+                            if len(buf) >= target_bytes:
+                                return
+                await asyncio.sleep(1e-6)
+
+        try:
+            await asyncio.wait_for(collect(), timeout=timeout)
+        except TimeoutError:
+            print(f"Timeout after {timeout:.0f}s, collected {len(buf)} bytes", file=sys.stderr)
+
+    audio = bytes(buf[:target_bytes])
+    with wave.open(str(out_path), "wb") as wf:
+        wf.setnchannels(CHANNELS)
+        wf.setsampwidth(SAMPLE_WIDTH)
+        wf.setframerate(SAMPLE_RATE)
+        wf.writeframes(audio)
+
+    actual_duration = len(audio) / (SAMPLE_RATE * CHANNELS * SAMPLE_WIDTH)
+    print(f"BGM: {out_path} ({actual_duration:.2f}s)")
+    return {"file": str(out_path), "duration_sec": round(actual_duration, 2)}
+
+
+def main() -> None:
+    args = parse_args()
+    try:
+        asyncio.run(generate_bgm(args))
+    except RuntimeError as exc:
+        print(f"BGM generation failed: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()