AudioWorklet based Host for web when Wasm atomics are enabled #958

kettle11 · 2025-03-01T19:23:10Z

This pull request adds an optional feature-flagged Host that uses AudioWorklet on web when the atomics feature is enabled. When the web_audio_worklet and wasm-bindgen features are enabled and nightly Rust is compiled with the atomics flag enabled the WebAudioWorklet Host is available.

AudioWorklet should be lower latency, lower overhead, and less prone to jank. This implementations works pretty much the same as a native audio thread, allowing the implementation to be simpler than the existing WebAudio Host implementation.

To used shared memory it's also required (for security reasons) that the server hosting the Wasm to be configured with the correct CORS headers. I've added an example that shows how to build with the correct Rust flags and how to set the Cors headers in a test environment.

So far I've tested this in Chrome, Safari, and Firefox with the beep example and it seems to be working fine.

Edit: I'm not sure why a past merged PR shows up in Github's listed commits, but it seems to have no impact on this PR.

…m platforms

roderickvd · 2025-08-05T21:22:28Z

Very nice addition! This is a big one, so I'm gonna first trigger a Copilot review to walk through major points, if any, then do a further code review.

Apologies for the late response - new collaborator here and grooming through the backlog now.

Copilot

Pull Request Overview

This pull request adds AudioWorklet support for web audio in CPAL, providing a lower-latency, lower-overhead alternative to the existing WebAudio host when WebAssembly atomics are enabled. The implementation leverages shared memory between the main thread and audio worklet thread, allowing for more efficient audio processing similar to native platforms.

Introduces a new web_audio_worklet feature flag and host implementation
Adds JavaScript worklet processor code that interfaces with WebAssembly
Provides an example demonstrating the setup requirements and usage

Reviewed Changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/platform/mod.rs	Adds conditional compilation for WebAudioWorklet host alongside existing WebAudio host
src/host/web_audio_worklet/mod.rs	Core implementation of the AudioWorklet-based host with stream management
src/host/web_audio_worklet/worklet.js	JavaScript AudioWorkletProcessor that interfaces with WASM audio processing
src/host/web_audio_worklet/dependent_module.rs	Utility for dynamically loading JavaScript modules in AudioWorklet context
src/host/mod.rs	Adds conditional module inclusion for web_audio_worklet
examples/web-audio-worklet-beep/*	Complete example showing usage with required configuration
Cargo.toml	Adds web_audio_worklet feature with necessary web-sys dependencies

Comments suppressed due to low confidence (1)

src/host/web_audio_worklet/worklet.js:1

[nitpick] The class name WasmProcessor is generic and could conflict with other WASM processors. Consider using a more specific name like CpalWasmProcessor to match the registered processor name.

registerProcessor("CpalProcessor", class WasmProcessor extends AudioWorkletProcessor {

src/host/web_audio_worklet/dependent_module.rs

src/host/web_audio_worklet/mod.rs

Co-authored-by: Copilot <[email protected]>

…example

kettle11 · 2025-08-07T05:16:22Z

Thanks for following up!

I applied some of Copilot's suggestions and also realized that some files needed to build the example were missing so I fixed that as well. Let me know if anything further is needed.

roderickvd

This looks very, very nice. Super to see such an exhaustive example too.

roderickvd · 2025-08-07T20:54:31Z

Cargo.toml

 asio = ["asio-sys", "num-traits"] # Only available on Windows. See README for setup instructions.
 oboe-shared-stdcxx = ["oboe/shared-stdcxx"] # Only available on Android. See README for what it does.
+# Only available on web when atomics are enabled. See README for what it does.
+web_audio_worklet = [


Please document the feature flag in the README.

roderickvd · 2025-08-07T20:54:50Z

Cargo.toml

@@ -65,6 +76,7 @@ web-sys = { version = "0.3.35", features = [ "AudioContext", "AudioContextOption

 [target.'cfg(all(target_arch = "wasm32", target_os = "unknown"))'.dependencies]
 wasm-bindgen = { version = "0.2.58", optional = true }
+wasm-bindgen-futures = {version = "0.4.33", optional = true}


Style: misses spaces between the curly braces.

roderickvd · 2025-08-07T20:55:20Z

examples/web-audio-worklet-beep/.cargo/config.toml

+rustflags = ["-C", "target-feature=+atomics"]
+
+[unstable]
+build-std = ["std", "panic_abort"]


Does it have to abort? Could we leave that choice to the user?

roderickvd · 2025-08-07T20:56:04Z

.gitignore

-.DS_Store
-recorded.wav
-rls*.log
+/target


Why does it give a diff for the first six lines? (don't bother too much, just wondering)

roderickvd · 2025-08-07T20:56:47Z

examples/web-audio-worklet-beep/Cargo.toml

@@ -0,0 +1,40 @@
+[package]
+name = "web-audio-worklet-beep"


Feel free to put your name as author.

roderickvd · 2025-08-07T21:03:07Z

src/host/web_audio_worklet/dependent_module.rs

+//
+// Copyright (c) 2017-2024 The wasm-bindgen Developers
+//
+// This file incorporates code from the above source under the terms of those licenses.


We should be explicit that we opt for the Apache license, since that's what's cpal itself is licensed under.

roderickvd · 2025-08-07T21:04:40Z

src/host/web_audio_worklet/mod.rs

+const SUPPORTED_SAMPLE_FORMAT: SampleFormat = SampleFormat::F32;
+
+impl Host {
+    pub fn new() -> Result<Self, crate::HostUnavailable> {


Why have a crate::JostUnavailable error type when it seems infallible?

roderickvd · 2025-08-07T21:05:22Z

src/host/web_audio_worklet/mod.rs

+pub type SupportedInputConfigs = ::std::vec::IntoIter<SupportedStreamConfigRange>;
+pub type SupportedOutputConfigs = ::std::vec::IntoIter<SupportedStreamConfigRange>;
+
+const MIN_CHANNELS: u16 = 1;


You can use the cpal::ChannelCount type alias instead of u16.

roderickvd · 2025-08-07T21:07:16Z

src/host/web_audio_worklet/mod.rs

+
+        let audio_context = web_sys::AudioContext::new_with_context_options(&stream_opts).map_err(
+            |err| -> BuildStreamError {
+                let description = format!("{:?}", err);


Does this pass clippy? Preferred syntax has become format!("{err:?}").

roderickvd · 2025-08-07T21:34:50Z

src/platform/mod.rs

@@ -662,7 +662,15 @@ mod platform_impl {
        SupportedOutputConfigs as WebAudioSupportedOutputConfigs,
    };

-    impl_platform_host!(WebAudio webaudio "WebAudio");
+    #[cfg(feature = "web_audio_worklet")]


Could you clarify this? Instead of doing impl_platform_host!, importing the relevant webaudio bits yourself when the web_audio_worklet feature is enabled?

kettle11 added 4 commits February 13, 2024 17:50

Fix crash on Web / Wasm when 'atomics' flag is enabled

3f72836

AudioWorklet based host for when atomics are enabled

58ee0ed

Merge branch 'master' of https://github.com/kettle11/cpal

b64e24b

Adjust cargo.toml to avoid adding unnecessary dependencies on non-Was…

0469502

…m platforms

kettle11 mentioned this pull request Apr 25, 2025

webaudio backend that uses AudioWorkletNode #663

Open

roderickvd requested a review from Copilot August 5, 2025 21:22

roderickvd added enhancement platform - web host - webaudio labels Aug 5, 2025

Copilot AI reviewed Aug 5, 2025

View reviewed changes

kettle11 and others added 5 commits August 7, 2025 00:18

Apply suggestion from @Copilot

314c9e4

Co-authored-by: Copilot <[email protected]>

Apply suggestion from @Copilot

991d86e

Co-authored-by: Copilot <[email protected]>

Apply suggestion from @Copilot

60733ab

Co-authored-by: Copilot <[email protected]>

Adapted copilot recommendation to remove eval

3d7e31f

Exempt from .gitignore .cargo/config.toml necessary for AudioWorklet …

57f28e1

…example

roderickvd requested changes Aug 7, 2025

View reviewed changes

AudioWorklet based Host for web when Wasm atomics are enabled #958

Are you sure you want to change the base?

AudioWorklet based Host for web when Wasm atomics are enabled #958

Uh oh!

Conversation

kettle11 commented Mar 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

roderickvd commented Aug 5, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kettle11 commented Aug 7, 2025

Uh oh!

roderickvd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kettle11 commented Mar 1, 2025 •

edited

Loading