hyper-animator-codex 0.2.0 → 0.3.0

package/README.md

@@ -37,6 +37,37 @@ Use a custom Codex skills directory:
 npx hyper-animator-codex install --target /path/to/codex/skills
 ```
 
+## MiniMax Music Configuration
+
+MiniMax is the preferred generated-background-music provider. Configure it during install so the copied Codex skill can generate music without asking for credentials later:
+
+```bash
+npx hyper-animator-codex install --force \
+  --minimax-api-key "$MINIMAX_API_KEY" \
+  --minimax-group-id "$MINIMAX_GROUP_ID" \
+  --minimax-model music-2.6-free
+```
+
+Environment fallback is also supported:
+
+```bash
+MINIMAX_API_KEY=... MINIMAX_GROUP_ID=... npx hyper-animator-codex install --force
+```
+
+Or load a JSON config file:
+
+```bash
+npx hyper-animator-codex install --force --minimax-config ./minimax.json
+```
+
+The installer writes local config to:
+
+```text
+${CODEX_HOME:-$HOME/.codex}/skills/hyper-animator-codex/config/minimax.json
+```
+
+Do not commit that installed config file. The npm package does not include local MiniMax credentials.
+
 ## Contents
 
 - `skills/hyper-animator-codex/SKILL.md`: Codex skill instructions.
@@ -61,6 +92,16 @@ Run the bundled analyzer from an installed skill directory or repository checkou
 python3 skills/hyper-animator-codex/scripts/analyze_music_beats.py path/to/music.wav -o beat-map.json --fps 60 --pretty
 ```
 
+Generate MiniMax background music from an installed skill directory:
+
+```bash
+node scripts/generate_minimax_music.mjs \
+  --prompt "bright electronic product launch, confident, clean, rising energy" \
+  --output-dir hyper-animator-output/music
+```
+
+Then analyze the generated audio with `analyze_music_beats.py` and align animation timing to the resulting beat map.
+
 ## Development
 
 ```bash

package/bin/hyper-animator-codex.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { installSkill, resolveCodexSkillsRoot, SKILL_NAME } from "../lib/install-skill.mjs";
+import { parseInstallArgs } from "../lib/install-options.mjs";
 
 function printHelp() {
   console.log(`Usage:
-  hyper-animator-codex install [--force] [--target <skills-dir>]
+  hyper-animator-codex install [--force] [--target <skills-dir>] [MiniMax options]
   hyper-animator-codex path
   hyper-animator-codex help
 
@@ -13,36 +14,18 @@ Commands:
   help     Show this help
 
 Options:
-  --force            Replace an existing installed skill
-  --target <dir>     Install into a specific Codex skills directory
+  --force                         Replace an existing installed skill
+  --target <dir>                  Install into a specific Codex skills directory
+  --minimax-api-key <key>         Save MiniMax API key into installed skill config
+  --minimax-group-id <group_id>   Save MiniMax group_id into installed skill config
+  --minimax-model <model>         MiniMax text music model: music-2.6 or music-2.6-free
+  --minimax-config <file>         Load MiniMax JSON config with api_key, group_id, and model
+
+Environment fallback:
+  MINIMAX_API_KEY, MINIMAX_GROUP_ID, MINIMAX_MODEL
 `);
 }
 
-function parseInstallArgs(args) {
-  const parsed = {
-    force: false,
-    targetRoot: undefined,
-  };
-
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === "--force") {
-      parsed.force = true;
-    } else if (arg === "--target") {
-      const value = args[index + 1];
-      if (!value) {
-        throw new Error("--target requires a directory");
-      }
-      parsed.targetRoot = value;
-      index += 1;
-    } else {
-      throw new Error(`Unknown option: ${arg}`);
-    }
-  }
-
-  return parsed;
-}
-
 async function main() {
   const [command = "install", ...args] = process.argv.slice(2);
 
@@ -66,6 +49,11 @@ async function main() {
   console.log(`Installed ${result.skillName}`);
   console.log(`Source: ${result.sourcePath}`);
   console.log(`Target: ${result.installedPath}`);
+
+  if (result.minimaxConfigPath) {
+    console.log(`MiniMax config: ${result.minimaxConfigPath}`);
+    console.log(`MiniMax model: ${result.minimaxConfig.model}`);
+  }
 }
 
 main().catch((error) => {

package/lib/install-options.mjs

@@ -0,0 +1,44 @@
+function requireValue(args, index, flag) {
+  const value = args[index + 1];
+
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${flag} requires a value`);
+  }
+
+  return value;
+}
+
+export function parseInstallArgs(args) {
+  const parsed = {
+    force: false,
+    targetRoot: undefined,
+    minimaxConfig: {},
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--force") {
+      parsed.force = true;
+    } else if (arg === "--target") {
+      parsed.targetRoot = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--minimax-api-key") {
+      parsed.minimaxConfig.api_key = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--minimax-group-id") {
+      parsed.minimaxConfig.group_id = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--minimax-model") {
+      parsed.minimaxConfig.model = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--minimax-config") {
+      parsed.minimaxConfig.config_path = requireValue(args, index, arg);
+      index += 1;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return parsed;
+}

package/lib/install-skill.mjs

@@ -3,6 +3,12 @@ import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import {
+  redactMinimaxConfig,
+  resolveInstallMinimaxConfig,
+  writeMinimaxConfig,
+} from "./minimax-config.mjs";
+
 export const SKILL_NAME = "hyper-animator-codex";
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -61,9 +67,19 @@ export async function installSkill(options = {}) {
     filter: shouldCopy,
   });
 
+  const resolvedMinimaxConfig = await resolveInstallMinimaxConfig({
+    cliConfig: options.minimaxConfig || {},
+    env: options.env || process.env,
+  });
+  const minimaxWrite = resolvedMinimaxConfig
+    ? await writeMinimaxConfig(installedPath, resolvedMinimaxConfig)
+    : null;
+
   return {
     skillName: SKILL_NAME,
     sourcePath,
     installedPath,
+    minimaxConfigPath: minimaxWrite ? minimaxWrite.configPath : null,
+    minimaxConfig: minimaxWrite ? redactMinimaxConfig(minimaxWrite.config) : null,
   };
 }

package/lib/minimax-config.mjs

@@ -0,0 +1,162 @@
+import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export const DEFAULT_MINIMAX_MODEL = "music-2.6-free";
+export const TEXT_MUSIC_MODELS = new Set(["music-2.6", "music-2.6-free"]);
+export const MINIMAX_CONFIG_RELATIVE_PATH = join("config", "minimax.json");
+
+async function pathExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function cleanString(value) {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function normalizeInput(input = {}) {
+  return {
+    api_key: cleanString(input.api_key),
+    group_id: cleanString(input.group_id),
+    model: cleanString(input.model),
+  };
+}
+
+function hasConfigValues(input = {}) {
+  return Boolean(cleanString(input.api_key) || cleanString(input.group_id) || cleanString(input.model));
+}
+
+async function readConfigFile(configPath) {
+  const raw = await readFile(configPath, "utf8");
+  let parsed;
+
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`MiniMax config file is not valid JSON: ${configPath}`);
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`MiniMax config file must contain a JSON object: ${configPath}`);
+  }
+
+  return parsed;
+}
+
+export function validateMinimaxConfig(config = {}) {
+  const normalized = normalizeInput(config);
+
+  if (!normalized.api_key) {
+    throw new Error("MiniMax api_key is required when MiniMax config is provided");
+  }
+
+  if (!normalized.group_id) {
+    throw new Error("MiniMax group_id is required when MiniMax config is provided");
+  }
+
+  const model = normalized.model || DEFAULT_MINIMAX_MODEL;
+
+  if (!TEXT_MUSIC_MODELS.has(model)) {
+    throw new Error(`Unsupported MiniMax text music model: ${model}. Use music-2.6 or music-2.6-free.`);
+  }
+
+  return {
+    api_key: normalized.api_key,
+    group_id: normalized.group_id,
+    model,
+  };
+}
+
+export async function resolveInstallMinimaxConfig({ cliConfig = {}, env = process.env } = {}) {
+  const configPath = cleanString(cliConfig.config_path);
+  const fileConfig = configPath ? await readConfigFile(configPath) : {};
+  const directConfig = normalizeInput(cliConfig);
+  const envConfig = normalizeInput({
+    api_key: env.MINIMAX_API_KEY,
+    group_id: env.MINIMAX_GROUP_ID,
+    model: env.MINIMAX_MODEL,
+  });
+
+  const merged = {
+    api_key: directConfig.api_key || cleanString(fileConfig.api_key) || envConfig.api_key,
+    group_id: directConfig.group_id || cleanString(fileConfig.group_id) || envConfig.group_id,
+    model: directConfig.model || cleanString(fileConfig.model) || envConfig.model,
+  };
+
+  if (!configPath && !hasConfigValues(directConfig) && !hasConfigValues(envConfig)) {
+    return null;
+  }
+
+  return validateMinimaxConfig(merged);
+}
+
+export async function writeMinimaxConfig(installedPath, config) {
+  const normalized = validateMinimaxConfig(config);
+  const configDir = join(installedPath, "config");
+  const configPath = join(installedPath, MINIMAX_CONFIG_RELATIVE_PATH);
+  const body = `${JSON.stringify(normalized, null, 2)}\n`;
+
+  await mkdir(configDir, { recursive: true });
+  await writeFile(configPath, body, { encoding: "utf8", mode: 0o600 });
+  await chmod(configPath, 0o600);
+
+  return {
+    configPath,
+    config: normalized,
+    redactedConfig: redactMinimaxConfig(normalized),
+  };
+}
+
+export async function readRuntimeMinimaxConfig({ skillRoot, env = process.env } = {}) {
+  if (!skillRoot) {
+    throw new Error("skillRoot is required to read MiniMax runtime config");
+  }
+
+  const configPath = join(skillRoot, MINIMAX_CONFIG_RELATIVE_PATH);
+
+  if (await pathExists(configPath)) {
+    return {
+      source: "file",
+      configPath,
+      config: validateMinimaxConfig(await readConfigFile(configPath)),
+    };
+  }
+
+  const envConfig = normalizeInput({
+    api_key: env.MINIMAX_API_KEY,
+    group_id: env.MINIMAX_GROUP_ID,
+    model: env.MINIMAX_MODEL,
+  });
+
+  if (!hasConfigValues(envConfig)) {
+    return null;
+  }
+
+  return {
+    source: "environment",
+    configPath: null,
+    config: validateMinimaxConfig(envConfig),
+  };
+}
+
+export function redactMinimaxConfig(config = {}) {
+  const normalized = normalizeInput(config);
+
+  return {
+    api_key: normalized.api_key ? "[redacted]" : undefined,
+    group_id: normalized.group_id,
+    model: normalized.model || DEFAULT_MINIMAX_MODEL,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyper-animator-codex",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Install the Hyper Animator Codex skill for Codex.",
   "type": "module",
   "bin": {

package/skills/hyper-animator-codex/SKILL.md

@@ -19,12 +19,13 @@ Turn a natural-language animation or video brief into a validated HyperFrames HT
    - `generate_new_hyperframes_html` when the user asks to write HTML, create a new effect, customize style, match a brand, use complex animation, or when component snippets are only paste placeholders.
    - `assemble_existing_catalog_items` only when the user asks to use existing catalog items or quickly compose installed blocks/components.
 6. Clarify audio: ask whether to add animation/transition sound effects and whether to add background music.
-7. If background music is used, read `references/beat-sync-workflow.md`, ask for the local audio path, and run `scripts/analyze_music_beats.py` when the file is available.
-8. Ask the second clarification round with candidate context: visual direction, motion rhythm, generation mode, audio choices, and any candidate tradeoffs.
-9. Write or assemble HTML. When beat-sync is enabled, align major reveals, cuts, transitions, camera moves, and visual accents to the beat map instead of arbitrary timestamps.
-10. Run pre-render quality gates.
-11. Show a concise plan summary and preview path or HTML file to the user. Ask for confirmation before video render.
-12. Render only after user confirmation, then report output path and any caveats.
+7. If background music is requested or undecided, read `references/minimax-music-workflow.md` and prefer MiniMax generation when configured. If MiniMax is unavailable or declined, ask for a local audio path or continue without BGM.
+8. If background music is used, read `references/beat-sync-workflow.md`, generate or obtain the audio, and run `scripts/analyze_music_beats.py` when the file is available.
+9. Ask the second clarification round with candidate context: visual direction, motion rhythm, generation mode, audio choices, music prompt/model when MiniMax is used, and beat-sync assumptions when background music is present.
+10. Write or assemble HTML. When beat-sync is enabled, align major reveals, cuts, transitions, camera moves, and visual accents to the beat map instead of arbitrary timestamps.
+11. Run pre-render quality gates.
+12. Show a concise plan summary and preview path or HTML file to the user. Ask for confirmation before video render.
+13. Render only after user confirmation, then report output path and any caveats.
 
 ## Interactive Questions
 
@@ -42,6 +43,7 @@ Do not ask everything upfront when the brief is already specific. Ask only for m
 - Read `references/hyperframes-intent-workflow.md` for the full AskUserQuestion workflow, generation-mode rules, scoring model, and render confirmation requirements.
 - Read `references/hyperframes-catalog-map.json` whenever selecting catalog candidates or determining visual references.
 - Read `references/hyperframes-agent-pseudocode.ts` when implementing the end-to-end loop or when the correct sequence is ambiguous.
+- Read `references/minimax-music-workflow.md` when generated background music, MiniMax, music prompt, instrumental/vocal choice, or provider fallback is mentioned.
 - Read `references/beat-sync-workflow.md` when sound effects, background music, soundtrack, beat sync, rhythm, BPM, audio-reactive animation, or transition timing to music is mentioned.
 - Use `references/examples/*.json` for sanity checks against common request shapes.
 
@@ -83,6 +85,7 @@ Before rendering, summarize:
 - generation mode;
 - selected or referenced catalog items;
 - sound effects and background music choices;
+- MiniMax provider status, model, generated audio path, metadata path, and redacted config source when MiniMax is used;
 - beat map path, BPM, duration, and timing assumptions when beat-sync is enabled;
 - dimensions and duration;
 - content assumptions;

package/skills/hyper-animator-codex/references/minimax-music-workflow.md

@@ -0,0 +1,77 @@
+# MiniMax Music Workflow
+
+Use this when the user wants generated background music or asks whether Hyper Animator Codex can create music for an animation.
+
+## MiniMax Preference
+
+Prefer MiniMax before other background-music sources when `config/minimax.json` exists in the installed skill or `MINIMAX_API_KEY` and `MINIMAX_GROUP_ID` are present in the environment.
+
+The installed config shape is:
+
+```json
+{
+  "api_key": "[redacted]",
+  "group_id": "group_id",
+  "model": "music-2.6-free"
+}
+```
+
+Do not print or echo the raw API key. `group_id` is stored because the installer collects it, but the current `/v1/music_generation` API call uses only `Authorization: Bearer <API_key>` and the documented JSON request body.
+
+## Clarify Music
+
+Ask only for missing choices:
+
+- Should background music be generated with MiniMax, supplied as a local file, or skipped?
+- What mood, genre, energy, audience, and scene should the music prompt express?
+- Should the music be instrumental or vocal?
+- For vocal music, should the user provide lyrics or allow MiniMax lyrics optimization?
+- Should animation duration follow the generated music, or should the generated music be trimmed or looped to the planned duration?
+
+## Generate Music
+
+From the installed skill directory:
+
+```bash
+node scripts/generate_minimax_music.mjs \
+  --prompt "bright electronic product launch, confident, clean, rising energy" \
+  --output-dir hyper-animator-output/music
+```
+
+For vocal music with user-provided lyrics:
+
+```bash
+node scripts/generate_minimax_music.mjs \
+  --prompt "optimistic pop launch hook, energetic, modern SaaS demo" \
+  --vocal \
+  --lyrics "[Verse]\n..." \
+  --output-dir hyper-animator-output/music
+```
+
+For vocal music where MiniMax should create lyrics:
+
+```bash
+node scripts/generate_minimax_music.mjs \
+  --prompt "optimistic pop launch hook, energetic, modern SaaS demo" \
+  --vocal \
+  --lyrics-optimizer \
+  --output-dir hyper-animator-output/music
+```
+
+Use `--dry-run` before a real call when checking config, request shape, or model choice.
+
+## Beat Sync
+
+After music generation succeeds, analyze the generated audio:
+
+```bash
+python3 scripts/analyze_music_beats.py hyper-animator-output/music/generated.mp3 -o hyper-animator-output/music/beat-map.json --fps 60 --pretty
+```
+
+Use the resulting beat map exactly as described in `references/beat-sync-workflow.md`.
+
+## Fallbacks
+
+If MiniMax config is missing, ask whether the user wants to provide a local audio file or continue without background music.
+
+If MiniMax generation fails, summarize the provider, model, redacted config source, and error message. Then ask whether to retry with a different prompt/model, use a local audio file, or continue without background music.

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

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  DEFAULT_MINIMAX_MODEL,
+  readMinimaxRuntimeConfig,
+  redactMinimaxConfig,
+  validateMinimaxConfig,
+} from "./minimax_runtime_config.mjs";
+
+const ENDPOINT = "https://api.minimaxi.com/v1/music_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 = {
+    prompt: undefined,
+    lyrics: undefined,
+    lyrics_optimizer: false,
+    is_instrumental: true,
+    output_dir: join(process.cwd(), "hyper-animator-output", "music"),
+    output_format: "hex",
+    audio_format: "mp3",
+    sample_rate: 44100,
+    bitrate: 256000,
+    model: undefined,
+    config_path: undefined,
+    dry_run: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--prompt") {
+      parsed.prompt = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--lyrics") {
+      parsed.lyrics = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--lyrics-optimizer") {
+      parsed.lyrics_optimizer = true;
+    } else if (arg === "--instrumental") {
+      parsed.is_instrumental = true;
+    } else if (arg === "--vocal") {
+      parsed.is_instrumental = false;
+    } else if (arg === "--output-dir") {
+      parsed.output_dir = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--output-format") {
+      parsed.output_format = 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 === "--model") {
+      parsed.model = requireValue(args, index, arg);
+      index += 1;
+    } 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_music.mjs --prompt <text> [options]
+
+Options:
+  --prompt <text>              Music style, mood, and scene prompt
+  --lyrics <text>              Lyrics for vocal generation
+  --lyrics-optimizer           Let MiniMax generate lyrics from prompt for vocal generation
+  --instrumental               Generate instrumental music, default
+  --vocal                      Generate vocal music; requires --lyrics or --lyrics-optimizer
+  --output-dir <dir>           Directory for generated audio and metadata
+  --output-format <hex|url>    MiniMax response format, default hex
+  --format <mp3|wav|pcm>       Audio encoding format, default mp3
+  --sample-rate <rate>         16000, 24000, 32000, or 44100; default 44100
+  --bitrate <bits>             32000, 64000, 128000, or 256000; default 256000
+  --model <model>              music-2.6 or music-2.6-free
+  --config <file>              Explicit MiniMax config JSON
+  --dry-run                    Print redacted request without contacting MiniMax
+`);
+}
+
+function validateOptions(options) {
+  if (!options.prompt || options.prompt.trim().length === 0) {
+    throw new Error("--prompt is required");
+  }
+
+  if (options.prompt.length > 2000) {
+    throw new Error("--prompt must be 2000 characters or fewer");
+  }
+
+  if (!["hex", "url"].includes(options.output_format)) {
+    throw new Error("--output-format must be hex or url");
+  }
+
+  if (!["mp3", "wav", "pcm"].includes(options.audio_format)) {
+    throw new Error("--format must be mp3, wav, or pcm");
+  }
+
+  if (![16000, 24000, 32000, 44100].includes(options.sample_rate)) {
+    throw new Error("--sample-rate must be 16000, 24000, 32000, or 44100");
+  }
+
+  if (![32000, 64000, 128000, 256000].includes(options.bitrate)) {
+    throw new Error("--bitrate must be 32000, 64000, 128000, or 256000");
+  }
+
+  if (!options.is_instrumental && !options.lyrics && !options.lyrics_optimizer) {
+    throw new Error("Vocal MiniMax generation requires --lyrics or --lyrics-optimizer");
+  }
+
+  if (options.lyrics && options.lyrics.length > 3500) {
+    throw new Error("--lyrics must be 3500 characters or fewer");
+  }
+}
+
+function buildRequest(options, config) {
+  const model = options.model || config.model || DEFAULT_MINIMAX_MODEL;
+  const validatedConfig = validateMinimaxConfig({
+    ...config,
+    model,
+  });
+
+  const request = {
+    model: validatedConfig.model,
+    prompt: options.prompt,
+    stream: false,
+    output_format: options.output_format,
+    audio_setting: {
+      sample_rate: options.sample_rate,
+      bitrate: options.bitrate,
+      format: options.audio_format,
+    },
+    is_instrumental: options.is_instrumental,
+  };
+
+  if (options.lyrics) {
+    request.lyrics = options.lyrics;
+  }
+
+  if (options.lyrics_optimizer) {
+    request.lyrics_optimizer = true;
+  }
+
+  return request;
+}
+
+function safeFileStem(prompt) {
+  const stem = prompt
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+
+  return stem || "minimax-music";
+}
+
+async function downloadUrl(url) {
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    throw new Error(`MiniMax audio URL download failed with HTTP ${response.status}`);
+  }
+
+  return Buffer.from(await response.arrayBuffer());
+}
+
+function decodeHexAudio(value) {
+  if (!/^[0-9a-fA-F]+$/.test(value) || value.length % 2 !== 0) {
+    throw new Error("MiniMax response audio is not valid hex data");
+  }
+
+  return Buffer.from(value, "hex");
+}
+
+async function callMiniMax(config, request) {
+  const response = await fetch(ENDPOINT, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${config.api_key}`,
+    },
+    body: JSON.stringify(request),
+  });
+
+  const text = await response.text();
+  let json;
+
+  try {
+    json = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`MiniMax returned non-JSON response with HTTP ${response.status}`);
+  }
+
+  if (!response.ok) {
+    const message = json.base_resp?.status_msg || `HTTP ${response.status}`;
+    throw new Error(`MiniMax request failed: ${message}`);
+  }
+
+  const statusCode = json.base_resp?.status_code;
+  if (statusCode !== 0) {
+    const message = json.base_resp?.status_msg || "unknown MiniMax error";
+    throw new Error(`MiniMax request failed with status_code ${statusCode}: ${message}`);
+  }
+
+  if (json.data?.status !== 2) {
+    throw new Error(`MiniMax generation is not complete; data.status is ${json.data?.status}`);
+  }
+
+  if (!json.data?.audio) {
+    throw new Error("MiniMax response did not include data.audio");
+  }
+
+  return json;
+}
+
+async function writeAudioOutput({ responseJson, request, outputDir, prompt }) {
+  await mkdir(outputDir, { recursive: true });
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const stem = `${safeFileStem(prompt)}-${timestamp}`;
+  const extension = request.audio_setting.format === "pcm" ? "pcm" : request.audio_setting.format;
+  const audioPath = join(outputDir, `${stem}.${extension}`);
+  const metadataPath = join(outputDir, `${stem}.minimax.json`);
+  const audioValue = responseJson.data.audio;
+  const audioBuffer = request.output_format === "url"
+    ? await downloadUrl(audioValue)
+    : decodeHexAudio(audioValue);
+
+  await writeFile(audioPath, audioBuffer);
+  await writeFile(
+    metadataPath,
+    `${JSON.stringify({
+      provider: "minimax",
+      endpoint: 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,
+  };
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  validateOptions(options);
+
+  const runtime = await readMinimaxRuntimeConfig({
+    skillRoot,
+    env: process.env,
+    configPath: options.config_path,
+  });
+
+  if (!runtime) {
+    throw new Error("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.");
+  }
+
+  const request = buildRequest(options, runtime.config);
+  const redactedConfig = redactMinimaxConfig(runtime.config);
+
+  if (options.dry_run) {
+    console.log(JSON.stringify({
+      ok: true,
+      dry_run: true,
+      provider: "minimax",
+      endpoint: ENDPOINT,
+      config: {
+        source: runtime.source,
+        path: runtime.configPath,
+        redacted: redactedConfig,
+      },
+      request,
+      output_dir: options.output_dir,
+    }, null, 2));
+    return;
+  }
+
+  const responseJson = await callMiniMax(runtime.config, request);
+  const output = await writeAudioOutput({
+    responseJson,
+    request,
+    outputDir: options.output_dir,
+    prompt: options.prompt,
+  });
+
+  console.log(JSON.stringify({
+    ok: true,
+    provider: "minimax",
+    model: request.model,
+    output_path: output.audioPath,
+    metadata_path: output.metadataPath,
+    beat_analysis_command: `python3 scripts/analyze_music_beats.py ${output.audioPath} -o ${join(options.output_dir, "beat-map.json")} --fps 60 --pretty`,
+  }, null, 2));
+}
+
+main().catch((error) => {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+});

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

@@ -0,0 +1,113 @@
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+export const DEFAULT_MINIMAX_MODEL = "music-2.6-free";
+export const TEXT_MUSIC_MODELS = new Set(["music-2.6", "music-2.6-free"]);
+
+async function pathExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function cleanString(value) {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function normalize(input = {}) {
+  return {
+    api_key: cleanString(input.api_key),
+    group_id: cleanString(input.group_id),
+    model: cleanString(input.model),
+  };
+}
+
+function hasValues(input = {}) {
+  return Boolean(cleanString(input.api_key) || cleanString(input.group_id) || cleanString(input.model));
+}
+
+export function redactMinimaxConfig(config = {}) {
+  const normalized = normalize(config);
+
+  return {
+    api_key: normalized.api_key ? "[redacted]" : undefined,
+    group_id: normalized.group_id,
+    model: normalized.model || DEFAULT_MINIMAX_MODEL,
+  };
+}
+
+export function validateMinimaxConfig(config = {}) {
+  const normalized = normalize(config);
+
+  if (!normalized.api_key) {
+    throw new Error("MiniMax api_key is required");
+  }
+
+  if (!normalized.group_id) {
+    throw new Error("MiniMax group_id is required");
+  }
+
+  const model = normalized.model || DEFAULT_MINIMAX_MODEL;
+
+  if (!TEXT_MUSIC_MODELS.has(model)) {
+    throw new Error(`Unsupported MiniMax text music model: ${model}. Use music-2.6 or music-2.6-free.`);
+  }
+
+  return {
+    api_key: normalized.api_key,
+    group_id: normalized.group_id,
+    model,
+  };
+}
+
+async function readJson(path) {
+  const raw = await readFile(path, "utf8");
+  const parsed = JSON.parse(raw);
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`MiniMax config file must be a JSON object: ${path}`);
+  }
+
+  return parsed;
+}
+
+export async function readMinimaxRuntimeConfig({ skillRoot, env = process.env, configPath } = {}) {
+  const explicitConfigPath = cleanString(configPath);
+  const defaultConfigPath = skillRoot ? join(skillRoot, "config", "minimax.json") : undefined;
+  const filePath = explicitConfigPath || defaultConfigPath;
+
+  if (filePath && await pathExists(filePath)) {
+    return {
+      source: "file",
+      configPath: filePath,
+      config: validateMinimaxConfig(await readJson(filePath)),
+    };
+  }
+
+  const envConfig = normalize({
+    api_key: env.MINIMAX_API_KEY,
+    group_id: env.MINIMAX_GROUP_ID,
+    model: env.MINIMAX_MODEL,
+  });
+
+  if (!hasValues(envConfig)) {
+    return null;
+  }
+
+  return {
+    source: "environment",
+    configPath: null,
+    config: validateMinimaxConfig(envConfig),
+  };
+}