Add -sAUDIO_WORKLET=2 build mode

emcc.py

@@ -2555,11 +2555,15 @@ def phase_linker_setup(options, state, newargs):
   if settings.AUDIO_WORKLET:
     if settings.AUDIO_WORKLET == 1:
       settings.AUDIO_WORKLET_FILE = unsuffixed(os.path.basename(target)) + '.aw.js'
+      if not settings.MINIMAL_RUNTIME:
+        # MINIMAL_RUNTIME exports these manually, since this export mechanism is placed
+        # in global scope that is not suitable for MINIMAL_RUNTIME loader.
+        settings.EXPORTED_RUNTIME_METHODS += ['stackSave', 'stackAlloc', 'stackRestore']
+    elif settings.AUDIO_WORKLET == 2:
+      settings.BINARYEN_ASYNC_COMPILATION = 0 # Run synchronous Wasm initialization inside AudioWorklet.
+      settings.SINGLE_FILE = 1 # All code must be embedded in a single .js file when targeting -sAUDIO_WORKLET=2
+
     settings.JS_LIBRARIES.append((0, shared.path_from_root('src', 'library_webaudio.js')))
-    if not settings.MINIMAL_RUNTIME:
-      # MINIMAL_RUNTIME exports these manually, since this export mechanism is placed
-      # in global scope that is not suitable for MINIMAL_RUNTIME loader.
-      settings.EXPORTED_RUNTIME_METHODS += ['stackSave', 'stackAlloc', 'stackRestore']
 
   if settings.FORCE_FILESYSTEM and not settings.MINIMAL_RUNTIME:
     # when the filesystem is forced, we export by default methods that filesystem usage

src/base64Utils.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-#if POLYFILL && (ENVIRONMENT_MAY_BE_SHELL || (ENVIRONMENT_MAY_BE_NODE && MIN_NODE_VERSION < 160000))
+#if POLYFILL && (ENVIRONMENT_MAY_BE_SHELL || (ENVIRONMENT_MAY_BE_NODE && MIN_NODE_VERSION < 160000) || AUDIO_WORKLET)
 #include "polyfill/atob.js"
 #endif
 

src/library_webaudio.js

@@ -1,13 +1,38 @@
-#if AUDIO_WORKLET && !WASM_WORKERS
-#error "Building with -sAUDIO_WORKLET also requires enabling -sWASM_WORKERS!"
+/*
+Emscripten can target Audio Worklets in two different ways:
+
+1) -sAUDIO_WORKLET + -sWASM_WORKERS mode: User compiles a multithreaded WebAssembly program Module, which is then
+                                          shared to the Audio Worklet scope via postMessage()ing the Module over.
+                                          Audio Worklet and main program utilize the same shared WebAssembly Memory,
+                                          and can synchronize using lock-free atomics.
+2) -sAUDIO_WORKLET=2 mode: User compiles a singlethreaded WebAssembly program Module, which is loaded into Audio
+                           Worklet scope manually by a custom web page & JS audio engine developed by the user. Main
+                           web page does not contain any Emscripten-compiled content, no shared memory or multi-
+                           threading is in use.
+*/
+
+#if AUDIO_WORKLET == 1 && !WASM_WORKERS
+#error "Building with -sAUDIO_WORKLET=1 also requires enabling -sWASM_WORKERS!"
 #endif
 #if AUDIO_WORKLET && TEXTDECODER == 2
 #error "-sAUDIO_WORKLET does not support -sTEXTDECODER=2 since TextDecoder is not available in AudioWorkletGlobalScope! Use e.g. -sTEXTDECODER=1 when building with -sAUDIO_WORKLET"
 #endif
-#if AUDIO_WORKLET && SINGLE_FILE
-#error "-sAUDIO_WORKLET does not support -sSINGLE_FILE"
+#if AUDIO_WORKLET == 1 && SINGLE_FILE
+#error "-sAUDIO_WORKLET=1 does not support -sSINGLE_FILE"
 #endif
 
+#if AUDIO_WORKLET == 2 && SHARED_MEMORY
+#error "Building with -sAUDIO_WORKLET=2 does not support shared memory! (-sWASM_WORKERS nor -pthread). To target Audio Worklets with shared memory, use -sAUDIO_WORKLET=1 mode."
+#endif
+#if AUDIO_WORKLET == 2 && BINARYEN_ASYNC_COMPILATION
+#error "Building with -sAUDIO_WORKLET=2 requires -sBINARYEN_ASYNC_COMPILATION=0"
+#endif
+#if AUDIO_WORKLET == 2 && !SINGLE_FILE
+#error "Building with -sAUDIO_WORKLET=2 requires -sSINGLE_FILE=1"
+#endif
+
+#if AUDIO_WORKLET == 1 // None of the code below is used in -sAUDIO_WORKLET=2 mode.
+
 let LibraryWebAudio = {
   $EmAudio: {},
   $EmAudioCounter: 0,
@@ -334,3 +359,4 @@ let LibraryWebAudio = {
 };
 
 addToLibrary(LibraryWebAudio);
+#endif // ~AUDIO_WORKLET==1

src/settings.js

@@ -1546,7 +1546,10 @@ var SHARED_MEMORY = false;
 // [compile+link] - affects user code at compile and system libraries at link.
 var WASM_WORKERS = 0;
 
-// If true, enables targeting Wasm Web Audio AudioWorklets. Check out the
+// If 1, enables targeting Wasm Web Audio AudioWorklets with Wasm Workers.
+// If 2, enables building an Emscripten output Module that is compatible to be
+// manually loaded inside an Audio Worklet scope.
+// Check out the
 // full documentation in site/source/docs/api_reference/wasm_audio_worklets.rst
 // [link]
 var AUDIO_WORKLET = 0;

test/test_interactive.py

@@ -283,3 +283,18 @@ def test_audio_worklet_tone_generator(self):
   # Tests that AUDIO_WORKLET+MINIMAL_RUNTIME+MODULARIZE combination works together.
   def test_audio_worklet_modularize(self):
     self.btest('webaudio/audioworklet.c', expected='0', args=['-sAUDIO_WORKLET', '-sWASM_WORKERS', '-sMINIMAL_RUNTIME', '-sMODULARIZE'])
+
+  # This test verifies -sAUDIO_WORKLET=2 mode, where Emscripten output WebAssembly Module is compiled to be manually loadable
+  # inside a hand-written Audio Worklet processor node. The main page will not have any Emscripten produced code in it.
+  @parameterized({
+    'debug': (['-g'],), # Build with verbose debug flags with assertions enabled
+    'optimized': (['-Oz', '-sMINIMAL_RUNTIME'],), # Build with as optimized minimal flags as possible
+  })
+  def test_audio_worklet_singlethreaded(self, args):
+    # Deploy test files from test/ source directory over to the test working directory
+    for f in ['main.html', 'wasm-worklet-processor.js']:
+      shutil.copyfile(test_file(f'webaudio/singlethreaded_audioworklet/{f}'), f)
+    # Build and run the test
+    self.compile_btest([test_file('webaudio/singlethreaded_audioworklet/SimpleKernel.cc'), '-o', 'simple-kernel.wasmmodule.js',
+      '--bind', '-sBINARYEN_ASYNC_COMPILATION=0', '-sSINGLE_FILE=1', '-sEXPORTED_FUNCTIONS=_malloc', '-sAUDIO_WORKLET=2', '--post-js', test_file('webaudio/singlethreaded_audioworklet/export_sync_es6_module.js')] + args)
+    self.run_browser('main.html', '/report_result?0')

test/webaudio/singlethreaded_audioworklet/SimpleKernel.cc

@@ -0,0 +1,50 @@
+/**
+ * Copyright 2018 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+#include <emscripten.h>
+#include <stdint.h>
+#include <string.h>
+
+const unsigned kRenderQuantumFrames = 128;
+const unsigned kBytesPerChannel = kRenderQuantumFrames * sizeof(float);
+
+// The "kernel" is an object that processes a audio stream, which contains
+// one or more channels. It is supposed to obtain the frame data from an
+// |input|, process and fill an |output| of the AudioWorkletProcessor.
+//
+//       AudioWorkletProcessor Input(multi-channel, 128-frames)
+//                                 |
+//                                 V
+//                               Kernel
+//                                 |
+//                                 V
+//       AudioWorkletProcessor Output(multi-channel, 128-frames)
+//
+// In this implementation, the kernel operates based on 128-frames, which is
+// the render quantum size of Web Audio API.
+extern "C" void EMSCRIPTEN_KEEPALIVE SimpleKernel_Process(uintptr_t input_ptr, uintptr_t output_ptr,
+               unsigned channel_count) {
+  float* input_buffer = reinterpret_cast<float*>(input_ptr);
+  float* output_buffer = reinterpret_cast<float*>(output_ptr);
+
+  // Bypasses the data. By design, the channel count will always be the same
+  // for |input_buffer| and |output_buffer|.
+  for (unsigned channel = 0; channel < channel_count; ++channel) {
+    float* destination = output_buffer + channel * kRenderQuantumFrames;
+    float* source = input_buffer + channel * kRenderQuantumFrames;
+    memcpy(destination, source, kBytesPerChannel);
+  }
+}

test/webaudio/singlethreaded_audioworklet/export_sync_es6_module.js

@@ -0,0 +1,6 @@
+// Emscripten has a -sEXPORT_ES6=1 option to export the generated program as a 'Module'
+// object. However, that module is asynchronously loaded, which does not work well
+// for Audio Worklets, which require synchronous loading. So instead we manually
+// build the page without EXPORT_ES6, and just add an export here.
+
+export default Module;

test/webaudio/singlethreaded_audioworklet/main.html

@@ -0,0 +1,60 @@
+<!doctype html>
+<html lang="en-us">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+    <title>Emscripten-Generated Code</title>
+  </head>
+  <body>
+    <h1>Audio Worklet and WebAssembly</h1>
+    <p>A basic pattern to use Audio Worklet with WebAssembly. The
+      AudioWorkletProcessor simply bypasses (copies) the audio via the WebAssembly
+      function.</p>
+    <p>See
+      <a href="https://developer.chrome.com/blog/audio-worklet-design-pattern/"
+        target="_blank">Chrome Developers Article: Audio Worklet Design Pattern</a>
+      for more details.</p>
+
+    <div class="demo-box">
+      <button id="button-start" disabled>START</button>
+    </div>
+
+    <script type='text/javascript'>
+      // Copyright (c) 2018 The Chromium Authors. All rights reserved.
+      // Use of this source code is governed by a BSD-style license that can be
+      // found in the LICENSE file.
+
+      const audioContext = new AudioContext();
+
+      const startAudio = async (context) => {
+        await context.audioWorklet.addModule('wasm-worklet-processor.js');
+        const oscillator = new OscillatorNode(context);
+        const bypasser = new AudioWorkletNode(context, 'wasm-worklet-processor');
+        oscillator.connect(bypasser).connect(context.destination);
+        oscillator.start();
+      };
+
+      // A simple onLoad handler. It also handles user gesture to unlock the audio
+      // playback.
+      window.addEventListener('load', async () => {
+        const buttonEl = document.getElementById('button-start');
+        buttonEl.disabled = false;
+        buttonEl.addEventListener('click', async () => {
+          await startAudio(audioContext);
+          audioContext.resume();
+          buttonEl.disabled = true;
+          buttonEl.textContent = 'Playing...';
+
+          // report success
+          setTimeout(function() {
+            var xhr = new XMLHttpRequest();
+            xhr.open('GET', 'http://localhost:8888/report_result?0', true);
+            xhr.send();
+            audioContext.close(); // stop the audio output after 1 second, should be enough to verify output and not be annoying
+            window.close();
+          }, 1000);
+        }, false);
+      });
+    </script>
+  </body>
+</html>