hyper-animator-codex 0.1.0 → 0.3.0

package/README.md

@@ -37,12 +37,71 @@ 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.
 - `skills/hyper-animator-codex/references/`: HyperFrames catalog map, workflow guide, pseudocode, and request examples.
 - `skills/hyper-animator-codex/scripts/validate_hyperframes_html.py`: static pre-render HTML quality gate.
 
+## Optional Beat Detection
+
+The skill can analyze background music and guide Codex to align HyperFrames/GSAP transitions to beats, bars, energy peaks, and detected music segments.
+
+Install optional Python dependencies:
+
+```bash
+python3 -m pip install librosa pydub numpy click
+```
+
+Analyze WAV/FLAC/OGG without ffmpeg. MP3/M4A/AAC/WMA require system `ffmpeg`.
+
+Run the bundled analyzer from an installed skill directory or repository checkout:
+
+```bash
+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.1.0",
+  "version": "0.3.0",
   "description": "Install the Hyper Animator Codex skill for Codex.",
   "type": "module",
   "bin": {

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

@@ -1,6 +1,6 @@
 ---
 name: hyper-animator-codex
-description: Use when a user asks Codex to create, plan, author, customize, validate, preview, or render a HyperFrames, HTML, or GSAP animation/video from natural-language requirements, including product demos, code demos, data videos, podcast captions, social shorts, catalog block/component assembly, or new HyperFrames HTML.
+description: Use when a user asks Codex to create, plan, author, customize, validate, preview, or render a HyperFrames, HTML, or GSAP animation/video from natural-language requirements, including product demos, code demos, data videos, podcast captions, social shorts, catalog assembly, new HyperFrames HTML, sound effects, background music, rhythm, BPM, or beat-synced transitions.
 ---
 
 # Hyper Animator Codex
@@ -18,11 +18,14 @@ Turn a natural-language animation or video brief into a validated HyperFrames HT
 5. Decide generation mode:
    - `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. Ask the second clarification round with candidate context: visual direction, motion rhythm, generation mode, and any candidate tradeoffs.
-7. Write or assemble HTML.
-8. Run pre-render quality gates.
-9. Show a concise plan summary and preview path or HTML file to the user. Ask for confirmation before video render.
-10. Render only after user confirmation, then report output path and any caveats.
+6. Clarify audio: ask whether to add animation/transition sound effects and whether to add background music.
+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
 
@@ -30,8 +33,8 @@ Prefer Codex interactive question tools such as `AskUserQuestion` or `request_us
 
 Use two rounds:
 
-- Round 1: purpose, format, duration, platform, required content, brand assets, and whether video render is expected in this turn.
-- Round 2: after catalog scoring, ask about style, motion, candidate selection, and generation mode.
+- Round 1: purpose, format, duration, platform, required content, brand assets, sound effects, background music, and whether video render is expected in this turn.
+- Round 2: after catalog scoring, ask about style, motion, candidate selection, generation mode, and beat-sync assumptions when background music is present.
 
 Do not ask everything upfront when the brief is already specific. Ask only for missing or decision-changing information.
 
@@ -40,6 +43,8 @@ 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.
 
 ## Catalog Rules
@@ -79,6 +84,9 @@ 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;
 - preview location;

package/skills/hyper-animator-codex/references/beat-sync-workflow.md

@@ -0,0 +1,51 @@
+# Beat Sync Workflow
+
+Use this when the user mentions sound effects, background music, soundtrack, beat sync, rhythm, BPM, transitions to music, or audio-reactive animation.
+
+## Clarify Audio
+
+Ask:
+
+- Should animation or transition sound effects be added?
+- Should background music be added?
+- If background music is used, what is the local audio path?
+- May scene timing, transition timing, and animation accents be adjusted to match the music?
+- Should the music be trimmed, looped, or should video duration follow the selected music region?
+
+## Analyze Music
+
+When a background music file is provided:
+
+```bash
+python3 scripts/analyze_music_beats.py path/to/music.wav -o path/to/beat-map.json --fps 60 --pretty
+```
+
+If dependencies are missing, tell the user:
+
+```bash
+python3 -m pip install librosa pydub numpy click
+```
+
+MP3/M4A/AAC/WMA require system `ffmpeg`; WAV/FLAC/OGG are safer.
+
+## Map Beats To Animation
+
+- Use `meta.bpm` for global pacing.
+- Use beats with `beat_in_bar: 1` for major scene changes, title reveals, camera moves, and transitions.
+- Use `energy_level: strong` for visual accents, scale pulses, light sweeps, flashes, or cut emphasis.
+- Use weak beats for secondary motion only.
+- Use `structure.segments` to shape intro, main body, and outro.
+- Use `structure.energy_peaks` for high-impact moments.
+- Keep `data-duration` consistent with the selected music region or state trim/loop assumptions.
+
+## GSAP Timing
+
+Convert beat times from milliseconds to seconds:
+
+```js
+const beatSeconds = beatMap.beats.map((beat) => beat.time_ms / 1000);
+tl.addLabel("downbeat_1", beatSeconds[0]);
+tl.to(".hero", { opacity: 1, y: 0, duration: 0.35 }, "downbeat_1");
+```
+
+Do not use wall-clock audio playback to drive render progress. The render timeline remains a paused GSAP timeline registered in `window.__timelines`.

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/analyze_music_beats.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.dont_write_bytecode = True
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+VENDOR_ROOT = SCRIPT_DIR.parent / "vendor" / "music-beat-detector"
+sys.path.insert(0, str(VENDOR_ROOT))
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Analyze background music and write a beat map JSON for HyperFrames timing."
+    )
+    parser.add_argument("audio_file", help="Path to WAV, FLAC, OGG, MP3, M4A, AAC, or WMA audio")
+    parser.add_argument("-o", "--output", help="Output JSON path. Prints JSON to stdout when omitted.")
+    parser.add_argument("--fps", type=int, default=60, help="Timeline frame rate for frame indexes. Default: 60")
+    parser.add_argument("--pretty", action="store_true", help="Pretty-print JSON")
+    parser.add_argument(
+        "--log-level",
+        default="error",
+        choices=["debug", "info", "warning", "error"],
+        help="Detector log level",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    audio_path = Path(args.audio_file)
+    if not audio_path.exists():
+        print(f"Error: audio file does not exist: {audio_path}", file=sys.stderr)
+        return 1
+
+    try:
+        from beat_detector import analyze
+        from beat_detector.errors import BeatDetectorError, FFmpegRequiredError
+    except ModuleNotFoundError as exc:
+        print(
+            "Error: missing Python dependency for beat detection. "
+            "Install optional dependencies with: python3 -m pip install librosa pydub numpy click",
+            file=sys.stderr,
+        )
+        print(f"Missing module: {exc.name}", file=sys.stderr)
+        return 10
+
+    try:
+        result = analyze(str(audio_path), fps=args.fps, log_level=args.log_level)
+        if args.output:
+            result.save(args.output, pretty=args.pretty)
+            print(f"Beat map saved to: {args.output}")
+        else:
+            print(result.to_json(pretty=args.pretty))
+        return 0
+    except FFmpegRequiredError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        print("Install ffmpeg or use WAV/FLAC/OGG audio for fewer runtime dependencies.", file=sys.stderr)
+        return 4
+    except BeatDetectorError as exc:
+        message = getattr(exc, "message", str(exc))
+        print(f"Error: {message}", file=sys.stderr)
+        return 3
+    except ModuleNotFoundError as exc:
+        print(
+            "Error: missing Python dependency for beat detection. "
+            "Install optional dependencies with: python3 -m pip install librosa pydub numpy click",
+            file=sys.stderr,
+        )
+        print(f"Missing module: {exc.name}", file=sys.stderr)
+        return 10
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())