Pull request to track the JACK Host implementation.

Major TODOs:

• [x] Store the data callback in the LocalProcessHandler for invocation from the audio thread
• [x] Process data from input ports
• [x] Accurately report if JACK is available
• [x] Use the error callback
• [x] Implement listing devices
• [x] Remove Arc Mutex wrapper around process callback when Sync requirement removal PR is merged in rust-jack (see https://github.com/RustAudio/rust-jack/pull/127)

More and more platforms are running audio with synchronous callback in a high-priority thread. That means that thread management should happen inside cpal, not in user code.

The blocking design of EventLoop should be replaced by some interface of registering callback. What's unfortunate is that we would need not only Send but also the 'static bound on the callback if it's implemented naively. Do we have anything more Rust-ic than callbacks (which is C-ish and often messy)?

It's obvious that we need different callbacks for different Hosts (assuming it get implemented), but should we support driving multiple streams with the same callback?

Close #278. I rushed for a buildable version so you can see it, there's still a lot of thing to do.

• [ ] Check for can_pause and optionally return an error
• [ ] Polymorphic struct versions of Traits will be explicitly !Sync, !Send
• [x] Take an additional error callback as described in https://github.com/tomaka/cpal/issues/268#issuecomment-508905225
• [ ] Update documentation
• [ ] Checkbox for ASIO backend so I don't miss it because it's without CI

As far as I can tell, cpal relies on no way on the COM mode being COINIT_MULTITHREADED.

So let's survive even if COM was already initialized in apartment-threaded mode (there is no such thing as single-threaded mode).

The refactor includes:

• The removal of most global state.
• Uses RAII for cleaner management of state transitions.
• Removes the hefty macros throughout the asio implementation.
• Adapts to the newly introduced Host API.

Support for ASIO has been gated behind an asio feature which is disabled by default. This is because the setup required for ASIO is fairly non-trivial and as it requires bindgen it introduces quite a few more dependencies.

A section has been added to the README describing in detail how to download, install and build CPAL with support for an ASIO host. Please see the more recent commit messages below for more details.

Closes #221.

cc @freesig cc @Boscop this is related to #156

Edit: Oh also, I've only been able to confirm the enumerate and beep examples work, though the beep example would distort heavily and cause my VM to crash. Originally I thought this might be my implementation, but I noticed this same behaviour happened in other software when running ASIO streams too. If anyone reading happens to have ASIO installed on a native system who could test the beep, record_wav and feedback examples that would be greatly appreciated!

Add a generic wasm-bindgen based WebAudio backend. Uses a sample scheduling strategy based on a set of interleaved AudioBufferSourceNode's which are rotated in and out as they finish playback. A quick port of the beep example appears to play stutter free on Firefox and Chrome.

This is another attempt to switch to the alsa crate fixing #346 (see also #308). I've attempted to change as little code as possible and keep consistency with the calls to the underlying library.

This change removes a lot of unsafe from cpal (though it still exists in the alsa crate itself) and enables RAII for the ALSA resources. It also fixes #377, allowing the use of the alsa crate and cpal in the same program.

This PR is a rebase of @ishitatsuyuki's work in #301. Originally opened at ishitatsuyuki/cpal#3 but closed in favour opening a new PR here.

Backends

• [x] null
• [x] ALSA
• [x] CoreAudio
• [x] WASAPI
• [x] Emscripten
• [x] ASIO

Other TODO

• [x] Polymorphic struct versions of Traits will be explicitly !Sync, !Send
• [x] Docs

ALSA multiple streams bug

Edit: This bug seems to have been addressed in the rebase.

After testing each of the examples with the ALSA backend on my Arch Linux system, I noticed that the feedback.rs example no longer works. No audio output was occurring and after some investigation it seems the output stream callback only seems to get called once. beep.rs and record_wav.rs both work fine, which leads me to wonder if there's an issue with the way multiple streams are being handled. feedback.rs also works fine on master, so this has likely been introduced in this PR.

@ishitatsuyuki does anything come to mind as a potential cause for this? I did notice that we're now spawning a whole OS thread per stream. I wonder if there's some kind of race going on in the stream loop? I might see if I can find anything about thread safety in the ALSA docs. I also wonder if we can reduce the number of threads necessary by just using a single thread on which all of the streams run, similar to the old EventLoop::run impl. If there is some race going on, maybe using a single thread for all streams would help to avoid this.

Also, I was reading through PortAudio's non-blocking ALSA code and noticed that, when spinning up a thread for a new stream, they also attempt to set the thread's priority to the highest possible. It might be worth seeing if there is some way we can do this too, though this work can probably wait for a follow-up PR.

This compile and runs fine with wasm32-unknown-unknown target, but doesn't produce any sound. Are you planning to support this target? Any idea why it doesn't work right now ?

This is an implementation of the planned changes described in #119.

For a quick overview of how the API has changed, check out the updated examples.

TODO:

• [x] Update API.
• [x] Update examples.
• ~Remove data_type field from Format? See here.~
• [x] Update docs.
• Update backends:
  • [x] null
  • [x] ALSA
  • [x] ASIO
  • [x] WASAPI
  • [x] CoreAudio
  • [x] Emscripten

Closes #119 Closes #260

This PR proposes an API for querying the supported min and max buffersizes of the device. I have managed to write successful test cases for ALSA, WASAPI, ASIO, CoreAudio, and Emscripten. I wanted to put this API out there for feedback before I start implementing all of the specific backends.

Note, the current version of winapi currently has no ability to query min/max buffersizes when using WASAPI. I have an open PR on winapi that can be found here that first needs to land until we can merge this work into CPAL.

This PR also removes the fn from(format: SupportedStreamConfig) -> SupportedStreamConfigRange function. Currently, it's only being used in wasapi/device line 529. I think we should aim to provide a better way of handling the supported formats returned by WASAPI rather than continue to modify this function to handle buffersizes.

Looking forward to hearing your feedback!

This is something that I've been struggling with because I'm used to working with audio streams broken by channels and sets of samples for each frame that represent a sample for each channel. With CPAL though, all that you get is a callback that effectively gives an array for individual samples devoid of any notion of channels save the number you have from the StreamConfig you used. At time of writing, I'm still not quite sure how to do multichannel audio. My best guess is that channel samples are interleaved but even if that's correct, the fact that I had to scour the docs and came back absolutely no wiser to this than when I went in is a major indication that this needs to be clarified in the docs if not for the audio pros who could assume how it works, than for the people like me who know a bit about low-level audio but are trying to learn to use an even more bare-metal library like this one.

While testing on Android, I ran into an issue with calling build_output_stream. In my project, I use symphonia to decode audio files and cpal to produce sound. Every time I played a new file, I would call build_output_stream.

This would stop working after 40 calls of the method. This error is thrown.

I have created a workaround fix where I call build_output_stream only once. However, I am concerned with the StreamConfig changing between audio files. Is there anything that can be done in cpal to fix this issue?

I have created a project that reproduces this issue and I have included the workaround I made. You will need cargo-apk installed to run it.

This is a quick hack for #730.

This way I can at least avoid worker thread busy-looping upon overrun condition (in general it's enough for me to teardown the stream in such case).

I believe a proper fix would require to:

• report this very condition as XRun
• let the user decide hwo to handle it

I'm working on an application using cpal over ALSA to continuously capture audio stream on Raspberry Pi. I use both RPI and PC for testing. Note: I'm using a version from master branch, as I need both i16 and i32 sample formats, with i32 not being supported in stable version.

Unfortunately I'm experiencing odd behavior upon capture overruns (which I trigger setting buffer size too low).

1. The most severe case is when poll() return EPOLERR which is not handled properly.

476794 1669022562.665530 poll([{fd=3, events=POLLIN}, {fd=5, events=POLLIN|POLLERR|POLLNVAL}], 2, 200) = 1 ([{fd=5, revents=POLLIN}])
476794 1669022562.666440 ioctl(5, SNDRV_PCM_IOCTL_STATUS_EXT,      0x7f6b10495f88) = 0
476794 1669022562.666532 ioctl(5, SNDRV_PCM_IOCTL_HWSYNC, 0x98) =      0
476794 1669022562.666577 ioctl(5, SNDRV_PCM_IOCTL_READI_FRAMES,      0x7f6b10496760) = 0
476794 1669022562.666707 poll([{fd=3, events=POLLIN}, {fd=5, events=POLLIN|POLLERR|POLLNVAL}], 2, 200) = 1 ([{fd=5, revents=POLLIN|POLLERR}])
476794 1669022562.669590 poll([{fd=3, events=POLLIN}, {fd=5, events=POLLIN|POLLERR|POLLNVAL}], 2, 200) = 1 ([{fd=5, revents=POLLIN|POLLERR}])
476794 1669022562.669765 poll([{fd=3, events=POLLIN}, {fd=5, events=POLLIN|POLLERR|POLLNVAL}], 2, 200) = 1 ([{fd=5, revents=POLLIN|POLLERR}])

And then I no longer get any more callbacks from cpal, but my application is eating up 100% of CPU core, as poll() is executed in a tight loop.

The problem is here:

https://github.com/RustAudio/cpal/blob/7776c6634a8e21e2a585358545141fe091c38320/src/host/alsa/mod.rs#L746-L753

This match doesn't recognize POLLIN|POLLERR and returns PollDescriptorsFlow::Continue, causing the worker thread to poll() again immediately, leading to a tight loop.

The problem seems obvious, I'll try to come with a pull request.

2. Another scenario is when the second ioctl call fails.

476936 1669022662.246764 poll([{fd=3, events=POLLIN}, {fd=5, events=POLLIN|POLLERR|POLLNVAL}], 2, 200) = 1 ([{fd=5, revents=POLLIN}])
476936 1669022662.247721 ioctl(5, SNDRV_PCM_IOCTL_STATUS_EXT, 0x7f70e2810f88) = 0
476936 1669022662.247884 ioctl(5, SNDRV_PCM_IOCTL_HWSYNC, 0x98) = -1 EPIPE (Broken pipe)
476936 1669022662.248019 ioctl(5, SNDRV_PCM_IOCTL_PREPARE, 0) = 0
476936 1669022662.248112 poll([{fd=3, events=POLLIN}, {fd=5, events=POLLIN|POLLERR|POLLNVAL}], 2, 200) = 0 (Timeout)
476936 1669022662.448722 write(1, "Die! A backend-specific error has occurred: `alsa::poll()` spuriously returned\n", 79) = 79
476936 1669022662.449074 poll([{fd=3, events=POLLIN}, {fd=5, events=POLLIN|POLLERR|POLLNVAL}], 2, 200) = 0 (Timeout)
476936 1669022662.649849 write(1, "Die! A backend-specific error has occurred: `alsa::poll()` spuriously returned\n", 79) = 79
476936 1669022662.650342 poll([{fd=3, events=POLLIN}, {fd=5, events=POLLIN|POLLERR|POLLNVAL}], 2, 200) = 0 (Timeout)
476936 1669022662.851166 write(1, "Die! A backend-specific error has occurred: `alsa::poll()` spuriously returned\n", 79) = 79

In this scenario I no longer get any data callbacks, instead I get error callback periodically (poll timeout).

I believe the problem is here:

https://github.com/RustAudio/cpal/blob/7776c6634a8e21e2a585358545141fe091c38320/src/host/alsa/mod.rs#L604-L609

The call to prepare() passes OK, but the stream is stopped - according to ALSA, this call changes the state to SND_PCM_STATE_PREPARED, there also need to be a call to start() to transition to SND_PCM_STATE_RUNNING and re-enable data flow.

I'm a bit confused here about what is the intended cpal behavior here:

• should I assume that stream is broken when my error callback is called for the first time, drop the Stream and create a new one? In such case I believe cpal should do some cleanup (e.g. stop the polling loop).
• should I assume that the error is temporary and the data flow will continue? In such case start() call is missing.

3. The third scenario is when ioctl(SNDRV_PCM_IOCTL_READI_FRAMES) fails with EPIPE:

476728 1669022521.635527 poll([{fd=3, events=POLLIN}, {fd=5, events=POLLIN|POLLERR|POLLNVAL}], 2, 200) = 1 ([{fd=5,        revents=POLLIN}])
476728 1669022521.636362 ioctl(5, SNDRV_PCM_IOCTL_STATUS_EXT, 0x7f8b2368af88) = 0
476728 1669022521.636521 ioctl(5, SNDRV_PCM_IOCTL_HWSYNC, 0x98) = 0
476728 1669022521.636681 ioctl(5, SNDRV_PCM_IOCTL_READI_FRAMES, 0x7f8b2368b760) = -1 EPIPE (Broken pipe)
476728 1669022521.636777 write(1, "Die! A backend-specific error has occurred: ALSA function 'snd_pcm_readi' failed with error 'EPIPE: Broken pipe'\n", 113) = 113
476728 1669022521.636823 poll([{fd=3, events=POLLIN}, {fd=5, events=POLLIN|POLLERR|POLLNVAL}], 2, 200) = 1 ([{fd=5,        revents=POLLIN|POLLERR}])
476728 1669022521.636860 poll([{fd=3, events=POLLIN}, {fd=5, events=POLLIN|POLLERR|POLLNVAL}], 2, 200) = 1 ([{fd=5,        revents=POLLIN|POLLERR}])
476728 1669022521.636892 poll([{fd=3, events=POLLIN}, {fd=5, events=POLLIN|POLLERR|POLLNVAL}], 2, 200) = 1 ([{fd=5,        revents=POLLIN|POLLERR}])

Here, the error from process_input() is properly delivered to my error callback, but then we enter the tight loop scenario, due to POLLERR not being recognized.

Running the example multiple times always produces the first recording I made.

Macbook M1, MacOS Montery, rustc v1.65

To reproduce:

# run the example (and say something)
cargo run --example record_wav
# listen to the result
open recorded.wav
# delete the recording
rm recorded.wav
# run the example again (and say something else)
cargo run --example record_wav
# listen to the result
open recorded.wav

No matter how many times I remove the recording and run the example, I get the very first recorded audio.

I followed the readme in the examples/wasm-beep folder, which said to run npm install then npm start. After running npm start it seems to mostly work, browser pops up to the page with the play and stop buttons, but there's an error in the terminal where I ran npm start:

ERROR in ./index.js
Module not found: Error: Can't resolve './pkg' in 'C:\Users\David\Projects\personal\rust-learn\cpal\examples\wasm-beep'

And no sound is heard when pressing the play button. I can't tell what pkg is supposed to be, or where to get it, so maybe something missing in the instructions? Or something else changed.