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

Author: sbc100

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 with automatically add this to this.  For exmaple, 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:
 

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 with automatically add this to this.  For exmaple, 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:
 //

src/settings_internal.js

@@ -135,11 +135,12 @@ var SOURCE_MAP_BASE = '';
 var SUPPORT_BASE64_EMBEDDING = false;
 
 // the possible environments the code may run in.
-var ENVIRONMENT_MAY_BE_WEB = true;
-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_WEB = false;
+var ENVIRONMENT_MAY_BE_WORKER = false;
+var ENVIRONMENT_MAY_BE_NODE = false;
+var ENVIRONMENT_MAY_BE_SHELL = false;
+var ENVIRONMENT_MAY_BE_WEBVIEW = false;
+var ENVIRONMENT_MAY_BE_AUDIO_WORKLET = false;
 
 // 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,12 +355,14 @@ 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
 {
 #if ASSERTIONS
-  throw new Error('environment detection error');
+  throw new Error('XXXXXenvironment detection error');
 #endif // ASSERTIONS
 }
 
@@ -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,28 @@ 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");
+      const m = await Module();
+      console.log("done");
+    ''')
+    create_file('test.html', '''
+      <script src="browser_reporting.js"></script>
+      <script>
+        async function createContext() {
+          const audioContext = new window.AudioContext();
+          await audioContext.audioWorklet.addModule('worklet.mjs');
+          reportResultToServer("done");
+        }
+        createContext();
+      </script>
+    ''')
+    self.run_browser('test.html', '/report_result?done')
+
   # Verifies setting audio context sample rate, and that emscripten_audio_context_sample_rate() works.
   @requires_sound_hardware
   @also_with_minimal_runtime

tools/emscripten.py

@@ -194,6 +194,8 @@ def generate_js_compiler_input_hash(symbols_only=False):
   if not symbols_only:
     files += settings.PRE_JS_FILES
     files += settings.POST_JS_FILES
+    # Also include other .js files that could be included in the output.
+    files += glob.glob(utils.path_from_root('src/*.js'))
 
   for file in sorted(files):
     file_contents.append(utils.read_file(file))

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