hyper-animator-codex 0.6.0 → 0.7.1

package/skills/hyper-animator-codex/scripts/generate_minimax_tts.mjs

@@ -0,0 +1,556 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  readMinimaxRuntimeConfig,
+  redactMinimaxConfig,
+} from "./minimax_runtime_config.mjs";
+
+const DEFAULT_TTS_ENDPOINT = "https://api.minimaxi.com/v1/t2a_v2";
+const DEFAULT_VOICE_ENDPOINT = "https://api.minimaxi.com/v1/get_voice";
+const DEFAULT_TTS_MODEL = "speech-2.8-hd";
+const DEFAULT_VOICE_ID = "XiaoR_001";
+const EMOTIONS = new Set(["happy", "sad", "angry", "fearful", "disgusted", "surprised", "calm", "fluent", "whipser"]);
+const VOICE_TYPES = new Set(["all", "system", "voice_cloning", "voice_generation"]);
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const skillRoot = dirname(scriptDir);
+
+function requireValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function parseArgs(args) {
+  const parsed = {
+    list_voices: false,
+    voice_type: "all",
+    narration_json: undefined,
+    request_json: undefined,
+    text: undefined,
+    voice_id: undefined,
+    emotion: undefined,
+    language: undefined,
+    output_dir: undefined,
+    model: undefined,
+    audio_format: undefined,
+    sample_rate: undefined,
+    bitrate: undefined,
+    channel: undefined,
+    speed: undefined,
+    volume: undefined,
+    pitch: undefined,
+    subtitle_enable: undefined,
+    config_path: undefined,
+    dry_run: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--list-voices") {
+      parsed.list_voices = true;
+    } else if (arg === "--voice-type") {
+      parsed.voice_type = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--narration-json") {
+      parsed.narration_json = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--request-json") {
+      parsed.request_json = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--text") {
+      parsed.text = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--voice-id") {
+      parsed.voice_id = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--emotion") {
+      parsed.emotion = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--language") {
+      parsed.language = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--output-dir") {
+      parsed.output_dir = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--model") {
+      parsed.model = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--format") {
+      parsed.audio_format = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--sample-rate") {
+      parsed.sample_rate = Number.parseInt(requireValue(args, index, arg), 10);
+      index += 1;
+    } else if (arg === "--bitrate") {
+      parsed.bitrate = Number.parseInt(requireValue(args, index, arg), 10);
+      index += 1;
+    } else if (arg === "--channel") {
+      parsed.channel = Number.parseInt(requireValue(args, index, arg), 10);
+      index += 1;
+    } else if (arg === "--speed") {
+      parsed.speed = Number.parseFloat(requireValue(args, index, arg));
+      index += 1;
+    } else if (arg === "--volume") {
+      parsed.volume = Number.parseFloat(requireValue(args, index, arg));
+      index += 1;
+    } else if (arg === "--pitch") {
+      parsed.pitch = Number.parseInt(requireValue(args, index, arg), 10);
+      index += 1;
+    } else if (arg === "--subtitle-enable") {
+      parsed.subtitle_enable = true;
+    } else if (arg === "--config") {
+      parsed.config_path = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--dry-run") {
+      parsed.dry_run = true;
+    } else if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return parsed;
+}
+
+function printHelp() {
+  console.log(`Usage:
+  node scripts/generate_minimax_tts.mjs --narration-json <file> [options]
+  node scripts/generate_minimax_tts.mjs --list-voices [--voice-type all]
+
+Options:
+  --list-voices              Query MiniMax available voices
+  --voice-type <type>        all, system, voice_cloning, or voice_generation
+  --narration-json <file>    Narration JSON with scenes[].narration
+  --request-json <file>      Structured TTS request options
+  --text <text>              Direct text input
+  --voice-id <id>            MiniMax voice_id, default from narration or XiaoR_001
+  --emotion <label>          happy, sad, angry, fearful, disgusted, surprised, calm, fluent, whipser
+  --language <code>          zh, en, or MiniMax language_boost value
+  --output-dir <dir>         Directory for generated audio and metadata
+  --model <model>            MiniMax speech model, default speech-2.8-hd
+  --format <mp3|wav|pcm>     Audio encoding format, default mp3
+  --sample-rate <rate>       Default 32000
+  --bitrate <bits>           Default 128000
+  --channel <count>          Default 1
+  --speed <value>            Default 1
+  --volume <value>           Default 1
+  --pitch <value>            Default 0
+  --subtitle-enable          Ask MiniMax to include subtitle data when available
+  --config <file>            Explicit MiniMax config JSON
+  --dry-run                  Print redacted request without contacting MiniMax
+`);
+}
+
+function printJson(payload) {
+  console.log(JSON.stringify(payload, null, 2));
+}
+
+function minimaxError(message, fields = {}) {
+  const error = new Error(message);
+  Object.assign(error, fields);
+  return error;
+}
+
+function makeErrorEnvelope(error, attempts = 0) {
+  return {
+    ok: false,
+    provider: "minimax",
+    error: {
+      kind: error.kind || "validation",
+      message: error.message,
+      retryable: Boolean(error.retryable),
+      http_status: error.http_status ?? null,
+      status_code: error.status_code ?? null,
+    },
+    attempts,
+  };
+}
+
+async function readJsonObject(path, label) {
+  if (!path) {
+    return {};
+  }
+
+  const parsed = JSON.parse(await readFile(path, "utf8"));
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw minimaxError(`${label} must contain a JSON object: ${path}`, { kind: "validation" });
+  }
+  return parsed;
+}
+
+function validateNarration(narration) {
+  if (!narration || typeof narration !== "object" || !Array.isArray(narration.scenes)) {
+    throw minimaxError("narration JSON must include scenes[]", { kind: "validation" });
+  }
+
+  narration.scenes.forEach((scene, index) => {
+    if (typeof scene?.narration !== "string" || !scene.narration.trim()) {
+      throw minimaxError(`scenes[${index}].narration is required`, { kind: "validation" });
+    }
+  });
+}
+
+function languageBoost(value) {
+  const language = typeof value === "string" ? value.trim() : "";
+  if (!language || language === "zh" || language === "zh-CN") {
+    return "Chinese";
+  }
+  if (language === "en" || language === "en-US") {
+    return "English";
+  }
+  return language;
+}
+
+function mergeOptions({ requestJson, narration, cliOptions }) {
+  const narrationText = narration?.scenes?.map((scene) => scene.narration.trim()).filter(Boolean).join("\n");
+
+  return {
+    text: cliOptions.text ?? requestJson.text ?? narrationText,
+    voice_id: cliOptions.voice_id ?? requestJson.voice_id ?? narration?.voice ?? DEFAULT_VOICE_ID,
+    emotion: cliOptions.emotion ?? requestJson.emotion ?? narration?.emotion ?? "calm",
+    language: cliOptions.language ?? requestJson.language ?? narration?.language ?? "zh",
+    output_dir: cliOptions.output_dir ?? requestJson.output_dir ?? join(process.cwd(), "hyper-animator-output", "voice"),
+    model: cliOptions.model ?? requestJson.model ?? DEFAULT_TTS_MODEL,
+    audio_format: cliOptions.audio_format ?? requestJson.audio_format ?? "mp3",
+    sample_rate: cliOptions.sample_rate ?? requestJson.sample_rate ?? 32000,
+    bitrate: cliOptions.bitrate ?? requestJson.bitrate ?? 128000,
+    channel: cliOptions.channel ?? requestJson.channel ?? 1,
+    speed: cliOptions.speed ?? requestJson.speed ?? 1,
+    volume: cliOptions.volume ?? requestJson.volume ?? 1,
+    pitch: cliOptions.pitch ?? requestJson.pitch ?? 0,
+    subtitle_enable: cliOptions.subtitle_enable ?? Boolean(requestJson.subtitle_enable),
+  };
+}
+
+function validateOptions(options) {
+  if (!options.text || !options.text.trim()) {
+    throw minimaxError("--text or --narration-json is required", { kind: "validation" });
+  }
+  if (options.text.length >= 10000) {
+    throw minimaxError("MiniMax TTS text must be fewer than 10000 characters", { kind: "validation" });
+  }
+  if (!options.voice_id || !options.voice_id.trim()) {
+    throw minimaxError("voice_id is required", { kind: "validation" });
+  }
+  if (!EMOTIONS.has(options.emotion)) {
+    throw minimaxError(`Unsupported emotion: ${options.emotion}`, { kind: "validation" });
+  }
+  if (!["mp3", "wav", "pcm"].includes(options.audio_format)) {
+    throw minimaxError("--format must be mp3, wav, or pcm", { kind: "validation" });
+  }
+  if (![16000, 24000, 32000, 44100].includes(options.sample_rate)) {
+    throw minimaxError("--sample-rate must be 16000, 24000, 32000, or 44100", { kind: "validation" });
+  }
+  if (![32000, 64000, 128000, 256000].includes(options.bitrate)) {
+    throw minimaxError("--bitrate must be 32000, 64000, 128000, or 256000", { kind: "validation" });
+  }
+  if (![1, 2].includes(options.channel)) {
+    throw minimaxError("--channel must be 1 or 2", { kind: "validation" });
+  }
+}
+
+function buildTtsRequest(options) {
+  return {
+    model: options.model,
+    text: options.text,
+    stream: false,
+    output_format: "hex",
+    voice_setting: {
+      voice_id: options.voice_id,
+      speed: options.speed,
+      vol: options.volume,
+      pitch: options.pitch,
+      emotion: options.emotion,
+    },
+    audio_setting: {
+      sample_rate: options.sample_rate,
+      bitrate: options.bitrate,
+      format: options.audio_format,
+      channel: options.channel,
+    },
+    language_boost: languageBoost(options.language),
+    subtitle_enable: options.subtitle_enable,
+  };
+}
+
+function endpointFromEnv(env = process.env) {
+  return {
+    tts: env.MINIMAX_TTS_ENDPOINT || DEFAULT_TTS_ENDPOINT,
+    voice: env.MINIMAX_VOICE_ENDPOINT || DEFAULT_VOICE_ENDPOINT,
+  };
+}
+
+function timeoutFromEnv(env = process.env) {
+  const value = Number.parseInt(env.MINIMAX_REQUEST_TIMEOUT_MS || "60000", 10);
+  return Number.isFinite(value) && value > 0 ? value : 60000;
+}
+
+function classifyHttpStatus(status) {
+  if (status === 401 || status === 403) {
+    return { kind: "auth", retryable: false };
+  }
+  if (status === 429) {
+    return { kind: "rate_limit", retryable: true };
+  }
+  if (status >= 500) {
+    return { kind: "server", retryable: true };
+  }
+  return { kind: "response", retryable: false };
+}
+
+async function fetchWithTimeout(url, options, timeoutMs) {
+  if (!URL.canParse(url)) {
+    throw minimaxError(`MiniMax endpoint is not a valid URL: ${url}`, { kind: "validation" });
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...options, signal: controller.signal });
+  } catch (error) {
+    if (error?.name === "AbortError") {
+      throw minimaxError("MiniMax request timed out", { kind: "timeout", retryable: true });
+    }
+    if (typeof error?.cause?.code === "string") {
+      throw minimaxError(`MiniMax network error: ${error.message}`, { kind: "network", retryable: true });
+    }
+    throw minimaxError(`MiniMax request setup failed: ${error.message}`, { kind: "response" });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function postMiniMax(config, endpoint, request, timeoutMs) {
+  const response = await fetchWithTimeout(endpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${config.api_key}`,
+    },
+    body: JSON.stringify(request),
+  }, timeoutMs);
+
+  const text = await response.text();
+  let json = null;
+
+  if (text) {
+    try {
+      json = JSON.parse(text);
+    } catch {
+      json = null;
+    }
+  }
+
+  if (!response.ok) {
+    const message = json?.base_resp?.status_msg || `HTTP ${response.status}`;
+    throw minimaxError(`MiniMax request failed: ${message}`, {
+      ...classifyHttpStatus(response.status),
+      http_status: response.status,
+      status_code: json?.base_resp?.status_code ?? null,
+    });
+  }
+
+  if (!json) {
+    throw minimaxError(`MiniMax returned non-JSON response with HTTP ${response.status}`, {
+      kind: "response",
+      http_status: response.status,
+    });
+  }
+
+  const statusCode = json.base_resp?.status_code;
+  if (statusCode !== undefined && statusCode !== 0) {
+    const message = json.base_resp?.status_msg || "unknown MiniMax error";
+    throw minimaxError(`MiniMax request failed with status_code ${statusCode}: ${message}`, {
+      kind: "provider",
+      http_status: response.status,
+      status_code: statusCode,
+    });
+  }
+
+  return json;
+}
+
+function decodeHexAudio(value) {
+  if (typeof value !== "string" || !/^[0-9a-fA-F]+$/.test(value) || value.length % 2 !== 0) {
+    throw minimaxError("MiniMax response audio is not valid hex data", { kind: "response" });
+  }
+  return Buffer.from(value, "hex");
+}
+
+function safeFileStem(value) {
+  const stem = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+  return stem || "minimax-tts";
+}
+
+async function writeTtsOutput({ responseJson, request, outputDir, endpoint }) {
+  if (responseJson.data?.status !== 2) {
+    throw minimaxError(`MiniMax TTS generation is not complete; data.status is ${responseJson.data?.status}`, { kind: "provider" });
+  }
+  if (!responseJson.data?.audio) {
+    throw minimaxError("MiniMax response did not include data.audio", { kind: "provider" });
+  }
+
+  await mkdir(outputDir, { recursive: true });
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const extension = request.audio_setting.format === "pcm" ? "pcm" : request.audio_setting.format;
+  const stem = `${safeFileStem(request.voice_setting.voice_id)}-${timestamp}`;
+  const audioPath = join(outputDir, `${stem}.${extension}`);
+  const metadataPath = join(outputDir, `${stem}.minimax-tts.json`);
+
+  await writeFile(audioPath, decodeHexAudio(responseJson.data.audio));
+  await writeFile(metadataPath, `${JSON.stringify({
+    provider: "minimax",
+    endpoint,
+    request,
+    response: {
+      base_resp: responseJson.base_resp,
+      data: { status: responseJson.data.status },
+      extra_info: responseJson.extra_info,
+      trace_id: responseJson.trace_id,
+    },
+    audio_path: audioPath,
+  }, null, 2)}\n`, "utf8");
+
+  return { audioPath, metadataPath };
+}
+
+function flattenVoices(json) {
+  const order = ["voice_cloning", "voice_generation", "system_voice", "music_generation"];
+  return order.flatMap((type) => (Array.isArray(json[type]) ? json[type] : []).map((voice) => ({
+    type,
+    voice_id: voice.voice_id,
+    voice_name: voice.voice_name,
+    description: voice.description,
+    created_time: voice.created_time,
+  })));
+}
+
+async function readRuntime(options) {
+  let runtime;
+  try {
+    runtime = await readMinimaxRuntimeConfig({
+      skillRoot,
+      env: process.env,
+      configPath: options.config_path,
+    });
+  } catch (error) {
+    throw Object.assign(error, { kind: "config", retryable: false });
+  }
+
+  if (!runtime) {
+    throw minimaxError("MiniMax config not found. Run hyper-animator-codex install with --minimax-api-key and --minimax-group-id, or set MINIMAX_API_KEY and MINIMAX_GROUP_ID.", {
+      kind: "config",
+      retryable: false,
+    });
+  }
+
+  return runtime;
+}
+
+async function listVoices(options, runtime, endpoints, timeoutMs) {
+  if (!VOICE_TYPES.has(options.voice_type)) {
+    throw minimaxError(`Unsupported voice_type: ${options.voice_type}`, { kind: "validation" });
+  }
+
+  const request = { voice_type: options.voice_type };
+  const responseJson = await postMiniMax(runtime.config, endpoints.voice, request, timeoutMs);
+
+  return {
+    ok: true,
+    provider: "minimax",
+    endpoint: endpoints.voice,
+    voice_type: options.voice_type,
+    config: {
+      source: runtime.source,
+      path: runtime.configPath,
+      redacted: redactMinimaxConfig(runtime.config),
+    },
+    voices: flattenVoices(responseJson),
+  };
+}
+
+async function main() {
+  try {
+    const cliOptions = parseArgs(process.argv.slice(2));
+    const endpoints = endpointFromEnv();
+    const timeoutMs = timeoutFromEnv();
+
+    if (cliOptions.help) {
+      printHelp();
+      return;
+    }
+
+    const runtime = await readRuntime(cliOptions);
+
+    if (cliOptions.list_voices) {
+      printJson(await listVoices(cliOptions, runtime, endpoints, timeoutMs));
+      return;
+    }
+
+    const requestJson = await readJsonObject(cliOptions.request_json, "--request-json");
+    const narration = cliOptions.narration_json
+      ? await readJsonObject(cliOptions.narration_json, "--narration-json")
+      : null;
+    if (narration) {
+      validateNarration(narration);
+    }
+
+    const options = mergeOptions({ requestJson, narration, cliOptions });
+    validateOptions(options);
+    const request = buildTtsRequest(options);
+    const redactedConfig = redactMinimaxConfig(runtime.config);
+
+    if (options.dry_run || cliOptions.dry_run) {
+      printJson({
+        ok: true,
+        dry_run: true,
+        provider: "minimax",
+        endpoint: endpoints.tts,
+        config: {
+          source: runtime.source,
+          path: runtime.configPath,
+          redacted: redactedConfig,
+        },
+        request_path: cliOptions.request_json,
+        narration_path: cliOptions.narration_json,
+        request,
+        output_dir: options.output_dir,
+      });
+      return;
+    }
+
+    const responseJson = await postMiniMax(runtime.config, endpoints.tts, request, timeoutMs);
+    const output = await writeTtsOutput({
+      responseJson,
+      request,
+      outputDir: options.output_dir,
+      endpoint: endpoints.tts,
+    });
+
+    printJson({
+      ok: true,
+      provider: "minimax",
+      model: request.model,
+      voice_id: request.voice_setting.voice_id,
+      emotion: request.voice_setting.emotion,
+      output_path: output.audioPath,
+      metadata_path: output.metadataPath,
+      extra_info: responseJson.extra_info,
+    });
+  } catch (error) {
+    printJson(makeErrorEnvelope(error, error.attempts ?? 0));
+    process.exitCode = 1;
+  }
+}
+
+main();