heygen-com/hyperframes · error

AudioWorklet is unavailable — the page needs a secure contex

Error message

AudioWorklet is unavailable — the page needs a secure context (https, localhost or file://)

What it means

ensureAudioFxWorklets() registers the AudioWorklet processors (hf-compressor, hf-limiter, hf-gate, hf-bitcrush) on a BaseAudioContext. If ctx.audioWorklet is undefined it throws, because AudioWorklet only exists in secure contexts. Secure means https://, localhost (127.0.0.1/localhost), or file://. The effects that need worklets are exactly those whose def.web starts with 'worklet-' (see chainNeedsWorklets).

Source

Thrown at packages/core/src/audio/audioFxWorklets.ts:203

        this.holds[ch] = (this.holds[ch] + 1) % step;
      }
    }
    return true;
  }
}
registerProcessor("hf-bitcrush", HfBitcrush);
`;

let modulePromise: Promise<void> | undefined;

/**
 * Register the processors on a context. Idempotent per module instance, since
 * addModule throws if the same processor name is registered twice.
 */
export function ensureAudioFxWorklets(ctx: BaseAudioContext): Promise<void> {
  modulePromise ??= (async () => {
    if (!ctx.audioWorklet) {
      throw new Error(
        "AudioWorklet is unavailable — the page needs a secure context (https, localhost or file://)",
      );
    }
    // A data: URL rather than a blob:, because a blob inherits the page origin
    // and is treated as opaque on a file:// page, where the module then fails
    // to load with an unhelpful AbortError.
    const url = `data:text/javascript;base64,${btoa(
      String.fromCharCode(...new TextEncoder().encode(AUDIO_FX_WORKLET_SOURCE)),
    )}`;
    await ctx.audioWorklet.addModule(url);
  })();
  return modulePromise;
}

/** Test seam: forget the cached registration so a fresh context can register. */
export function __resetAudioFxWorkletsForTests(): void {
  modulePromise = undefined;
}

View on GitHub (pinned to c2996c8626)

Solutions

  1. Serve the page over https, or access it via localhost/127.0.0.1/file:// so the context is secure.
  2. Remove worklet-based effects (compressor, limiter, gate, bitcrush) from the chain for that context — non-worklet effects (biquad filters, waveshaper, delay, chorus, phaser, convolver) run without AudioWorklet.
  3. If embedding the studio, ensure the parent page is https and the iframe is same-origin or served over https.

Example fix

// before — page on http://lan-ip, chain has worklet effects
ctx.audioWorklet; // undefined -> ensureAudioFxWorklets throws

// after — serve securely or drop worklet nodes
import { chainNeedsWorklets } from "@hyperframes/core";
if (chainNeedsWorklets(chain) && !window.isSecureContext) {
  chain = { ...chain, nodes: chain.nodes.filter((n) => !n.type.startsWith("worklet-")) };
}
// and/or access via https:// or localhost
Defensive patterns

Strategy: validation

Validate before calling

function canUseWorklets(ctx: BaseAudioContext): boolean {
  return typeof ctx.audioWorklet === "object" && ctx.audioWorklet !== null && window.isSecureContext;
}
if (chainNeedsWorklets(chain) && !canUseWorklets(ctx)) {
  // strip worklet nodes or move to https/localhost
}

Type guard

function supportsAudioWorklet(ctx: BaseAudioContext): boolean {
  return ctx.audioWorklet != null && typeof window !== "undefined" && window.isSecureContext === true;
}

Try / catch

try { await ensureAudioFxWorklets(ctx); }
catch (err) {
  if (/secure context/.test(String(err))) { /* serve over https/localhost or drop worklet effects */ }
  else throw err;
}

Prevention

When it happens

Trigger: Previewing or rendering a chain that contains a worklet effect while the page is served over plain http on a non-localhost host (e.g. http://192.168.x.y:3000 on a LAN device, or an embedded iframe on http). The browser omits ctx.audioWorklet entirely in insecure contexts, so the property is undefined rather than the call failing.

Common situations: Opening the studio preview from another machine on the LAN via http://<lan-ip>; rendering inside an iframe embedded on a non-https parent page; testing on http://0.0.0.0; an older browser lacking AudioWorklet support.

Related errors

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