You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -27,30 +27,75 @@ Note that on Linux, the ALSA development files are required. These are provided
27
27
as part of the `libasound2-dev` package on Debian and Ubuntu distributions and
28
28
`alsa-lib-devel` on Fedora.
29
29
30
-
## Compiling for Web Assembly
30
+
## Compiling for WebAssembly
31
31
32
-
If you are interested in using CPAL with WASM, please see [this guide](https://github.com/RustAudio/cpal/wiki/Setting-up-a-new-CPAL-WASM-project) in our Wiki which walks through setting up a new project from scratch.
32
+
If you are interested in using CPAL with WebAssembly, please see [this guide](https://github.com/RustAudio/cpal/wiki/Setting-up-a-new-CPAL-WASM-project) in our Wiki which walks through setting up a new project from scratch. Some of the examples in this repository also provide working configurations that you can use as reference.
33
33
34
-
## Feature flags for audio backends
34
+
## Optional Features
35
35
36
-
Some audio backends are optional and will only be compiled with a [feature flag](https://doc.rust-lang.org/cargo/reference/features.html).
36
+
CPAL provides the following optional features:
37
37
38
-
- JACK (on Linux): `jack`
39
-
- ASIO (on Windows): `asio`
40
-
- AudioWorklet (on Web): `audioworklet`
38
+
### `asio`
41
39
42
-
For AudioWorklet backend usage see the README for the `audioworklet-beep` example.
40
+
**Platform:** Windows
43
41
44
-
## ASIO on Windows
42
+
Enables the ASIO (Audio Stream Input/Output) backend. ASIO provides low-latency audio I/O by bypassing the Windows audio stack.
43
+
44
+
**Requirements:**
45
+
- ASIO drivers for your audio device
46
+
- LLVM/Clang for build-time bindings generation
47
+
48
+
**Setup:** See the [ASIO setup guide](#asio-on-windows) below for detailed installation instructions.
Enables the JACK (JACK Audio Connection Kit) backend. JACK is an audio server providing low-latency connections between applications and audio hardware.
55
+
56
+
**Requirements:**
57
+
- JACK server and client libraries must be installed on the system
58
+
59
+
**Usage:** See the [beep example](examples/beep.rs) for selecting the JACK host at runtime.
60
+
61
+
**Note:** While JACK is available on Windows and macOS, CPAL's JACK backend is currently only implemented for Linux and BSD systems. On other platforms, use the native backends (WASAPI/ASIO for Windows, CoreAudio for macOS).
Enables the Audio Worklet backend for lower-latency web audio processing compared to the default Web Audio API backend.
80
+
81
+
**Requirements:**
82
+
- The `wasm-bindgen` feature (automatically enabled)
83
+
- Build with atomics support: `RUSTFLAGS="-C target-feature=+atomics,+bulk-memory,+mutable-globals"`
84
+
- Web server must send Cross-Origin headers for SharedArrayBuffer support
85
+
86
+
**Setup:** See the `audioworklet-beep` example README for complete setup instructions.
87
+
88
+
**Note:** Audio Worklet provides better performance than the default Web Audio API by running audio processing on a separate thread.
89
+
90
+
### `custom`
91
+
92
+
**Platform:** All platforms
45
93
46
-
[ASIO](https://en.wikipedia.org/wiki/Audio_Stream_Input/Output) is an audio
47
-
driver protocol by Steinberg. While it is available on multiple operating
48
-
systems, it is most commonly used on Windows to work around limitations of
49
-
WASAPI including access to large numbers of channels and lower-latency audio
50
-
processing.
94
+
Enables support for user-defined custom host implementations, allowing integration with audio systems not natively supported by CPAL.
51
95
52
-
CPAL allows for using the ASIO SDK as the audio host on Windows instead of
53
-
WASAPI.
96
+
**Usage:** See `examples/custom.rs` for implementation details.
97
+
98
+
## ASIO on Windows
54
99
55
100
### Locating the ASIO SDK
56
101
@@ -64,78 +109,81 @@ The build script will try to find the ASIO SDK by following these steps in order
64
109
65
110
In an ideal situation you don't need to worry about this step.
66
111
67
-
### Preparing the build environment
112
+
### Preparing the Build Environment
113
+
114
+
1.**Install LLVM/Clang**: `bindgen`, the library used to generate bindings to the C++ SDK, requires clang. Download and install LLVM from <http://releases.llvm.org/download.html> under the "Pre-Built Binaries" section.
68
115
69
-
1.`bindgen`, the library used to generate bindings to the C++ SDK, requires
70
-
clang. **Download and install LLVM** from
71
-
[here](http://releases.llvm.org/download.html) under the "Pre-Built Binaries"
72
-
section. The version as of writing this is 17.0.1.
73
-
2. Add the LLVM `bin` directory to a `LIBCLANG_PATH` environment variable. If
74
-
you installed LLVM to the default directory, this should work in the command
75
-
prompt:
116
+
2.**Set LIBCLANG_PATH**: Add the LLVM `bin` directory to a `LIBCLANG_PATH` environment variable. If you installed LLVM to the default directory, this should work in the command prompt:
76
117
```
77
118
setx LIBCLANG_PATH "C:\Program Files\LLVM\bin"
78
119
```
79
-
3. If you don't have any ASIO devices or drivers available, you can [**download
80
-
and install ASIO4ALL**](http://www.asio4all.org/). Be sure to enable the
81
-
"offline" feature during installation despite what the installer says about
82
-
it being useless.
83
-
4. Our build script assumes that Microsoft Visual Studio is installed if the host OS for compilation is Windows. The script will try to find `vcvarsall.bat`
84
-
and execute it with the right host and target machine architecture regardless of the Microsoft Visual Studio version.
85
-
If there are any errors encountered in this process which is unlikely,
86
-
you may find the `vcvarsall.bat` manually and execute it with your machine architecture as an argument.
87
-
The script will detect this and skip the step.
88
-
89
-
A manually executed command example for 64 bit machines:
90
120
121
+
3.**Install ASIO Drivers** (optional for testing): If you don't have any ASIO devices or drivers available, you can download and install ASIO4ALL from <http://www.asio4all.org/>. Be sure to enable the "offline" feature during installation.
122
+
123
+
4.**Visual Studio**: The build script assumes Microsoft Visual Studio is installed. It will try to find `vcvarsall.bat` and execute it with the right host and target architecture. If needed, you can manually execute it:
For more information see the [vcvarsall.bat documentation](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line).
94
128
95
-
For more information please refer to the documentation of [`vcvarsall.bat``](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-160#vcvarsall-syntax).
129
+
### Using ASIO in Your Application
96
130
97
-
5. Select the ASIO host at the start of our program with the following code:
131
+
1.**Enable the feature** in your `Cargo.toml`:
132
+
```toml
133
+
cpal = { version = "*", features = ["asio"] }
134
+
```
98
135
136
+
2.**Select the ASIO host** in your code:
99
137
```rust
100
-
lethost;
101
-
#[cfg(target_os ="windows")]
102
-
{
103
-
host=cpal::host_from_id(cpal::HostId::Asio).expect("failed to initialise ASIO host");
104
-
}
138
+
lethost=cpal::host_from_id(cpal::HostId::Asio)
139
+
.expect("failed to initialise ASIO host");
105
140
```
106
141
107
-
If you run into compilations errors produced by `asio-sys` or `bindgen`, make
108
-
sure that `CPAL_ASIO_DIR` is set correctly and try `cargo clean`.
142
+
### Troubleshooting
109
143
110
-
6. Make sure to enable the `asio` feature when building CPAL:
144
+
If you encounter compilation errors from `asio-sys` or `bindgen`:
145
+
- Verify `CPAL_ASIO_DIR` is set correctly
146
+
- Try running `cargo clean`
147
+
- Ensure LLVM/Clang is properly installed and `LIBCLANG_PATH` is set
111
148
112
-
```
113
-
cargo build --features "asio"
114
-
```
149
+
### Cross-Compilation
115
150
116
-
or if you are using CPAL as a dependency in a downstream project, enable the
117
-
feature like this:
151
+
When Windows is the host and target OS, the build script supports all cross-compilation targets supported by the MSVC compiler.
118
152
119
-
```toml
120
-
cpal = { version = "*", features = ["asio"] }
121
-
```
153
+
It is also possible to compile Windows applications with ASIO support on Linux and macOS using the MinGW-w64 toolchain.
122
154
123
-
_Updated as of ASIO version 2.3.3._
155
+
**Requirements:**
156
+
- Include the MinGW-w64 include directory in your `CPLUS_INCLUDE_PATH` environment variable
157
+
- Include the LLVM include directory in your `CPLUS_INCLUDE_PATH` environment variable
124
158
125
-
### Cross compilation
159
+
**Example for macOS** (targeting `x86_64-pc-windows-gnu` with `mingw-w64` installed via brew):
When Windows is the host and the target OS, the build script of `asio-sys` supports all cross compilation targets
128
-
which are supported by the MSVC compiler. An exhaustive list of combinations could be found [here](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-160#vcvarsall-syntax) with the addition of undocumented `arm64`, `arm64_x86`, `arm64_amd64` and `arm64_arm` targets. (5.11.2023)
164
+
## Troubleshooting
129
165
130
-
It is also possible to compile Windows applications with ASIO support on Linux and macOS.
166
+
### No Default Device Available
131
167
132
-
For both platforms the common way to do this is to use the [MinGW-w64](https://www.mingw-w64.org/) toolchain.
168
+
If you receive errors about no default input or output device:
133
169
134
-
Make sure that you have included the `MinGW-w64` include directory in your `CPLUS_INCLUDE_PATH` environment variable.
135
-
Make sure that LLVM is installed and include directory is also included in your `CPLUS_INCLUDE_PATH` environment variable.
170
+
-**Linux/ALSA:** Ensure your user is in the `audio` group and that ALSA is properly configured
171
+
-**Linux/PulseAudio:** Check that PulseAudio is running: `pulseaudio --check`
172
+
-**Windows:** Verify your audio device is enabled in Sound Settings
173
+
-**macOS:** Check System Preferences > Sound for available devices
174
+
-**Mobile (iOS/Android):** Ensure your app has microphone/audio permissions
136
175
137
-
Example for macOS for the target of `x86_64-pc-windows-gnu` where `mingw-w64` is installed via brew:
0 commit comments