hyper-animator-codex 0.8.0 → 0.8.3

package/skills/hyper-animator-codex/contracts/workflow-policy.json

@@ -5,6 +5,7 @@
     "generated_narration": {
       "provider": "minimax_cn",
       "endpoint": "https://api.minimaxi.com/v1/t2a_v2",
+      "stage_after": "visual_confirmation",
       "backup_endpoints": [
         "https://api-bj.minimaxi.com/v1/t2a_v2"
       ],
@@ -26,10 +27,14 @@
     ],
     "forbidden_commands": [
       "hyperframes auth login",
-      "hyperframes tts"
+      "hyperframes tts",
+      "python3 -m pip install librosa",
+      "pip3 install librosa",
+      "pip install librosa"
     ],
     "automatic_fallback": false,
     "automatic_runtime_install": false,
+    "automatic_dependency_install": false,
     "failure_choices": [
       "retry_minimax_cn",
       "use_user_local_file",
@@ -42,14 +47,20 @@
   },
   "model_routing": {
     "page_animation_authoring": {
-      "model": "gpt-5.6-sol",
+      "tier": "high_quality",
+      "preferred_models": {
+        "codex": "gpt-5.6-sol"
+      },
       "use_for": [
         "page_generation",
         "animation_authoring"
       ]
     },
     "planning_and_validation": {
-      "model": "gpt-5.6-terra",
+      "tier": "fast",
+      "preferred_models": {
+        "codex": "gpt-5.6-terra"
+      },
       "use_for": [
         "requirements",
         "file_detection",
@@ -69,6 +80,13 @@
     "default_statuses": [
       "implemented"
     ],
+    "motion_pack_path": "references/shotcraft/motion-pack/README.md",
+    "motion_pack_snippet": "references/shotcraft/motion-pack/shotcraft-motion-pack.js",
+    "prefer_motion_pack_before_freehand": true,
+    "motion_pack_required_for_supported_refs": true,
+    "motion_contract_required": true,
+    "minimum_commitments_per_shot": 1,
+    "read_selected_cards_before_html": true,
     "excluded_asset_extensions": [
       ".mp4",
       ".mov",

package/skills/hyper-animator-codex/references/examples/shot-plan-dual-catalog.json

@@ -1,5 +1,6 @@
 {
-  "schema_version": "1.0.0",
+  "schema_version": "1.1.0",
+  "workflow_stage": "visual_draft",
   "generation_mode": "generate_new_hyperframes_html",
   "catalog_strategy": "dual_catalog",
   "dimensions": {
@@ -9,8 +10,7 @@
   "duration_seconds": 12,
   "audio": {
     "narration": {
-      "mode": "generated",
-      "provider": "minimax_cn"
+      "mode": "deferred"
     },
     "bgm": {
       "mode": "generated",
@@ -18,8 +18,14 @@
     }
   },
   "model_routing": {
-    "page_animation_authoring": "gpt-5.6-sol",
-    "planning_and_validation": "gpt-5.6-terra"
+    "page_animation_authoring": {
+      "tier": "high_quality",
+      "actual_model": "gpt-5.6-sol"
+    },
+    "planning_and_validation": {
+      "tier": "fast",
+      "actual_model": "gpt-5.6-terra"
+    }
   },
   "shots": [
     {
@@ -33,6 +39,16 @@
       "shotcraft_refs": [
         "scene-locked-title"
       ],
+      "motion_contract": {
+        "motion_preset": "none",
+        "energy": "cinematic",
+        "camera": "slow crane rise from a title detail to the full product stage",
+        "transition": "full-frame light wipe into the proof shot",
+        "shotcraft_commitments": [
+          "keep the title locked and readable before the camera travel opens the scene"
+        ],
+        "readable_rest_seconds": 0.6
+      },
       "narration_scene": "1"
     },
     {
@@ -46,6 +62,16 @@
       "shotcraft_refs": [
         "ai-stream-response"
       ],
+      "motion_contract": {
+        "motion_preset": "none",
+        "energy": "high",
+        "camera": "locked readable screen with short punch-ins on key rows",
+        "transition": "snap to the final proof state on a clear beat",
+        "shotcraft_commitments": [
+          "stream response rows progressively instead of fading static copy"
+        ],
+        "readable_rest_seconds": 0.5
+      },
       "narration_scene": "2"
     },
     {
@@ -59,6 +85,16 @@
       "shotcraft_refs": [
         "ui-strip-away-outro"
       ],
+      "motion_contract": {
+        "motion_preset": "none",
+        "energy": "cinematic",
+        "camera": "wide resolve with a final centered brand hold",
+        "transition": "strip away interface fragments into the outro mark",
+        "shotcraft_commitments": [
+          "resolve dense motion into a clean brand hold for at least one second"
+        ],
+        "readable_rest_seconds": 1
+      },
       "narration_scene": "3"
     }
   ],

package/skills/hyper-animator-codex/references/hyperframes-intent-workflow.md

@@ -19,23 +19,28 @@
    Transition、可选 Outro，以及每个镜头的 ShotCraft 参考。
 6. 判断 generation mode：组装现有 catalog，还是生成新 HTML。
 7. 调用 `AskUserQuestion` 第二轮澄清样式、动效、候选取舍，以及 generation mode。
-8. 若选择 `assemble_existing_catalog_items`，生成 wrapper composition，并解析 component paste 指令为真实 snippet。
-9. 若选择 `generate_new_hyperframes_html`，按
+8. 写出 `workflow_stage: visual_draft` 的 shot plan。每个镜头必须包含
+   `motion_contract.motion_preset` 和 `motion_contract.shotcraft_commitments`，
+   把 ShotCraft 卡片的镜头、转场、节奏和避坑要求变成可验证条目。若最终需要
+   旁白，此阶段使用 `audio.narration.mode: deferred`。
+9. 运行 `scripts/validate_shot_plan.mjs shot-plan.json`。
+10. 若选择 `assemble_existing_catalog_items`，生成 wrapper composition，并解析 component paste 指令为真实 snippet。
+11. 若选择 `generate_new_hyperframes_html`，按
    `references/HyperFrames-AI-Generation-Patterns-codex.md` 生成完整
    block/component HTML；ShotCraft TSX 只作为动效参考，不引入 Remotion
    运行时。
-10. 按 `contracts/shot-plan.schema.json` 写出镜头计划，并运行
-    `scripts/validate_shot_plan.mjs shot-plan.json`。
-11. 运行 pre-render quality gates。
-12. 展示方案摘要和 HTML preview，让用户验证/确认。
-13. 根据反馈修订。
-14. 渲染视频。
+12. 运行 pre-render quality gates。
+13. 展示方案摘要和 HTML preview，让用户确认页面、转场和动画。
+14. 视觉确认后再生成旁白、字幕并按实际时长更新 shot plan。
+15. 根据反馈修订。
+16. 渲染视频。
 
 ## Intent Profile
 
 ```json
 {
   "rawRequest": "",
+  "workflowStage": "visual_draft",
   "purpose": "product_launch",
   "format": "landscape_16_9",
   "generationMode": "generate_new_hyperframes_html",
@@ -136,6 +141,8 @@ score =
 }
 ```
 
+Round 2 不选择 voice/emotion，也不生成字幕。旁白选择放到视觉确认后。
+
 ## HTML Generation Plan
 
 生成 HTML 前输出 plan：
@@ -149,6 +156,7 @@ score =
     {"id": "logo-outro", "role": "outro_reference"}
   ],
   "patternsRequired": true,
+  "audio": {"narration": {"mode": "deferred"}},
   "assumptions": ["用户未提供 logo，先使用文字 logo 占位"],
   "nextValidation": "请确认风格、文案、时长和画幅。"
 }
@@ -176,9 +184,11 @@ score =
 
 ## Model Routing
 
-- `gpt-5.6-sol` 仅用于页面生成和动画编写。
+- 页面生成和动画编写使用当前客户端的 `high_quality` 层级模型；
+  Codex 优先 `gpt-5.6-sol`。
 - 需求抽取、文件检测、catalog 查询、镜头计划、音频提示词、校验和打包
-  使用 `gpt-5.6-terra` 或同级快速经济模型。
+  使用当前客户端的 `fast` 层级模型；Codex 优先 `gpt-5.6-terra`。
+- 在 shot plan 中记录层级和实际模型名；Claude Code 不要伪填 GPT 型号。
 - 不为模型路由自动新增 Agent 或其他实体；在运行环境支持模型选择时才
   应用路由。
 

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

@@ -26,17 +26,15 @@ The installed config shape is:
 ```json
 {
   "api_key": "[redacted]",
-  "group_id": "group_id",
-  "model": "music-2.6-free"
+  "model": "music-3.0"
 }
 ```
 
-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.
+Do not print or echo the raw API key. `group_id` is optional legacy account
+metadata and is not required by the current `/v1/music_generation` call.
 
-The wrapper accepts `music-3.0`, `music-2.6`, and `music-2.6-free`. The stable
-installer default remains `music-2.6` for backward compatibility; choose
-`music-3.0` explicitly when the account has access and the user wants the
-current model.
+The wrapper accepts `music-3.0`, `music-3.0-free`, `music-2.6`, and
+`music-2.6-free`. The installer default is `music-3.0`.
 
 ## Clarify Music
 

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

@@ -15,19 +15,23 @@ 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 only outline exists, record narration as deferred until visual approval;
+- if only narration exists, use it as content context but do not generate audio or subtitles yet;
 - 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.
+The coding agent writes or edits outline/narration content. Scripts only validate, convert, call MiniMax, and write artifacts.
+
+Narration is a post-visual-confirmation stage. Do not generate MiniMax TTS,
+voice lists, or subtitles until the user has approved the page, transition,
+and animation direction. A visual draft shot plan should use
+`audio.narration.mode: "deferred"` when narration is requested.
 
 ## Provider Boundary
 
 Generated narration and BGM use MiniMax mainland China (`minimax_cn`) only.
 Never run `hyperframes auth login` or `hyperframes tts`; never invoke HeyGen,
-Kokoro, or MusicGen; and never install a fallback runtime/model. Kokoro is a
-local open-weight TTS engine, but it is outside this product contract and is
-not needed.
+Kokoro, or MusicGen; and never install a fallback runtime/model or beat
+analysis dependency during a run. Do not add a Kokoro runtime or component.
 
 Before a generated-audio call, validate the route:
 
@@ -48,7 +52,7 @@ Use this shape:
 
 ```json
 {
-  "voice": "XiaoR_001",
+  "voice": "male-qn-qingse",
   "emotion": "calm",
   "language": "zh",
   "style": "casual",
@@ -121,15 +125,17 @@ Subtitle rules:
 
 ## BGM, Beat, And Schedule
 
-BGM is the timing source when present:
+BGM is the timing source when present, but narration still waits for visual
+approval:
 
 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.
+2. if BGM is needed for beat-sync, generate BGM with `scripts/generate_minimax_music.mjs`;
+3. analyze the music with `scripts/analyze_music_beats.py` only when its dependencies are already available;
+4. if beat analysis dependencies are missing, do not run `pip install`; ask for a beat map, continue with explicit manual cues, or skip beat sync;
+5. schedule transitions and animation against the beat map or manual cues;
+6. generate the visual HTML preview and get page/transition/animation confirmation;
+7. generate narration and subtitles, then reconcile timing;
+8. render and mix final video/audio after final approval.
 
 Default mix:
 

package/skills/hyper-animator-codex/references/preview-controls-workflow.md

@@ -4,7 +4,7 @@ Use this whenever a generated or assembled HyperFrames HTML animation will be sh
 
 ## Required Behavior
 
-HTML previews should include a bottom page indicator and thin progress bar. Users can drag the progress bar to seek, or press ArrowLeft and ArrowRight to move between pages.
+HTML previews should include a bottom page indicator, play/pause button, and thin progress bar. The preview copy must start the registered timeline in interactive mode; users can pause/resume, drag the progress bar to seek, or press ArrowLeft and ArrowRight to move between pages. Never show the paused base composition as the interactive preview.
 
 Video renders must hide those controls. Use one of these render-hidden signals:
 
@@ -12,6 +12,8 @@ Video renders must hide those controls. Use one of these render-hidden signals:
 - `?preview=0`
 - `<html data-render-mode="video">`
 
+The main render timeline should remain `paused: true` for deterministic frame capture. Preview controls are responsible for calling `timeline.play()`/`timeline.pause()` and must skip autoplay when any render-hidden signal is active.
+
 ## Page Model
 
 Prefer explicit page starts:
@@ -34,7 +36,7 @@ After the base HTML passes normal quality gates, create a preview copy:
 
 ```bash
 node scripts/inject_preview_controls.mjs composition.html -o composition.preview.html --force
-python3 scripts/validate_hyperframes_html.py composition.preview.html --preview-controls
+python3 scripts/validate_hyperframes_html.py composition.preview.html --preview-controls --shot-plan shot-plan.json
 ```
 
 Show the preview copy to the user for validation.

package/skills/hyper-animator-codex/references/shotcraft/motion-pack/README.md

@@ -0,0 +1,32 @@
+# ShotCraft motion pack
+
+Use this pack before freehanding animation for the supported ShotCraft cards.
+The goal is to copy the card's actual motion grammar into GSAP/HyperFrames
+instead of merely describing it in prose.
+
+| ShotCraft reference | `motion_contract.motion_preset` | Helper |
+| --- | --- | --- |
+| `slam-entrance-moves` | `slam-entrance` | `slamEntrance` |
+| `shot-transitions` | `whip-transition` | `whipTransition` |
+| `crash-zoom-punch` | `crash-zoom` | `crashZoom` |
+| `bottom-push-stack-wipe` | `push-stack-wipe` | `pushStackWipe` |
+| `dataviz-landscape-open` | `dataviz-landscape-open` | `datavizLandscapeOpen` |
+| `panel-grid-moves` | `panel-grid-reflow` | `panelGridReflow` |
+| `ui-to-brand-morph` | `brand-resolve` | `brandResolve` |
+
+Usage:
+
+1. Read the selected ShotCraft card README first.
+2. Set the matching `motion_contract.motion_preset` in the shot plan.
+3. Copy only the needed helper from `shotcraft-motion-pack.js` into the
+   generated HTML, or include the file as a local reference when the project
+   allows that.
+4. Keep the helper on the main paused GSAP timeline; do not run wall-clock
+   timers, React, Remotion, or ShotCraft runtime code.
+
+Quality bar:
+
+- motion starts with a visible camera/geometry event, not a fade;
+- transition covers the cut with a real mask, whip, impact, or spatial travel;
+- dense motion resolves into at least `readable_rest_seconds` of rest;
+- every helper call is tied to a named shot boundary or beat cue.

package/skills/hyper-animator-codex/references/shotcraft/motion-pack/shotcraft-motion-pack.js

@@ -0,0 +1,178 @@
+// Copy the needed helpers into a generated HyperFrames HTML file.
+// Requires GSAP and a paused main timeline.
+(function registerShotCraftMotion(global) {
+  function gsapRef() {
+    if (!global.gsap) throw new Error("GSAP is required for ShotCraft motion helpers");
+    return global.gsap;
+  }
+
+  function slamEntrance(tl, target, cue = 0, opts = {}) {
+    const gsap = gsapRef();
+    const duration = opts.duration ?? 0.72;
+    tl.set(target, { transformPerspective: 900, transformOrigin: "50% 55%" }, cue)
+      .fromTo(target, {
+        autoAlpha: 0,
+        scale: 2.4,
+        z: 420,
+        rotateX: -18,
+        filter: "blur(14px) brightness(1.8)",
+      }, {
+        autoAlpha: 1,
+        scale: 0.92,
+        z: 0,
+        rotateX: 0,
+        filter: "blur(0px) brightness(1)",
+        duration: duration * 0.58,
+        ease: "expo.out",
+      }, cue)
+      .to(target, { scale: 1.04, duration: duration * 0.16, ease: "power2.out" }, cue + duration * 0.42)
+      .to(target, { scale: 1, duration: duration * 0.26, ease: "back.out(2.4)" }, cue + duration * 0.56);
+    if (opts.ring) {
+      tl.fromTo(opts.ring, { autoAlpha: 0.9, scale: 0.12 }, {
+        autoAlpha: 0,
+        scale: 2.8,
+        duration: duration * 0.72,
+        ease: "expo.out",
+      }, cue + 0.04);
+    }
+    return tl;
+  }
+
+  function whipTransition(tl, fromTarget, toTarget, cue = 0, opts = {}) {
+    const distance = opts.distance ?? 260;
+    const blur = opts.blur ?? 18;
+    tl.to(fromTarget, {
+      x: -distance,
+      rotateZ: -3,
+      filter: `blur(${blur}px)`,
+      autoAlpha: 0,
+      duration: 0.2,
+      ease: "power4.in",
+    }, cue)
+      .fromTo(toTarget, {
+        x: distance,
+        rotateZ: 3,
+        filter: `blur(${blur}px)`,
+        autoAlpha: 0,
+      }, {
+        x: 0,
+        rotateZ: 0,
+        filter: "blur(0px)",
+        autoAlpha: 1,
+        duration: 0.34,
+        ease: "expo.out",
+      }, cue + 0.16);
+    if (opts.flash) tl.fromTo(opts.flash, { autoAlpha: 0 }, { autoAlpha: 1, yoyo: true, repeat: 1, duration: 0.05 }, cue + 0.14);
+    return tl;
+  }
+
+  function crashZoom(tl, target, cue = 0, opts = {}) {
+    tl.fromTo(target, {
+      scale: opts.fromScale ?? 0.72,
+      filter: "contrast(1.3) saturate(1.25)",
+    }, {
+      scale: opts.overshoot ?? 1.18,
+      duration: 0.16,
+      ease: "power4.in",
+    }, cue)
+      .to(target, { scale: 0.98, duration: 0.12, ease: "power2.out" }, cue + 0.16)
+      .to(target, { scale: 1, filter: "contrast(1) saturate(1)", duration: 0.28, ease: "expo.out" }, cue + 0.28);
+    if (opts.shock) tl.fromTo(opts.shock, { autoAlpha: 0.85, scale: 0.2 }, { autoAlpha: 0, scale: 2.2, duration: 0.34, ease: "expo.out" }, cue + 0.12);
+    return tl;
+  }
+
+  function pushStackWipe(tl, fromTarget, toTarget, cue = 0, opts = {}) {
+    const height = opts.height ?? "112%";
+    tl.fromTo(toTarget, { y: height, autoAlpha: 1 }, {
+      y: "0%",
+      duration: 0.48,
+      ease: "power3.inOut",
+    }, cue)
+      .to(fromTarget, {
+        y: "-18%",
+        scale: 0.94,
+        filter: "blur(8px)",
+        autoAlpha: 0,
+        duration: 0.42,
+        ease: "power3.inOut",
+      }, cue + 0.04)
+      .fromTo(opts.shadow ?? toTarget, { boxShadow: "0 -40px 80px rgba(0,0,0,0.35)" }, {
+        boxShadow: "0 0 0 rgba(0,0,0,0)",
+        duration: 0.36,
+        ease: "power2.out",
+      }, cue + 0.28);
+    return tl;
+  }
+
+  function datavizLandscapeOpen(tl, bars, labels, cue = 0, opts = {}) {
+    tl.fromTo(bars, {
+      scaleY: 0,
+      transformOrigin: "50% 100%",
+    }, {
+      scaleY: 1,
+      duration: opts.duration ?? 0.86,
+      stagger: opts.stagger ?? 0.035,
+      ease: "expo.out",
+    }, cue)
+      .fromTo(labels, { y: 18, autoAlpha: 0 }, {
+        y: 0,
+        autoAlpha: 1,
+        duration: 0.34,
+        stagger: opts.stagger ?? 0.035,
+        ease: "power2.out",
+      }, cue + 0.24);
+    return tl;
+  }
+
+  function panelGridReflow(tl, panels, cue = 0, opts = {}) {
+    const gsap = gsapRef();
+    const panelList = gsap.utils.toArray(panels);
+    panelList.forEach((panel, index) => {
+      tl.fromTo(panel, {
+        xPercent: index % 2 === 0 ? -18 : 18,
+        yPercent: index % 3 === 0 ? -12 : 12,
+        rotateZ: index % 2 === 0 ? -3 : 3,
+        autoAlpha: 0,
+      }, {
+        xPercent: 0,
+        yPercent: 0,
+        rotateZ: 0,
+        autoAlpha: 1,
+        duration: opts.duration ?? 0.58,
+        ease: "expo.out",
+      }, cue + index * (opts.stagger ?? 0.045));
+    });
+    return tl;
+  }
+
+  function brandResolve(tl, tiles, wordmark, cue = 0, opts = {}) {
+    tl.to(tiles, {
+      x: 0,
+      y: 0,
+      rotateZ: 0,
+      scale: 0.78,
+      duration: opts.gatherDuration ?? 0.54,
+      stagger: opts.stagger ?? 0.025,
+      ease: "power3.inOut",
+    }, cue)
+      .to(tiles, { autoAlpha: 0, scale: 0.48, duration: 0.2, ease: "power2.in" }, cue + 0.48)
+      .fromTo(wordmark, { autoAlpha: 0, scale: 0.86, filter: "blur(10px)" }, {
+        autoAlpha: 1,
+        scale: 1,
+        filter: "blur(0px)",
+        duration: 0.42,
+        ease: "expo.out",
+      }, cue + 0.54);
+    return tl;
+  }
+
+  global.HyperAnimatorShotCraftMotion = {
+    slamEntrance,
+    whipTransition,
+    crashZoom,
+    pushStackWipe,
+    datavizLandscapeOpen,
+    panelGridReflow,
+    brandResolve,
+  };
+})(window);

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

@@ -108,7 +108,7 @@ Options:
   --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-3.0, music-2.6, or music-2.6-free
+  --model <model>              music-3.0, music-3.0-free, music-2.6, or music-2.6-free
   --config <file>              Explicit MiniMax config JSON
   --request-json <file>        Read request options from a JSON file
   --dry-run                    Print redacted request without contacting MiniMax
@@ -270,8 +270,12 @@ function safeFileStem(prompt) {
   return stem || "minimax-music";
 }
 
-async function downloadUrl(url) {
-  const response = await fetch(url);
+async function downloadUrl(url, timeoutMs) {
+  const parsed = URL.canParse(url) ? new URL(url) : null;
+  if (!parsed || !["http:", "https:"].includes(parsed.protocol)) {
+    throw minimaxError("MiniMax audio URL must use HTTP or HTTPS", { kind: "response" });
+  }
+  const response = await fetchWithTimeout(url, {}, timeoutMs);
 
   if (!response.ok) {
     throw new Error(`MiniMax audio URL download failed with HTTP ${response.status}`);
@@ -429,7 +433,7 @@ async function callMiniMaxWithRetries(config, request, { endpoint, timeoutMs, ma
   throw minimaxError("MiniMax request failed", { kind: "network", retryable: true, attempts });
 }
 
-async function writeAudioOutput({ responseJson, request, outputDir, prompt, endpoint }) {
+async function writeAudioOutput({ responseJson, request, outputDir, prompt, endpoint, timeoutMs }) {
   await mkdir(outputDir, { recursive: true });
 
   const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
@@ -439,7 +443,7 @@ async function writeAudioOutput({ responseJson, request, outputDir, prompt, endp
   const metadataPath = join(outputDir, `${stem}.minimax.json`);
   const audioValue = responseJson.data.audio;
   const audioBuffer = request.output_format === "url"
-    ? await downloadUrl(audioValue)
+    ? await downloadUrl(audioValue, timeoutMs)
     : decodeHexAudio(audioValue);
 
   await writeFile(audioPath, audioBuffer);
@@ -496,7 +500,7 @@ async function main() {
     }
 
     if (!runtime) {
-      throw Object.assign(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."), {
+      throw Object.assign(new Error("MiniMax config not found. Run hyper-animator-codex install with --minimax-api-key, or set MINIMAX_API_KEY."), {
         kind: "config",
         retryable: false,
       });
@@ -539,6 +543,7 @@ async function main() {
       outputDir: options.output_dir,
       prompt: options.prompt,
       endpoint,
+      timeoutMs,
     });
 
     printJson({

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

@@ -14,7 +14,7 @@ const BACKUP_TTS_ENDPOINT = "https://api-bj.minimaxi.com/v1/t2a_v2";
 const BACKUP_VOICE_ENDPOINT = "https://api-bj.minimaxi.com/v1/get_voice";
 const PROVIDER = "minimax_cn";
 const DEFAULT_TTS_MODEL = "speech-2.8-hd";
-const DEFAULT_VOICE_ID = "XiaoR_001";
+const DEFAULT_VOICE_ID = "male-qn-qingse";
 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));
@@ -135,12 +135,12 @@ Options:
   --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
+  --voice-id <id>            MiniMax voice_id, default from narration or male-qn-qingse
   --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
+  --format <mp3|wav|pcm|flac> Audio encoding format, default mp3
   --sample-rate <rate>       Default 32000
   --bitrate <bits>           Default 128000
   --channel <count>          Default 1
@@ -246,14 +246,17 @@ function validateOptions(options) {
   if (!options.voice_id || !options.voice_id.trim()) {
     throw minimaxError("voice_id is required", { kind: "validation" });
   }
+  if (typeof options.model !== "string" || !/^speech-[a-z0-9.-]+$/i.test(options.model)) {
+    throw minimaxError(`Unsupported MiniMax speech model: ${options.model}`, { 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 (!["mp3", "wav", "pcm", "flac"].includes(options.audio_format)) {
+    throw minimaxError("--format must be mp3, wav, pcm, or flac", { 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 (![8000, 16000, 22050, 24000, 32000, 44100].includes(options.sample_rate)) {
+    throw minimaxError("--sample-rate must be 8000, 16000, 22050, 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" });
@@ -261,6 +264,15 @@ function validateOptions(options) {
   if (![1, 2].includes(options.channel)) {
     throw minimaxError("--channel must be 1 or 2", { kind: "validation" });
   }
+  if (!Number.isFinite(options.speed) || options.speed < 0.5 || options.speed > 2) {
+    throw minimaxError("--speed must be from 0.5 to 2", { kind: "validation" });
+  }
+  if (!Number.isFinite(options.volume) || options.volume < 0.1 || options.volume > 10) {
+    throw minimaxError("--volume must be from 0.1 to 10", { kind: "validation" });
+  }
+  if (!Number.isInteger(options.pitch) || options.pitch < -12 || options.pitch > 12) {
+    throw minimaxError("--pitch must be an integer from -12 to 12", { kind: "validation" });
+  }
 }
 
 function buildTtsRequest(options) {
@@ -477,7 +489,7 @@ async function readRuntime(options) {
   }
 
   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.", {
+    throw minimaxError("MiniMax config not found. Run hyper-animator-codex install with --minimax-api-key, or set MINIMAX_API_KEY.", {
       kind: "config",
       retryable: false,
     });