{"record":{"id":"3e1ec3ab4fe49bd4","repo":"heygen-com/hyperframes","slug":"audio-fx-runtime-failed-to-load","errorCode":null,"errorMessage":"audio FX runtime failed to load","messagePattern":"audio FX runtime failed to load","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/engine/src/services/audioFxRender.ts","lineNumber":244,"sourceCode":"      await page.goto(pathToFileURL(hostPage).href, { waitUntil: \"domcontentloaded\" });\n      await page.addScriptTag({ content: getAudioFxRuntimeScript() });\n\n      const rendered = (await page.evaluate(\n        async ([channelB64, rate, chainJson]: [string[], number, string]) => {\n          const decode = (b64: string): Float32Array => {\n            const bin = atob(b64);\n            const bytes = new Uint8Array(bin.length);\n            for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);\n            return new Float32Array(bytes.buffer);\n          };\n          const api = (\n            window as unknown as {\n              __HF_AUDIO_FX?: {\n                render(p: Float32Array[], r: number, c: string): Promise<Float32Array[]>;\n              };\n            }\n          ).__HF_AUDIO_FX;\n          if (!api) throw new Error(\"audio FX runtime failed to load\");\n          const out = await api.render(channelB64.map(decode), rate, chainJson);\n          const encode = (plane: Float32Array): string => {\n            const u8 = new Uint8Array(plane.buffer, plane.byteOffset, plane.length * 4);\n            let s = \"\";\n            const CHUNK = 0x8000;\n            for (let i = 0; i < u8.length; i += CHUNK) {\n              s += String.fromCharCode.apply(null, Array.from(u8.subarray(i, i + CHUNK)));\n            }\n            return btoa(s);\n          };\n          return out.map(encode);\n        },\n        [\n          planes.map((plane) =>\n            Buffer.from(plane.buffer, plane.byteOffset, plane.length * 4).toString(\"base64\"),\n          ),\n          sampleRate,\n          JSON.stringify(chain),","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/engine/src/services/audioFxRender.ts#L226-L262","documentation":"Thrown inside page.evaluate() when window.__HF_AUDIO_FX is undefined after page.addScriptTag() injected the audio FX runtime script. The runtime is expected to register a global object with a render(planes, sampleRate, chainJson) method. If the script failed to parse, threw during execution, or didn't set the global, the API surface is absent.","triggerScenarios":"applyAudioFxChain() calls page.addScriptTag({ content: getAudioFxRuntimeScript() }) then page.evaluate() which dereferences window.__HF_AUDIO_FX. If addScriptTag silently failed (e.g., the page navigated away, the script content was empty/malformed, or a Content Security Policy blocked inline scripts), __HF_AUDIO_FX is never set.","commonSituations":"The getAudioFxRuntimeScript() function returned an empty or truncated string due to a bundling issue. A browser extension or CSP header blocked inline script evaluation. The headless Chrome version doesn't support AudioWorklet (the script may depend on it). The file:// host page didn't load before addScriptTag ran.","solutions":["Verify getAudioFxRuntimeScript() returns non-empty, valid JavaScript by logging its length and first 200 chars.","Check the Chrome version supports AudioWorklet (Chrome 66+) and that the file:// page loaded (waitUntil: 'domcontentloaded' is used).","Run the runtime script in a standalone HTML file in a browser and check the console for parse/runtime errors.","If using a custom Chrome build, ensure JavaScript is not disabled (--disable-javascript flag must NOT be present)."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"const script = getAudioFxRuntimeScript();\nif (!script || script.length < 100) {\n  throw new Error('Audio FX runtime script is empty or truncated');\n}\n// verify the script registers the global\nif (!script.includes('__HF_AUDIO_FX')) {\n  throw new Error('Audio FX runtime script does not register __HF_AUDIO_FX');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await applyAudioFxChain(inputWav, chain, outWav, opts);\n} catch (err) {\n  if (err instanceof AudioFxRenderError && err.message.includes('runtime failed to load')) {\n    // check Chrome version, CSP, or bundle integrity\n  }\n  throw err;\n}","preventionTips":["Verify the runtime script bundle is non-empty and includes the __HF_AUDIO_FX registration before injection.","Ensure the headless Chrome version supports AudioWorklet (Chrome 66+).","Avoid --disable-javascript or restrictive CSP on the host page."],"tags":["audio","browser","puppeteer","runtime","script-injection"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}