heygen-com/hyperframes · error

beat analyzer not loaded

Error message

beat analyzer not loaded

What it means

Thrown inside the headless Chrome page (inPageAnalyze) when window.__hfAnalyze is not a function after addScriptTag injected the analyzer bundle. The bundle is supposed to set globalThis.__hfAnalyze = analyzeMusicFromBuffer; if the script failed to execute or the global was not assigned, the page-evaluate call rejects with this message, which detectOnPage then rewraps with any page-error detail.

Source

Thrown at packages/cli/src/beats/headlessAnalyzer.ts:90

  bpm: number | null;
  bpmConfidence: string;
}

// Guard against pathological inputs that would blow CDP message limits when
// transferred to the page as base64 (≈ +33% over the raw bytes).
const MAX_AUDIO_BYTES = 80 * 1024 * 1024;

// Runs inside the headless page: decode the base64 audio and analyze it.
function inPageAnalyze(data: string) {
  const bin = atob(data);
  const bytes = new Uint8Array(bin.length);
  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
  const win = window as unknown as {
    AudioContext: typeof AudioContext;
    webkitAudioContext?: typeof AudioContext;
    __hfAnalyze?: (buffer: AudioBuffer) => Promise<HeadlessBeatResult>;
  };
  if (typeof win.__hfAnalyze !== "function") throw new Error("beat analyzer not loaded");
  const ctx = new (win.AudioContext || win.webkitAudioContext!)();
  return (
    ctx
      .decodeAudioData(bytes.buffer)
      .then((buf) => win.__hfAnalyze!(buf))
      // analyzeMusicFromBuffer also returns the decoded PCM (channelData) + sampleRate;
      // project to only the fields we need so page.evaluate doesn't serialize an
      // ~8-million-element Float32Array back across the CDP boundary.
      .then((r) => ({
        beatTimes: r.beatTimes,
        beatStrengths: r.beatStrengths,
        bpm: r.bpm,
        bpmConfidence: r.bpmConfidence,
      }))
      .finally(() => ctx.close())
  );
}

View on GitHub (pinned to c2996c8626)

Solutions

1. Rebuild the CLI bundle artifacts: `bun run build` to regenerate beat-analyzer.global.js.
2. Clear any stale cache and retry: remove dist artifacts that findPrebuiltBundle() locates.
3. Check the wrapped error detail (detectOnPage appends pageErrors) for the underlying JS error and address it in the core beatDetection source.

Example fix

# before — stale analyzer bundle lacks the global assignment
$ bunx hyperframes beats song.mp3  # 'beat analyzer not loaded'
# rebuild and retry
$ bun run build
$ bunx hyperframes beats song.mp3

try {
  await analyzeBeatsHeadless(buf);
} catch (err) {
  const msg = (err as Error).message;
  if (/beat analyzer not loaded/i.test(msg)) {
    console.error('Analyzer bundle did not install __hfAnalyze. Rebuild artifacts: `bun run build`.');
  }
  throw err;
}

When it happens

Trigger: analyzeBeatsHeadless() runs detectOnPage(); page.addScriptTag({ content: bundle }) injects the bundle but a JS parse/exec error prevented __hfAnalyze being set; or the bundle string was empty/malformed (e.g. buildFromCoreSource produced empty output but did not throw).

Common situations: The analyzer bundle is stale or corrupted (older build missing the globalThis assignment); a CSP or page error blocked script execution; an esbuild output regression produced a partial bundle; headless Chrome failed to parse the IIFE.

Related errors

• Failed to bundle beat analyzer
• ${err instanceof Error ? err.message : String(err)}${detail}
• Audio file too large for headless analysis (${mb}MB > ${MAX_
• Missing browser script ${name}
• Could not persist selector: ${options.selector}

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/4a6e773eb5f6cd84. Report an issue: GitHub.