npm - hyper-animator-codex - Versions diffs - 0.6.0 → 0.7.0 - Mend

hyper-animator-codex 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md +37 -3
package/package.json +1 -1
package/skills/hyper-animator-codex/SKILL.md +23 -18
package/skills/hyper-animator-codex/references/narration-audio-workflow.md +110 -0
package/skills/hyper-animator-codex/scripts/detect_project_files.mjs +178 -0
package/skills/hyper-animator-codex/scripts/generate_minimax_tts.mjs +556 -0
package/skills/hyper-animator-codex/scripts/generate_subtitles.mjs +181 -0

package/README.md CHANGED Viewed

@@ -2,7 +2,7 @@
 Install the `hyper-animator-codex` Codex skill from npm.
-The skill guides Codex through a HyperFrames animation workflow: natural-language brief, clarification questions, catalog-map intent matching, style and motion selection, HTML animation authoring, validation, user approval, and render handoff.
+The skill guides Codex through a HyperFrames animation workflow: natural-language brief, outline/narration detection, clarification questions, catalog-map intent matching, style and motion selection, HTML animation authoring, validation, user approval, and render handoff.
 ## Install
@@ -52,9 +52,9 @@ node skills/hyper-animator-codex/scripts/git_checkpoint.mjs \
 Existing Git repositories with uncommitted changes are protected: the helper stops instead of mixing user edits into automatic commits. Large video and audio files above 10 MB are skipped by default and recorded in a manifest under `hyper-animator-output/git-checkpoints/`.
-## MiniMax Music Configuration
+## MiniMax Audio 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:
+MiniMax is the preferred generated-background-music provider and the required narration TTS provider. Configure it during install so the copied Codex skill can generate music and voiceover without asking for credentials later:
 ```bash
 npx hyper-animator-codex install --force \
@@ -104,10 +104,44 @@ When rendering video, hide preview controls with any one of:
 <html data-render-mode="video">
 ```
+## Narration And Subtitles
+Detect outline and narration files in a project directory:
+```bash
+node skills/hyper-animator-codex/scripts/detect_project_files.mjs --dir . --pretty
+```
+List MiniMax voices, cloned voices first:
+```bash
+node skills/hyper-animator-codex/scripts/generate_minimax_tts.mjs --list-voices --voice-type all
+```
+Generate narration audio from `narration.json`:
+```bash
+node skills/hyper-animator-codex/scripts/generate_minimax_tts.mjs \
+  --narration-json narration.json \
+  --output-dir hyper-animator-output/voice
+```
+Generate timed subtitle JSON and SRT:
+```bash
+node skills/hyper-animator-codex/scripts/generate_subtitles.mjs \
+  --narration narration.json \
+  --output-dir hyper-animator-output/subtitles \
+  --style clean
+```
 ## 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/detect_project_files.mjs`: top-level outline and narration detector for first-run/restart workflows.
+- `skills/hyper-animator-codex/scripts/generate_minimax_tts.mjs`: MiniMax voice listing and narration TTS helper.
+- `skills/hyper-animator-codex/scripts/generate_subtitles.mjs`: timed subtitle JSON/SRT generator.
 - `skills/hyper-animator-codex/scripts/git_checkpoint.mjs`: Git initialization and stage-commit helper for `/hyper-animator` runs.
 - `skills/hyper-animator-codex/scripts/validate_hyperframes_html.py`: static pre-render HTML quality gate.

package/package.json CHANGED Viewed

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

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

@@ -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 assembly, new HyperFrames HTML, sound effects, background music, rhythm, BPM, or beat-synced transitions.
+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, outline/narration detection, voiceover, subtitles, sound effects, background music, rhythm, BPM, final mixing, or beat-synced transitions.
 ---
 # Hyper Animator Codex
@@ -12,23 +12,25 @@ Turn a natural-language animation or video brief into a validated HyperFrames HT
 ## Required Flow
 1. Read `references/git-checkpoint-workflow.md` and run `scripts/git_checkpoint.mjs --phase init --message "chore: initialize hyper animator workspace" --allow-empty` before requirement capture. If the helper reports an existing dirty repository or linked worktree, stop and ask the user to resolve it.
-2. Capture the raw request and extract an initial intent profile: purpose, format, duration, content inputs, style tags, motion tags, and needed roles.
-3. If purpose, format, or core content is unclear, ask the first clarification round before choosing catalog items.
-4. Read `references/hyperframes-catalog-map.json` and score candidates by keyword, intent domain, format, role, style, motion, and constraints.
-5. Pick candidate blocks/components for main scene, caption, effects, transitions, and outro.
-6. Decide generation mode:
+2. When starting in a new directory, restarting, or handling outline/narration/voiceover/subtitle/full-mix work, read `references/narration-audio-workflow.md` and run `scripts/detect_project_files.mjs --dir . --pretty` before visual planning.
+3. Capture the raw request and extract an initial intent profile: purpose, format, duration, content inputs, style tags, motion tags, and needed roles.
+4. If purpose, format, or core content is unclear, ask the first clarification round before choosing catalog items.
+5. Read `references/hyperframes-catalog-map.json` and score candidates by keyword, intent domain, format, role, style, motion, and constraints.
+6. Pick candidate blocks/components for main scene, caption, effects, transitions, and outro.
+7. 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.
-7. Clarify audio: ask whether to add animation/transition sound effects and whether to add background music.
-8. If background music is requested or undecided, read `references/minimax-music-workflow.md` and use `scripts/generate_minimax_music.mjs` for every MiniMax request. Do not construct MiniMax HTTP calls directly. If MiniMax is unavailable or declined, ask for a local audio path or continue without BGM.
-9. 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.
-10. 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.
-11. 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.
-12. After each file-writing stage, run `scripts/git_checkpoint.mjs` with the phase-specific allowlist from `references/git-checkpoint-workflow.md`. Do not create, switch, or recommend Git branches or worktrees.
-13. Run pre-render quality gates on the base HTML.
-14. Read `references/preview-controls-workflow.md`, run `scripts/inject_preview_controls.mjs` to create a preview HTML copy, and run `scripts/validate_hyperframes_html.py preview.html --preview-controls`.
-15. Show a concise plan summary and preview path or HTML file to the user. Ask for confirmation before video render.
-16. Render only after user confirmation. Prefer rendering the base HTML; if rendering the preview copy, use `?render=1`, `?preview=0`, or `<html data-render-mode="video">` so preview controls are hidden. Then report output path and any caveats.
+8. Clarify audio: ask whether to use narration, subtitles, animation/transition sound effects, and background music.
+9. If narration is used, use `scripts/generate_minimax_tts.mjs` for voice listing and TTS. Do not construct MiniMax TTS HTTP calls directly. If subtitles are requested, run `scripts/generate_subtitles.mjs`.
+10. If background music is requested or undecided, read `references/minimax-music-workflow.md` and use `scripts/generate_minimax_music.mjs` for every MiniMax music request. Do not construct MiniMax music HTTP calls directly. If MiniMax is unavailable or declined, ask for a local audio path or continue without BGM.
+11. 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.
+12. Ask the second clarification round with candidate context: visual direction, motion rhythm, generation mode, narration/subtitle/audio choices, music prompt/model when MiniMax is used, and beat-sync assumptions when background music is present.
+13. Write or assemble HTML. When beat-sync is enabled, align major reveals, cuts, transitions, camera moves, narration beats, subtitle cues, and visual accents to the beat map instead of arbitrary timestamps.
+14. After each file-writing stage, run `scripts/git_checkpoint.mjs` with the phase-specific allowlist from `references/git-checkpoint-workflow.md`. Do not create, switch, or recommend Git branches or worktrees.
+15. Run pre-render quality gates on the base HTML.
+16. Read `references/preview-controls-workflow.md`, run `scripts/inject_preview_controls.mjs` to create a preview HTML copy, and run `scripts/validate_hyperframes_html.py preview.html --preview-controls`.
+17. Show a concise plan summary and preview path or HTML file to the user. Ask for confirmation before video render.
+18. Render only after user confirmation. Prefer rendering the base HTML; if rendering the preview copy, use `?render=1`, `?preview=0`, or `<html data-render-mode="video">` so preview controls are hidden. Then report output path and any caveats.
 ## Interactive Questions
@@ -36,14 +38,15 @@ Prefer Codex interactive question tools such as `AskUserQuestion` or `request_us
 Use two rounds:
-- 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.
+- Round 1: purpose, format, duration, platform, required content, outline/narration status, narration/subtitles, 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, voice/emotion/subtitle style, 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.
 ## References
 - Read `references/git-checkpoint-workflow.md` before any `/hyper-animator` run writes files or initializes output.
+- Read `references/narration-audio-workflow.md` when first-run detection, restart, outline, narration, voiceover, subtitle, BGM timing, or final audio/video mixing is mentioned.
 - 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.
@@ -94,7 +97,9 @@ If the validator fails, fix the HTML before asking the user to approve render.
 Before rendering, summarize:
 - generation mode;
+- detected outline/narration paths, ambiguity status, and any outline/narration generation assumptions;
 - selected or referenced catalog items;
+- narration usage, selected voice, emotion, voice audio path, subtitle style, subtitle JSON/SRT paths, and voice/BGM/SFX volume values when applicable;
 - 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;

package/skills/hyper-animator-codex/references/narration-audio-workflow.md ADDED Viewed

@@ -0,0 +1,110 @@
+# Narration Audio Workflow
+Use this when a `/hyper-animator` run starts in a new directory, the user asks to restart, or the brief mentions outline, narration, voiceover, subtitles, BGM, beat sync, sound effects, or final audio/video mixing.
+## Start Or Restart
+Run file detection before visual planning:
+```bash
+node scripts/detect_project_files.mjs --dir . --pretty
+```
+Rules:
+- scan only the current directory top level;
+- trust fixed names first: `outline.*` and `narration.*`;
+- if multiple candidates are returned, ask the user to choose;
+- if only outline exists, ask whether to generate narration from it;
+- if only narration exists, ask whether to generate an outline from it;
+- if narration is not used, do not generate voice audio or subtitles.
+Codex writes or edits outline/narration content. Scripts only validate, convert, call MiniMax, and write artifacts.
+## Narration JSON
+Use this shape:
+```json
+{
+  "voice": "XiaoR_001",
+  "emotion": "calm",
+  "language": "zh",
+  "style": "casual",
+  "scenes": [
+    {
+      "scene": 1,
+      "title": "Scene title",
+      "sync_hint": "Visual sync hint",
+      "narration": "Spoken text",
+      "duration_estimate": 8
+    }
+  ]
+}
+```
+Before generating narration, ask language and style. Default language is `zh`.
+## MiniMax Voice
+Do not hand-write MiniMax TTS HTTP calls. Use:
+```bash
+node scripts/generate_minimax_tts.mjs --list-voices --voice-type all
+```
+Prefer cloned voices, then generated voices, then system voices. Recommend three candidates by content tone and ask the user to choose. If listing fails, continue with `XiaoR_001` after telling the user.
+Emotion labels:
+```text
+happy, sad, angry, fearful, disgusted, surprised, calm, fluent, whipser
+```
+Generate narration audio:
+```bash
+node scripts/generate_minimax_tts.mjs \
+  --narration-json narration.json \
+  --output-dir hyper-animator-output/voice
+```
+Use `--dry-run` before a real call when checking request shape or credentials.
+## Subtitles
+Generate subtitles only when narration is used and the user wants subtitles:
+```bash
+node scripts/generate_subtitles.mjs \
+  --narration narration.json \
+  --output-dir hyper-animator-output/subtitles \
+  --style clean
+```
+Subtitle rules:
+- short phrase cues;
+- no trailing punctuation;
+- one visible cue at a time;
+- JSON and SRT outputs include timecodes.
+## BGM, Beat, And Schedule
+BGM is the timing source when present:
+1. decide BGM generation, local import, or skip;
+2. if configured, generate BGM with `scripts/generate_minimax_music.mjs`;
+3. analyze the music with `scripts/analyze_music_beats.py`;
+4. schedule transitions, animation, narration, and subtitles against the beat map;
+5. generate HTML;
+6. preview and get user confirmation;
+7. render and mix final video/audio.
+Default mix:
+- voice: `1.0`;
+- BGM: `0.3`;
+- SFX: `0.3`.
+If the user gives volume commands, adjust `voice`, `bgm`, and `sfx` independently in the final mix command or render handoff.

package/skills/hyper-animator-codex/scripts/detect_project_files.mjs ADDED Viewed

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+import { readdir, readFile, stat } from "node:fs/promises";
+import { resolve, join } from "node:path";
+const OUTLINE_NAMES = new Set(["outline.md", "outline.json", "outline.txt"]);
+const NARRATION_NAMES = new Set(["narration.json", "narration.md", "narration.txt"]);
+const TEXT_EXTENSIONS = new Set([".md", ".txt"]);
+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 = { dir: process.cwd(), pretty: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--dir") {
+      parsed.dir = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--pretty") {
+      parsed.pretty = true;
+    } else if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+  return parsed;
+}
+function extensionOf(name) {
+  const dot = name.lastIndexOf(".");
+  return dot === -1 ? "" : name.slice(dot).toLowerCase();
+}
+async function readTopLevelFiles(root) {
+  const entries = await readdir(root, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => ({
+      name: entry.name,
+      lowerName: entry.name.toLowerCase(),
+      path: join(root, entry.name),
+      extension: extensionOf(entry.name),
+    }));
+}
+async function classifyJson(file) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(file.path, "utf8"));
+  } catch {
+    return null;
+  }
+  if (parsed && typeof parsed === "object" && Array.isArray(parsed.scenes)) {
+    const hasNarration = parsed.scenes.some((scene) => typeof scene?.narration === "string" && scene.narration.trim());
+    if (hasNarration) {
+      return { type: "narration", reason: "json-scenes-narration" };
+    }
+  }
+  return null;
+}
+async function classifyText(file) {
+  if (!TEXT_EXTENSIONS.has(file.extension)) {
+    return null;
+  }
+  const text = await readFile(file.path, "utf8");
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  const outlineLines = lines.filter((line) => /^#{1,4}\s+\S/.test(line) || /^[-*]\s+\S/.test(line) || /^\d+[.)]\s+\S/.test(line));
+  if (outlineLines.length >= 2 || (lines.length >= 3 && outlineLines.length >= 1)) {
+    return { type: "outline", reason: "outline-text-structure" };
+  }
+  return null;
+}
+function pickSingle(candidates) {
+  return candidates.length === 1 ? candidates[0] : null;
+}
+async function detectProjectFiles(rootDir) {
+  const root = resolve(rootDir);
+  const rootStat = await stat(root);
+  if (!rootStat.isDirectory()) {
+    throw new Error(`--dir must be a directory: ${root}`);
+  }
+  const files = await readTopLevelFiles(root);
+  const fixedOutlines = files
+    .filter((file) => OUTLINE_NAMES.has(file.lowerName))
+    .map((file) => ({ path: file.path, name: file.name, reason: "fixed-name" }));
+  const fixedNarrations = files
+    .filter((file) => NARRATION_NAMES.has(file.lowerName))
+    .map((file) => ({ path: file.path, name: file.name, reason: "fixed-name" }));
+  const candidates = {
+    outline: [...fixedOutlines],
+    narration: [...fixedNarrations],
+  };
+  if (fixedOutlines.length === 0 || fixedNarrations.length === 0) {
+    for (const file of files) {
+      if (OUTLINE_NAMES.has(file.lowerName) || NARRATION_NAMES.has(file.lowerName)) {
+        continue;
+      }
+      const classification = file.extension === ".json"
+        ? await classifyJson(file)
+        : await classifyText(file);
+      if (!classification) {
+        continue;
+      }
+      if (classification.type === "outline" && fixedOutlines.length === 0) {
+        candidates.outline.push({ path: file.path, name: file.name, reason: classification.reason });
+      } else if (classification.type === "narration" && fixedNarrations.length === 0) {
+        candidates.narration.push({ path: file.path, name: file.name, reason: classification.reason });
+      }
+    }
+  }
+  const outline = pickSingle(candidates.outline);
+  const narration = pickSingle(candidates.narration);
+  return {
+    ok: true,
+    root,
+    outline,
+    narration,
+    candidates,
+    ambiguous: candidates.outline.length > 1 || candidates.narration.length > 1,
+  };
+}
+function printHelp() {
+  console.log(`Usage:
+  node scripts/detect_project_files.mjs [--dir <path>] [--pretty]
+Options:
+  --dir <path>   Project directory to scan, default cwd
+  --pretty       Pretty-print JSON output
+`);
+}
+async function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+      printHelp();
+      return;
+    }
+    const result = await detectProjectFiles(options.dir);
+    console.log(JSON.stringify(result, null, options.pretty ? 2 : 0));
+  } catch (error) {
+    console.log(JSON.stringify({
+      ok: false,
+      error: {
+        message: error.message,
+      },
+    }, null, 2));
+    process.exitCode = 1;
+  }
+}
+main();

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

@@ -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();

package/skills/hyper-animator-codex/scripts/generate_subtitles.mjs ADDED Viewed

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+const TRAILING_PUNCTUATION = /[，。！？；：,.!?;:、]+$/u;
+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 = {
+    narration: undefined,
+    output_dir: join(process.cwd(), "hyper-animator-output", "subtitles"),
+    style: "default",
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--narration") {
+      parsed.narration = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--output-dir") {
+      parsed.output_dir = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--style") {
+      parsed.style = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+  return parsed;
+}
+function validateNarration(narration) {
+  if (!narration || typeof narration !== "object" || !Array.isArray(narration.scenes)) {
+    throw new Error("narration JSON must include scenes[]");
+  }
+  narration.scenes.forEach((scene, index) => {
+    if (typeof scene?.narration !== "string" || !scene.narration.trim()) {
+      throw new Error(`scenes[${index}].narration is required`);
+    }
+    if (scene.duration_estimate !== undefined && (!Number.isFinite(Number(scene.duration_estimate)) || Number(scene.duration_estimate) <= 0)) {
+      throw new Error(`scenes[${index}].duration_estimate must be a positive number`);
+    }
+  });
+}
+function cleanCueText(text) {
+  return text.trim().replace(TRAILING_PUNCTUATION, "").trim();
+}
+function splitNarration(text) {
+  return text
+    .split(/[\r\n]+|(?<=[，。！？；：,.!?;:、])/u)
+    .map(cleanCueText)
+    .filter(Boolean);
+}
+function roundTime(value) {
+  return Number(value.toFixed(3));
+}
+function buildCues(narration) {
+  const cues = [];
+  let cursor = 0;
+  narration.scenes.forEach((scene, sceneIndex) => {
+    const parts = splitNarration(scene.narration);
+    const duration = Number(scene.duration_estimate) || Math.max(parts.length * 2, 2);
+    const cueDuration = duration / Math.max(parts.length, 1);
+    parts.forEach((text) => {
+      const start = cursor;
+      const end = cursor + cueDuration;
+      cues.push({
+        index: cues.length + 1,
+        scene: scene.scene ?? sceneIndex + 1,
+        start: roundTime(start),
+        end: roundTime(end),
+        text,
+      });
+      cursor = end;
+    });
+  });
+  return cues;
+}
+function formatSrtTime(seconds) {
+  const totalMs = Math.round(seconds * 1000);
+  const ms = totalMs % 1000;
+  const totalSeconds = Math.floor(totalMs / 1000);
+  const sec = totalSeconds % 60;
+  const totalMinutes = Math.floor(totalSeconds / 60);
+  const min = totalMinutes % 60;
+  const hour = Math.floor(totalMinutes / 60);
+  return `${String(hour).padStart(2, "0")}:${String(min).padStart(2, "0")}:${String(sec).padStart(2, "0")},${String(ms).padStart(3, "0")}`;
+}
+function renderSrt(cues) {
+  return `${cues.map((cue) => [
+    cue.index,
+    `${formatSrtTime(cue.start)} --> ${formatSrtTime(cue.end)}`,
+    cue.text,
+  ].join("\n")).join("\n\n")}\n`;
+}
+async function generateSubtitles(options) {
+  if (!options.narration) {
+    throw new Error("--narration is required");
+  }
+  const narration = JSON.parse(await readFile(options.narration, "utf8"));
+  validateNarration(narration);
+  const cues = buildCues(narration);
+  await mkdir(options.output_dir, { recursive: true });
+  const jsonPath = join(options.output_dir, "subtitles.json");
+  const srtPath = join(options.output_dir, "subtitles.srt");
+  const payload = {
+    ok: true,
+    style: options.style,
+    source: options.narration,
+    cues,
+  };
+  await writeFile(jsonPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  await writeFile(srtPath, renderSrt(cues), "utf8");
+  return {
+    ...payload,
+    json_path: jsonPath,
+    srt_path: srtPath,
+  };
+}
+function printHelp() {
+  console.log(`Usage:
+  node scripts/generate_subtitles.mjs --narration <file> [options]
+Options:
+  --narration <file>    Narration JSON file
+  --output-dir <dir>    Output directory, default hyper-animator-output/subtitles
+  --style <name>        Subtitle style label for downstream HTML/render steps
+`);
+}
+async function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+      printHelp();
+      return;
+    }
+    console.log(JSON.stringify(await generateSubtitles(options), null, 2));
+  } catch (error) {
+    console.log(JSON.stringify({
+      ok: false,
+      error: {
+        message: error.message,
+      },
+    }, null, 2));
+    process.exitCode = 1;
+  }
+}
+main();