hyper-animator-codex 0.7.0 → 0.8.0

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

@@ -15,6 +15,7 @@ function requireValue(args, index, flag) {
 function parseArgs(args) {
   const parsed = {
     narration: undefined,
+    timing_manifest: undefined,
     output_dir: join(process.cwd(), "hyper-animator-output", "subtitles"),
     style: "default",
   };
@@ -30,6 +31,9 @@ function parseArgs(args) {
     } else if (arg === "--style") {
       parsed.style = requireValue(args, index, arg);
       index += 1;
+    } else if (arg === "--timing-manifest") {
+      parsed.timing_manifest = requireValue(args, index, arg);
+      index += 1;
     } else if (arg === "--help" || arg === "-h") {
       parsed.help = true;
     } else {
@@ -71,14 +75,43 @@ function roundTime(value) {
   return Number(value.toFixed(3));
 }
 
-function buildCues(narration) {
+function validateTimingManifest(manifest, narration) {
+  if (!manifest || typeof manifest !== "object" || !Array.isArray(manifest.scenes)) {
+    throw new Error("timing manifest must include scenes[]");
+  }
+  if (manifest.provider !== "minimax_cn") {
+    throw new Error("timing manifest provider must be minimax_cn");
+  }
+  if (manifest.scenes.length !== narration.scenes.length) {
+    throw new Error("timing manifest scene count must match narration scenes");
+  }
+
+  let expectedStart = 0;
+  manifest.scenes.forEach((scene, index) => {
+    if (!Number.isFinite(scene.start_seconds) || !Number.isFinite(scene.end_seconds)
+      || scene.start_seconds < 0 || scene.end_seconds <= scene.start_seconds) {
+      throw new Error(`timing manifest scenes[${index}] must have valid start_seconds/end_seconds`);
+    }
+    if (Math.abs(scene.start_seconds - expectedStart) > 0.001) {
+      throw new Error(`timing manifest scenes[${index}] must be contiguous`);
+    }
+    expectedStart = scene.end_seconds;
+  });
+}
+
+function buildCues(narration, timingManifest) {
   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 timing = timingManifest?.scenes?.[sceneIndex];
+    const sceneStart = timing?.start_seconds ?? cursor;
+    const duration = timing
+      ? timing.end_seconds - timing.start_seconds
+      : Number(scene.duration_estimate) || Math.max(parts.length * 2, 2);
     const cueDuration = duration / Math.max(parts.length, 1);
+    cursor = sceneStart;
 
     parts.forEach((text) => {
       const start = cursor;
@@ -124,8 +157,12 @@ async function generateSubtitles(options) {
 
   const narration = JSON.parse(await readFile(options.narration, "utf8"));
   validateNarration(narration);
+  const timingManifest = options.timing_manifest
+    ? JSON.parse(await readFile(options.timing_manifest, "utf8"))
+    : null;
+  if (timingManifest) validateTimingManifest(timingManifest, narration);
 
-  const cues = buildCues(narration);
+  const cues = buildCues(narration, timingManifest);
   await mkdir(options.output_dir, { recursive: true });
 
   const jsonPath = join(options.output_dir, "subtitles.json");
@@ -134,6 +171,7 @@ async function generateSubtitles(options) {
     ok: true,
     style: options.style,
     source: options.narration,
+    timing_source: options.timing_manifest ?? null,
     cues,
   };
 
@@ -153,6 +191,7 @@ function printHelp() {
 
 Options:
   --narration <file>    Narration JSON file
+  --timing-manifest <file>  MiniMax narration-manifest.json with exact scene timing
   --output-dir <dir>    Output directory, default hyper-animator-output/subtitles
   --style <name>        Subtitle style label for downstream HTML/render steps
 `);

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

@@ -1,8 +1,8 @@
 import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 
-export const DEFAULT_MINIMAX_MODEL = "music-2.6-free";
-export const TEXT_MUSIC_MODELS = new Set(["music-2.6", "music-2.6-free"]);
+export const DEFAULT_MINIMAX_MODEL = "music-2.6";
+export const TEXT_MUSIC_MODELS = new Set(["music-3.0", "music-2.6", "music-2.6-free"]);
 
 async function pathExists(path) {
   try {
@@ -61,7 +61,7 @@ export function validateMinimaxConfig(config = {}) {
   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.`);
+    throw new Error(`Unsupported MiniMax text music model: ${model}. Use music-3.0, music-2.6, or music-2.6-free.`);
   }
 
   return {

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

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const catalogPath = join(dirname(scriptDir), "references", "shotcraft", "catalog.json");
+
+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 = { limit: 8, json: false, include_reference_only: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--query" || arg === "-q") {
+      parsed.query = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg === "--limit") {
+      parsed.limit = Number.parseInt(requireValue(args, index, arg), 10);
+      index += 1;
+    } else if (arg === "--json") {
+      parsed.json = true;
+    } else if (arg === "--include-reference-only") {
+      parsed.include_reference_only = true;
+    } else if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+  return parsed;
+}
+
+function tokens(value) {
+  return String(value)
+    .toLowerCase()
+    .split(/[\s,，。:：;；/|()[\]{}"'`_-]+/)
+    .map((token) => token.trim())
+    .filter(Boolean);
+}
+
+function scoreText(queryTokens, fields) {
+  const haystack = fields.filter(Boolean).join("\n").toLowerCase();
+  return queryTokens.reduce((score, token) => {
+    if (!haystack.includes(token)) return score;
+    const exactWord = new RegExp(`(^|[^a-z0-9])${token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}([^a-z0-9]|$)`, "i");
+    return score + (exactWord.test(haystack) ? 4 : 2);
+  }, 0);
+}
+
+function rankCard(card, queryTokens, includeReferenceOnly) {
+  const eligibleStyles = card.styles.filter((style) => (
+    includeReferenceOnly || style.implementation_status === "implemented"
+  ));
+  if (eligibleStyles.length === 0) return null;
+
+  const styleScores = eligibleStyles.map((style) => ({
+    style,
+    score: scoreText(queryTokens, [
+      style.key,
+      style.label,
+      style.description,
+      style.use,
+    ]),
+  })).sort((left, right) => right.score - left.score || left.style.key.localeCompare(right.style.key));
+
+  const cardScore = scoreText(queryTokens, [
+    card.name,
+    card.summary,
+    card.use,
+    card.energy,
+    card.intention,
+  ]);
+  const bestStyle = styleScores[0];
+  const slugBonus = queryTokens.some((token) => card.name.includes(token)) ? 3 : 0;
+  return {
+    score: cardScore + bestStyle.score + slugBonus,
+    card: card.name,
+    summary: card.summary,
+    use: card.use,
+    duration: card.duration,
+    energy: card.energy,
+    code_status: card.code_status,
+    style: bestStyle.style.key,
+    implementation_status: bestStyle.style.implementation_status,
+    usage_document: bestStyle.style.usage_document || card.usage_document,
+    source_files: bestStyle.style.source_files,
+  };
+}
+
+function printHuman(results) {
+  for (const [index, result] of results.entries()) {
+    console.log(`${index + 1}. ${result.card} / ${result.style} (score ${result.score})`);
+    console.log(`   ${result.summary}`);
+    console.log(`   use: ${result.use}`);
+    console.log(`   source: ${result.source_files.join(", ")}`);
+  }
+}
+
+async function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+      console.log("Usage: query_shotcraft.mjs --query <text> [--limit 8] [--json] [--include-reference-only]");
+      return;
+    }
+    if (!args.query?.trim()) throw new Error("--query is required");
+    if (!Number.isInteger(args.limit) || args.limit < 1 || args.limit > 50) {
+      throw new Error("--limit must be an integer from 1 to 50");
+    }
+
+    const catalog = JSON.parse(await readFile(catalogPath, "utf8"));
+    const queryTokens = tokens(args.query);
+    const results = catalog.cards
+      .map((card) => rankCard(card, queryTokens, args.include_reference_only))
+      .filter((result) => result && result.score > 0)
+      .sort((left, right) => right.score - left.score || left.card.localeCompare(right.card))
+      .slice(0, args.limit);
+
+    if (args.json) {
+      console.log(JSON.stringify({
+        ok: true,
+        query: args.query,
+        source_revision: catalog.source_revision,
+        results,
+      }, null, 2));
+    } else {
+      printHuman(results);
+    }
+  } catch (error) {
+    console.log(JSON.stringify({ ok: false, error: error.message }, null, 2));
+    process.exitCode = 1;
+  }
+}
+
+main();

package/skills/hyper-animator-codex/scripts/validate_hyperframes_html.py

@@ -13,6 +13,20 @@ def has_attr(html: str, name: str) -> bool:
     return re.search(rf"\b{name}\s*=\s*['\"]?[^'\"\s>]+", html, re.IGNORECASE) is not None
 
 
+def numeric_attr(html: str, name: str) -> float | None:
+    match = re.search(
+        rf"\b{name}\s*=\s*(?:['\"]([^'\"]+)['\"]|([^\s>]+))",
+        html,
+        re.IGNORECASE,
+    )
+    if not match:
+        return None
+    try:
+        return float(match.group(1) or match.group(2))
+    except ValueError:
+        return None
+
+
 def check_html(
     html: str,
     *,
@@ -26,6 +40,11 @@ def check_html(
         for attr in ("data-width", "data-height", "data-duration", "data-composition-id"):
             if not has_attr(html, attr):
                 failures.append(f"missing {attr}")
+        for attr in ("data-width", "data-height", "data-duration"):
+            if has_attr(html, attr):
+                value = numeric_attr(html, attr)
+                if value is None or value <= 0:
+                    failures.append(f"{attr} must be a positive number")
 
     if "<!-- paste from " in html:
         failures.append("unresolved component paste placeholder")
@@ -47,6 +66,9 @@ def check_html(
     if re.search(r"\bsetInterval\s*\(", html):
         failures.append("uses setInterval(); primary render progress must be timeline-driven")
 
+    if re.search(r"\bMath\s*\.\s*random\s*\(", html):
+        failures.append("uses Math.random(); visual generation must use a fixed-seed deterministic PRNG")
+
     if re.search(r"\brequestAnimationFrame\s*\(", html) and "fallback" not in html.lower():
         warnings.append("requestAnimationFrame found; ensure it is not the primary render clock and has render fallback")
 

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

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const policyPath = join(dirname(scriptDir), "contracts", "workflow-policy.json");
+
+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 = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (["--kind", "--provider", "--endpoint"].includes(arg)) {
+      parsed[arg.slice(2)] = 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 output(payload, exitCode = 0) {
+  console.log(JSON.stringify(payload, null, 2));
+  process.exitCode = exitCode;
+}
+
+function reject(code, message, details = {}) {
+  output({ ok: false, error: { code, message, ...details } }, 1);
+}
+
+async function main() {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+      console.log("Usage: validate_provider_policy.mjs --kind <narration|bgm> --provider <name> --endpoint <url>");
+      return;
+    }
+
+    if (!["narration", "bgm"].includes(args.kind)) {
+      reject("invalid_kind", "--kind must be narration or bgm");
+      return;
+    }
+    if (!args.provider) {
+      reject("missing_provider", "--provider is required");
+      return;
+    }
+    if (!args.endpoint || !URL.canParse(args.endpoint)) {
+      reject("invalid_endpoint", "--endpoint must be a valid URL");
+      return;
+    }
+
+    const policy = JSON.parse(await readFile(policyPath, "utf8"));
+    const normalizedProvider = args.provider.trim().toLowerCase();
+    if (policy.audio.forbidden_providers.includes(normalizedProvider)) {
+      reject("forbidden_provider", `${args.provider} is forbidden by the generated-audio policy`, {
+        provider: normalizedProvider,
+      });
+      return;
+    }
+
+    const route = args.kind === "narration"
+      ? policy.audio.generated_narration
+      : policy.audio.generated_bgm;
+    if (normalizedProvider !== route.provider) {
+      reject("provider_mismatch", `${args.kind} generation requires provider ${route.provider}`, {
+        expected: route.provider,
+        actual: normalizedProvider,
+      });
+      return;
+    }
+
+    const actual = new URL(args.endpoint);
+    const expected = new URL(route.endpoint);
+    const allowedEndpoints = [route.endpoint, ...(route.backup_endpoints || [])]
+      .map((endpoint) => new URL(endpoint));
+    if (!allowedEndpoints.some((allowed) => (
+      actual.origin === allowed.origin && actual.pathname === allowed.pathname
+    ))) {
+      reject("endpoint_mismatch", `${args.kind} generation requires the MiniMax mainland endpoint`, {
+        expected: route.endpoint,
+        actual: args.endpoint,
+      });
+      return;
+    }
+
+    output({
+      ok: true,
+      kind: args.kind,
+      provider: route.provider,
+      endpoint: args.endpoint,
+      primary_endpoint: route.endpoint,
+      region: "cn",
+    });
+  } catch (error) {
+    reject("validation", error.message);
+  }
+}
+
+main();

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

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const skillRoot = dirname(scriptDir);
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function validateAudioTrack(track, label, errors) {
+  if (!isObject(track)) {
+    errors.push(`audio.${label} must be an object`);
+    return;
+  }
+
+  if (!["generated", "user_local_file", "none"].includes(track.mode)) {
+    errors.push(`audio.${label}.mode must be generated, user_local_file, or none`);
+  }
+  if (track.mode === "generated" && track.provider !== "minimax_cn") {
+    errors.push(`audio.${label}.provider must be minimax_cn when mode is generated`);
+  }
+  if (track.mode === "user_local_file" && (typeof track.path !== "string" || !track.path.trim())) {
+    errors.push(`audio.${label}.path is required when mode is user_local_file`);
+  }
+  if (track.mode === "none" && track.provider !== undefined) {
+    errors.push(`audio.${label}.provider must be omitted when mode is none`);
+  }
+}
+
+function validateShotPlan(plan, catalogs) {
+  const errors = [];
+
+  if (!isObject(plan)) return ["plan must be a JSON object"];
+  if (plan.schema_version !== "1.0.0") errors.push("schema_version must be 1.0.0");
+  if (!["assemble_existing_catalog_items", "generate_new_hyperframes_html"].includes(plan.generation_mode)) {
+    errors.push("generation_mode is invalid");
+  }
+  if (plan.catalog_strategy !== "dual_catalog") errors.push("catalog_strategy must be dual_catalog");
+
+  if (!isObject(plan.dimensions)
+    || !Number.isInteger(plan.dimensions.width)
+    || !Number.isInteger(plan.dimensions.height)
+    || plan.dimensions.width <= 0
+    || plan.dimensions.height <= 0) {
+    errors.push("dimensions.width and dimensions.height must be positive integers");
+  }
+  if (!Number.isFinite(plan.duration_seconds) || plan.duration_seconds <= 0) {
+    errors.push("duration_seconds must be a positive number");
+  }
+
+  if (!isObject(plan.audio)) {
+    errors.push("audio must be an object");
+  } else {
+    validateAudioTrack(plan.audio.narration, "narration", errors);
+    validateAudioTrack(plan.audio.bgm, "bgm", errors);
+  }
+
+  if (!isObject(plan.model_routing)) {
+    errors.push("model_routing must be an object");
+  } else {
+    if (plan.model_routing.page_animation_authoring !== "gpt-5.6-sol") {
+      errors.push("model_routing.page_animation_authoring must be gpt-5.6-sol");
+    }
+    if (!plan.model_routing.planning_and_validation) {
+      errors.push("model_routing.planning_and_validation is required");
+    } else if (plan.model_routing.planning_and_validation === "gpt-5.6-sol") {
+      errors.push("model_routing.planning_and_validation must not use gpt-5.6-sol");
+    }
+  }
+
+  if (!Array.isArray(plan.shots) || plan.shots.length === 0) {
+    errors.push("shots must contain at least one shot");
+    return errors;
+  }
+
+  const ids = new Set();
+  plan.shots.forEach((shot, index) => {
+    const label = `shots[${index}]`;
+    if (!isObject(shot)) {
+      errors.push(`${label} must be an object`);
+      return;
+    }
+    if (typeof shot.id !== "string" || !/^[a-z][a-z0-9-]*$/.test(shot.id)) {
+      errors.push(`${label}.id must be a kebab-case identifier`);
+    } else if (ids.has(shot.id)) {
+      errors.push(`${label}.id must be unique`);
+    } else {
+      ids.add(shot.id);
+    }
+    if (!Number.isFinite(shot.start_seconds) || shot.start_seconds < 0) {
+      errors.push(`${label}.start_seconds must be zero or greater`);
+    }
+    if (!Number.isFinite(shot.end_seconds) || shot.end_seconds <= shot.start_seconds) {
+      errors.push(`${label}.end_seconds must be greater than start_seconds`);
+    }
+    if (typeof shot.purpose !== "string" || !shot.purpose.trim()) {
+      errors.push(`${label}.purpose is required`);
+    }
+    if (!Array.isArray(shot.hyperframes_refs)) {
+      errors.push(`${label}.hyperframes_refs must be an array`);
+    } else {
+      for (const reference of shot.hyperframes_refs) {
+        if (!catalogs.hyperframes.has(reference)) {
+          errors.push(`${label} has unknown HyperFrames reference: ${reference}`);
+        }
+      }
+    }
+    if (!Array.isArray(shot.shotcraft_refs)) {
+      errors.push(`${label}.shotcraft_refs must be an array`);
+    } else {
+      for (const reference of shot.shotcraft_refs) {
+        if (!catalogs.shotcraft.has(reference)) {
+          errors.push(`${label} has unknown ShotCraft reference: ${reference}`);
+        }
+      }
+    }
+    if (Array.isArray(shot.hyperframes_refs)
+      && Array.isArray(shot.shotcraft_refs)
+      && shot.hyperframes_refs.length + shot.shotcraft_refs.length === 0) {
+      errors.push(`${label} must reference at least one catalog`);
+    }
+
+    if (index === 0 && shot.start_seconds !== 0) {
+      errors.push("shots must start at 0 seconds");
+    }
+    if (index > 0 && Number.isFinite(shot.start_seconds)) {
+      const previous = plan.shots[index - 1];
+      if (Number.isFinite(previous?.end_seconds) && Math.abs(shot.start_seconds - previous.end_seconds) > 0.001) {
+        errors.push(`shots must be contiguous: ${label}.start_seconds must equal shots[${index - 1}].end_seconds`);
+      }
+    }
+  });
+
+  const lastEnd = plan.shots.at(-1)?.end_seconds;
+  if (Number.isFinite(lastEnd)
+    && Number.isFinite(plan.duration_seconds)
+    && Math.abs(lastEnd - plan.duration_seconds) > 0.001) {
+    errors.push("last shot end_seconds must equal duration_seconds");
+  }
+
+  return errors;
+}
+
+function output(payload, code = 0) {
+  console.log(JSON.stringify(payload, null, 2));
+  process.exitCode = code;
+}
+
+async function main() {
+  try {
+    const path = process.argv[2];
+    if (!path || path === "--help" || path === "-h") {
+      console.log("Usage: validate_shot_plan.mjs <shot-plan.json>");
+      process.exitCode = path ? 0 : 1;
+      return;
+    }
+    const plan = JSON.parse(await readFile(path, "utf8"));
+    const hyperframesCatalog = JSON.parse(await readFile(
+      join(skillRoot, "references", "hyperframes-catalog-map.json"),
+      "utf8",
+    ));
+    const shotcraftCatalog = JSON.parse(await readFile(
+      join(skillRoot, "references", "shotcraft", "catalog.json"),
+      "utf8",
+    ));
+    const catalogs = {
+      hyperframes: new Set(hyperframesCatalog.items.map((item) => item.id)),
+      shotcraft: new Set(shotcraftCatalog.cards.flatMap((card) => [
+        card.name,
+        ...card.styles.map((style) => style.key),
+      ])),
+    };
+    const errors = validateShotPlan(plan, catalogs);
+    if (errors.length > 0) {
+      output({ ok: false, path, errors }, 1);
+      return;
+    }
+    output({
+      ok: true,
+      path,
+      shot_count: plan.shots.length,
+      duration_seconds: plan.duration_seconds,
+      catalog_strategy: plan.catalog_strategy,
+    });
+  } catch (error) {
+    output({ ok: false, errors: [error.message] }, 1);
+  }
+}
+
+main();

package/skills/hyper-animator-codex/vendor/music-beat-detector/beat_detector/analyzer.py

@@ -23,6 +23,7 @@ class MetaInfo:
     sample_rate: int
     bpm: float
     time_signature: str = "4/4"
+    beat_grid: dict = field(default_factory=dict)
 
 
 @dataclass
@@ -116,7 +117,8 @@ def analyze(
         duration_ms=duration_ms,
         sample_rate=sr,
         bpm=beat_result.bpm,
-        time_signature=beat_result.time_signature
+        time_signature=beat_result.time_signature,
+        beat_grid=beat_result.beat_grid
     )
 
     result = AnalysisResult(

package/skills/hyper-animator-codex/vendor/music-beat-detector/beat_detector/beat.py

@@ -30,6 +30,41 @@ class BeatResult:
     bpm: float
     beats: List[Beat]
     time_signature: str = "4/4"
+    beat_grid: dict = None
+
+
+def _fit_beat_grid(beat_times: np.ndarray, fallback_bpm: float) -> tuple[float, dict]:
+    """Fit t_i = phase + i * period and report grid reliability."""
+    if len(beat_times) < 2:
+        period = 60.0 / fallback_bpm if fallback_bpm > 0 else 0.0
+        phase = float(beat_times[0]) if len(beat_times) == 1 else 0.0
+        return fallback_bpm, {
+            "method": "insufficient_beats",
+            "phase_ms": round(phase * 1000, 3),
+            "period_ms": round(period * 1000, 3),
+            "max_residual_ms": None,
+            "rms_residual_ms": None,
+            "reliable": False,
+            "threshold_ms": 15.0,
+        }
+
+    indexes = np.arange(len(beat_times), dtype=float)
+    design = np.vstack([indexes, np.ones_like(indexes)]).T
+    (period, phase), *_ = np.linalg.lstsq(design, beat_times, rcond=None)
+    residuals = beat_times - (phase + indexes * period)
+    max_residual_ms = float(np.max(np.abs(residuals)) * 1000)
+    rms_residual_ms = float(np.sqrt(np.mean(residuals ** 2)) * 1000)
+    fitted_bpm = 60.0 / period if period > 0 else fallback_bpm
+
+    return fitted_bpm, {
+        "method": "least_squares",
+        "phase_ms": round(float(phase) * 1000, 3),
+        "period_ms": round(float(period) * 1000, 3),
+        "max_residual_ms": round(max_residual_ms, 3),
+        "rms_residual_ms": round(rms_residual_ms, 3),
+        "reliable": max_residual_ms <= 15.0,
+        "threshold_ms": 15.0,
+    }
 
 
 def detect_beats(
@@ -52,6 +87,7 @@ def detect_beats(
 
     # 转换为时间（毫秒）
     beat_times = librosa.frames_to_time(beat_frames, sr=sr)
+    bpm, beat_grid = _fit_beat_grid(beat_times, bpm)
     beat_times_ms = [int(t * 1000) for t in beat_times]
 
     # 计算每个beat的能量
@@ -82,7 +118,7 @@ def detect_beats(
     if on_progress:
         on_progress(100.0)
 
-    return BeatResult(bpm=bpm, beats=beats)
+    return BeatResult(bpm=bpm, beats=beats, beat_grid=beat_grid)
 
 
 def _compute_beat_energies(