Add support for Web Audio (Emscripten/WebAssembly)

.github/workflows/cmake.yml

@@ -25,6 +25,12 @@ jobs:
               -DPA_USE_ASIO=ON
               -DPA_USE_JACK=OFF
               -DASIO_SDK_ZIP_PATH=asiosdk.zip
+          - name: Ubuntu Emscripten
+            os: ubuntu-latest
+            vcpkg_triplet: wasm32-emscripten
+            cmake_generator: "Unix Makefiles"
+            cmake_options:
+              -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE="$EMSDK/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake"
           - name: Windows MSVC
             os: windows-latest
             vcpkg_triplet: x64-windows
@@ -72,6 +78,11 @@ jobs:
         sudo apt-get update
         sudo apt-get install libasound2-dev libpulse-dev libsndio-dev ${{ matrix.dependencies_extras }}
       if: matrix.os == 'ubuntu-latest'
+    - name: Set up Emscripten SDK
+      uses: mymindstorm/setup-emsdk@v14
+      with:
+        version: '3.1.55'
+      if: startsWith(matrix.vcpkg_triplet, 'wasm32-')
     - name: "Set up ASIO SDK cache [Windows/MinGW]"
       uses: actions/cache@v2
       if: matrix.asio_sdk_cache_path != null

CMakeLists.txt

@@ -32,8 +32,10 @@ if(PA_WARNINGS_ARE_ERRORS)
             # Do *NOT* add warnings to this list. Instead, fix your code so that it doesn't produce the warning.
             # TODO: fix the offending code so that we don't have to exclude specific warnings anymore.
             -Wno-error=deprecated-declarations  # https://github.com/PortAudio/portaudio/issues/213 https://github.com/PortAudio/portaudio/issues/641
-            -Wno-error=stringop-overflow
         )
+        if (NOT EMSCRIPTEN)
+            add_compile_options(-Wno-error=stringop-overflow)
+        endif()
         if (CMAKE_C_COMPILER_ID MATCHES "Clang")
              # Don't fail on older clang versions that don't recognize the latest warnings in the list above.
              # Note that unrecognized warning options are not a fatal error on GCC, and in fact, GCC will choke on this option. Hence the conditional.
@@ -399,6 +401,38 @@ elseif(UNIX)
       set(PKGCONFIG_CFLAGS "${PKGCONFIG_CFLAGS} -DPA_USE_SNDIO=1")
       set(PKGCONFIG_REQUIRES_PRIVATE "${PKGCONFIG_REQUIRES_PRIVATE} sndio")
     endif()
+
+    if(EMSCRIPTEN)
+      option(PA_USE_WEBAUDIO "Enable support for Web Audio" ON)
+
+      if(PA_USE_WEBAUDIO)
+        target_sources(PortAudio PRIVATE
+          src/hostapi/webaudio/pa_webaudio.c
+        )
+        target_compile_definitions(PortAudio PUBLIC PA_USE_WEBAUDIO=1)
+        target_compile_options(PortAudio PUBLIC -pthread)
+        target_link_options(PortAudio PUBLIC
+          -sAUDIO_WORKLET
+          -sWASM_WORKERS
+          -sEXPORTED_RUNTIME_METHODS=emscriptenGetAudioObject
+        )
+
+        option(PA_WEBAUDIO_ASYNCIFY "Build with -sASYNCIFY and use async operations. Recommended when intending to call PortAudio from the main thread to avoid blocking." ON)
+        if(PA_WEBAUDIO_ASYNCIFY)
+          target_compile_definitions(PortAudio PUBLIC PA_WEBAUDIO_ASYNCIFY=1)
+          target_link_options(PortAudio PUBLIC
+            -sASYNCIFY
+            -sASYNCIFY_IMPORTS=emscripten_asm_const_int
+          )
+        endif()
+        set(PKGCONFIG_CFLAGS "${PKGCONFIG_CFLAGS} -DPA_USE_WEBAUDIO=1")
+      endif()
+
+      # This makes it easy to run the examples. The default output format is .js
+      # and is set in the Emscripten toolchain file, so it cannot be overriden
+      # from the command-line with -DCMAKE_EXECUTABLE_SUFFIX.
+      set(CMAKE_EXECUTABLE_SUFFIX ".html")
+    endif()
   endif()
 endif()
 

examples/CMakeLists.txt

@@ -10,6 +10,10 @@ macro(add_example appl_name)
   if(WIN32)
     set_property(TARGET ${appl_name} APPEND_STRING PROPERTY COMPILE_DEFINITIONS _CRT_SECURE_NO_WARNINGS)
   endif()
+  if(EMSCRIPTEN AND NOT PA_WEBAUDIO_ASYNCIFY)
+    target_compile_options(${appl_name} PUBLIC -pthread)
+    target_link_options(${appl_name} PUBLIC -pthread -sPROXY_TO_PTHREAD)
+  endif()
 endmacro()
 
 macro(add_example_cpp appl_name)
@@ -19,6 +23,10 @@ macro(add_example_cpp appl_name)
   if(WIN32)
     set_property(TARGET ${appl_name} APPEND_STRING PROPERTY COMPILE_DEFINITIONS _CRT_SECURE_NO_WARNINGS)
   endif()
+  if(EMSCRIPTEN AND NOT PA_WEBAUDIO_ASYNCIFY)
+    target_compile_options(${appl_name} PUBLIC -pthread)
+    target_link_options(${appl_name} PUBLIC -pthread -sPROXY_TO_PTHREAD)
+  endif()
 endmacro()
 
 add_example(pa_devs)

src/hostapi/webaudio/README.md

@@ -0,0 +1,33 @@
+# Web Audio API
+
+To build PortAudio for the web, make sure to have [the Emscripten SDK](https://emscripten.org/docs/getting_started/downloads.html) installed and on your `PATH`, then run from the repository's top-level directory:
+
+```sh
+emcmake cmake -B build
+cmake --build build
+```
+
+To build the examples, use
+
+```sh
+emcmake cmake -B build -DPA_BUILD_EXAMPLES=ON
+cmake --build build
+```
+
+> [!TIP]
+> By default PortAudio will be built with `-sASYNCIFY`. This makes it safe to be called from the main thread, but also introduces overhead and potentially other issues when the application already uses other asynchronous operations. PortAudio can also be built without Asyncify (i.e. using synchronous/blocking operations) by setting `-DPA_WEBAUDIO_ASYNCIFY=OFF`, in that case it is recommended to call PortAudio from a worker thread to avoid blocking the main thread (which may result in locking up the UI or in worse cases deadlock the application, e.g. if PortAudio waits for user interaction, as it does during `Pa_StartStream`). This can be done automatically using `-sPROXY_TO_PTHREAD`.
+
+> [!TIP]
+> For debug logging, set `-DPA_ENABLE_DEBUG_OUTPUT=ON`
+
+You can now run the examples in a local browser using `emrun`, for example
+
+```sh
+emrun build/examples/paex_sine.html
+```
+
+> [!IMPORTANT]
+> Due to browser policies you have to interact with the site at least once (e.g. by clicking anywhere) before audio contexts can be started. `Pa_StartStream` will (from the C/C++ perspective) block until this happens. Under the hood this is handled asynchronously using Asyncify.
+
+> [!TIP]
+> You can customize the browser e.g. by setting `--browser=firefox` and also pass arguments to the browser with `--browser-args`