Add support for running output directly in Audio Worklet

There are some use cases where its useful to be able to run emscripten
generated code in an audio worklet without building with
`-sAUDIO_WORKLET`.  One major one is for deploying in a context where
shared memory not available (i.e. no cross origin isolation)

Fixes: #25943, #25943

Author: sbc100

ChangeLog.md

@@ -20,6 +20,13 @@ See docs/process.md for more on how version tagging works.
 
 4.0.22 (in development)
 -----------------------
+- It is now possible to load emscripten-generated code directly into an Audio
+  Worklet without using the `-sAUDIO_WORKLET` setting (which depends on shared
+  memory and `-sWASM_WORKERS`). To do this simply build with
+  `-sENVIRONMENT=worklet`. In this environment, because audio worklets don't
+  have a fetch API, you will need to either using `-sSINGLE_FILE` to embed the
+  Wasm file, or use a custom `instantiateWasm` callback while performing
+  instantation externally. (#25942)
 - Source maps now support 'names' field with function name information.
   emsymbolizer will show function names when used with a source map. The size
   of source maps may increase 2-3x and the link time can increase slightly due

site/source/docs/tools_reference/settings_reference.rst

@@ -991,13 +991,18 @@ are:
 - 'webview' - just like web, but in a webview like Cordova; considered to be
   same as "web" in almost every place
 - 'worker'  - a web worker environment.
+- 'worklet' - Audio Worklet environment.
 - 'node'    - Node.js.
 - 'shell'   - a JS shell like d8, js, or jsc.
 
 This setting can be a comma-separated list of these environments, e.g.,
 "web,worker". If this is the empty string, then all environments are
 supported.
 
+Certain settings will automatically add to this list.  For examble, building
+with pthreads will automatically add `worker` and building with
+``AUDIO_WORKLET`` will automatically add `worklet`.
+
 Note that the set of environments recognized here is not identical to the
 ones we identify at runtime using ``ENVIRONMENT_IS_*``. Specifically:
 
@@ -2502,6 +2507,11 @@ AUDIO_WORKLET
 If true, enables targeting Wasm Web Audio AudioWorklets. Check out the
 full documentation in site/source/docs/api_reference/wasm_audio_worklets.rst
 
+Note: The setting will implicitly add ``worklet`` to the :ref:`ENVIRONMENT`,
+(i.e. the resulting code and run in a worklet environment) but additionaly
+depends on ``WASM_WORKERS`` and Wasm SharedArrayBuffer to run new Audio
+Worklets.
+
 Default value: 0
 
 .. _audio_worklet_support_audio_params:

src/preamble.js

@@ -443,6 +443,12 @@ function findWasmBinary() {
   }
 #endif
 
+#if ENVIRONMENT_MAY_BE_AUDIO_WORKLET && !AUDIO_WORKLET // AUDIO_WORKLET handled above
+  if (ENVIRONMENT_IS_AUDIO_WORKLET) {
+    return '{{{ WASM_BINARY_FILE }}}';
+  }
+#endif
+
   if (Module['locateFile']) {
     return locateFile('{{{ WASM_BINARY_FILE }}}');
   }

src/settings.js

@@ -646,13 +646,18 @@ var LEGACY_VM_SUPPORT = false;
 // - 'webview' - just like web, but in a webview like Cordova; considered to be
 //   same as "web" in almost every place
 // - 'worker'  - a web worker environment.
+// - 'worklet' - Audio Worklet environment.
 // - 'node'    - Node.js.
 // - 'shell'   - a JS shell like d8, js, or jsc.
 //
 // This setting can be a comma-separated list of these environments, e.g.,
 // "web,worker". If this is the empty string, then all environments are
 // supported.
 //
+// Certain settings will automatically add to this list.  For examble, building
+// with pthreads will automatically add `worker` and building with
+// ``AUDIO_WORKLET`` will automatically add `worklet`.
+//
 // Note that the set of environments recognized here is not identical to the
 // ones we identify at runtime using ``ENVIRONMENT_IS_*``. Specifically:
 //
@@ -1629,6 +1634,11 @@ var WASM_WORKERS = 0;
 
 // If true, enables targeting Wasm Web Audio AudioWorklets. Check out the
 // full documentation in site/source/docs/api_reference/wasm_audio_worklets.rst
+//
+// Note: The setting will implicitly add ``worklet`` to the :ref:`ENVIRONMENT`,
+// (i.e. the resulting code and run in a worklet environment) but additionaly
+// depends on ``WASM_WORKERS`` and Wasm SharedArrayBuffer to run new Audio
+// Worklets.
 // [link]
 var AUDIO_WORKLET = 0;
 

src/settings_internal.js

@@ -140,6 +140,7 @@ var ENVIRONMENT_MAY_BE_WORKER = true;
 var ENVIRONMENT_MAY_BE_NODE = true;
 var ENVIRONMENT_MAY_BE_SHELL = true;
 var ENVIRONMENT_MAY_BE_WEBVIEW = true;
+var ENVIRONMENT_MAY_BE_AUDIO_WORKLET = true;
 
 // Whether to minify import and export names in the minify_wasm_js stage.
 // Currently always off for MEMORY64.

src/shell.js

@@ -34,7 +34,7 @@ var Module = moduleArg;
 var Module;
 // if (!Module)` is crucial for Closure Compiler here as it will otherwise replace every `Module` occurrence with a string
 if (!Module) /** @suppress{checkTypes}*/Module = {"__EMSCRIPTEN_PRIVATE_MODULE_EXPORT_NAME_SUBSTITUTION__":1};
-#elif AUDIO_WORKLET
+#elif ENVIRONMENT_MAY_BE_AUDIO_WORKLET
 var Module = globalThis.Module || (typeof {{{ EXPORT_NAME }}} != 'undefined' ? {{{ EXPORT_NAME }}} : {});
 #else
 var Module = typeof {{{ EXPORT_NAME }}} != 'undefined' ? {{{ EXPORT_NAME }}} : {};
@@ -53,8 +53,11 @@ var Module = typeof {{{ EXPORT_NAME }}} != 'undefined' ? {{{ EXPORT_NAME }}} : {
 var ENVIRONMENT_IS_WASM_WORKER = globalThis.name == 'em-ww';
 #endif
 
-#if AUDIO_WORKLET
+#if ENVIRONMENT_MAY_BE_AUDIO_WORKLET
 var ENVIRONMENT_IS_AUDIO_WORKLET = !!globalThis.AudioWorkletGlobalScope;
+#endif
+
+#if AUDIO_WORKLET
 // Audio worklets behave as wasm workers.
 if (ENVIRONMENT_IS_AUDIO_WORKLET) ENVIRONMENT_IS_WASM_WORKER = true;
 #endif
@@ -79,7 +82,7 @@ var ENVIRONMENT_IS_WORKER = !!globalThis.WorkerGlobalScope;
 // N.b. Electron.js environment is simultaneously a NODE-environment, but
 // also a web environment.
 var ENVIRONMENT_IS_NODE = {{{ nodeDetectionCode() }}};
-#if AUDIO_WORKLET
+#if ENVIRONMENT_MAY_BE_AUDIO_WORKLET
 var ENVIRONMENT_IS_SHELL = !ENVIRONMENT_IS_WEB && !ENVIRONMENT_IS_NODE && !ENVIRONMENT_IS_WORKER && !ENVIRONMENT_IS_AUDIO_WORKLET;
 #else
 var ENVIRONMENT_IS_SHELL = !ENVIRONMENT_IS_WEB && !ENVIRONMENT_IS_NODE && !ENVIRONMENT_IS_WORKER;
@@ -352,7 +355,9 @@ if (ENVIRONMENT_IS_WEB || ENVIRONMENT_IS_WORKER) {
   }
 } else
 #endif // ENVIRONMENT_MAY_BE_WEB || ENVIRONMENT_MAY_BE_WORKER
-#if AUDIO_WORKLET && ASSERTIONS
+#if ENVIRONMENT_MAY_BE_AUDIO_WORKLET
+#endif
+#if ENVIRONMENT_MAY_BE_AUDIO_WORKLET && ASSERTIONS
 if (!ENVIRONMENT_IS_AUDIO_WORKLET)
 #endif
 {
@@ -401,7 +406,7 @@ if (ENVIRONMENT_IS_NODE) {
 // if an assertion fails it cannot print the message
 #if PTHREADS
 assert(
-#if AUDIO_WORKLET
+#if ENVIRONMENT_MAY_BE_AUDIO_WORKLET
   ENVIRONMENT_IS_AUDIO_WORKLET ||
 #endif
   ENVIRONMENT_IS_WEB || ENVIRONMENT_IS_WORKER || ENVIRONMENT_IS_NODE, 'Pthreads do not work in this environment yet (need Web Workers, or an alternative to them)');

test/test_browser.py

@@ -5478,6 +5478,44 @@ def test_audio_worklet_params_mixing(self, args):
   def test_audio_worklet_emscripten_locks(self):
     self.btest_exit('webaudio/audioworklet_emscripten_locks.c', cflags=['-sAUDIO_WORKLET', '-sWASM_WORKERS', '-pthread'])
 
+  def test_audio_worklet_direct(self):
+    self.add_browser_reporting()
+    self.emcc('hello_world.c', ['-o', 'hello_world.mjs', '-sEXPORT_ES6', '-sSINGLE_FILE', '-sENVIRONMENT=worklet'])
+    create_file('worklet.mjs', '''
+      import Module from "./hello_world.mjs"
+      console.log("in worklet");
+      class MyProcessor extends AudioWorkletProcessor {
+        constructor() {
+          super();
+          Module().then(() => {
+            console.log("done Module constructor");
+            this.port.postMessage("ready");
+          });
+        }
+        process(inputs, outputs, parameters) {
+          return true;
+        }
+      }
+      registerProcessor('my-processor', MyProcessor);
+      console.log("done register");
+    ''')
+    create_file('test.html', '''
+      <script src="browser_reporting.js"></script>
+      <script>
+        async function createContext() {
+          const context = new window.AudioContext();
+          await context.audioWorklet.addModule('worklet.mjs');
+          const node = new AudioWorkletNode(context, 'my-processor');
+          node.port.onmessage = (event) => {
+            console.log(event);
+            reportResultToServer(event.data);
+          }
+        }
+        createContext();
+      </script>
+    ''')
+    self.run_browser('test.html', '/report_result?ready')
+
   # Verifies setting audio context sample rate, and that emscripten_audio_context_sample_rate() works.
   @requires_sound_hardware
   @also_with_minimal_runtime

tools/link.py

@@ -67,7 +67,7 @@
   '__main_argc_argv',
 ]
 
-VALID_ENVIRONMENTS = ('web', 'webview', 'worker', 'node', 'shell')
+VALID_ENVIRONMENTS = {'web', 'webview', 'worker', 'node', 'shell', 'worklet'}
 
 EXECUTABLE_EXTENSIONS = ['.wasm', '.html', '.js', '.mjs', '.out', '']
 
@@ -184,6 +184,9 @@ def setup_environment_settings():
   if settings.SHARED_MEMORY and settings.ENVIRONMENT:
     settings.ENVIRONMENT.append('worker')
 
+  if settings.AUDIO_WORKLET:
+    settings.ENVIRONMENT.append('worklet')
+
   # Environment setting based on user input
   if any(x for x in settings.ENVIRONMENT if x not in VALID_ENVIRONMENTS):
     exit_with_error(f'Invalid environment specified in "ENVIRONMENT": {settings.ENVIRONMENT}. Should be one of: {",".join(VALID_ENVIRONMENTS)}')
@@ -193,6 +196,7 @@ def setup_environment_settings():
   settings.ENVIRONMENT_MAY_BE_NODE = not settings.ENVIRONMENT or 'node' in settings.ENVIRONMENT
   settings.ENVIRONMENT_MAY_BE_SHELL = not settings.ENVIRONMENT or 'shell' in settings.ENVIRONMENT
   settings.ENVIRONMENT_MAY_BE_WORKER = not settings.ENVIRONMENT or 'worker' in settings.ENVIRONMENT
+  settings.ENVIRONMENT_MAY_BE_AUDIO_WORKLET = not settings.ENVIRONMENT or 'worklet' in settings.ENVIRONMENT
 
   if not settings.ENVIRONMENT_MAY_BE_NODE:
     if 'MIN_NODE_VERSION' in user_settings and settings.MIN_NODE_VERSION != feature_matrix.UNSUPPORTED:
@@ -1175,7 +1179,7 @@ def limit_incoming_module_api():
   # In Audio Worklets TextDecoder API is intentionally not exposed
   # (https://github.com/WebAudio/web-audio-api/issues/2499) so we also need to
   # keep the JavaScript-based fallback.
-  if settings.SHRINK_LEVEL >= 2 and not settings.AUDIO_WORKLET and \
+  if settings.SHRINK_LEVEL >= 2 and not settings.ENVIRONMENT_MAY_BE_AUDIO_WORKLET and \
      not settings.ENVIRONMENT_MAY_BE_SHELL:
     default_setting('TEXTDECODER', 2)
 
@@ -2472,7 +2476,7 @@ def module_export_name_substitution():
   logger.debug(f'Private module export name substitution with {settings.EXPORT_NAME}')
   src = read_file(final_js)
   final_js += '.module_export_name_substitution.js'
-  if settings.MINIMAL_RUNTIME and not settings.ENVIRONMENT_MAY_BE_NODE and not settings.ENVIRONMENT_MAY_BE_SHELL and not settings.AUDIO_WORKLET:
+  if settings.MINIMAL_RUNTIME and not settings.ENVIRONMENT_MAY_BE_NODE and not settings.ENVIRONMENT_MAY_BE_SHELL and not settings.ENVIRONMENT_MAY_BE_AUDIO_WORKLET:
     # On the web, with MINIMAL_RUNTIME, the Module object is always provided
     # via the shell html in order to provide the .asm.js/.wasm content.
     replacement = settings.EXPORT_NAME