1# CPAL - Cross-Platform Audio Library
2
3[![Actions Status](https://github.com/RustAudio/cpal/workflows/cpal/badge.svg)](https://github.com/RustAudio/cpal/actions)
4 [![Crates.io](https://img.shields.io/crates/v/cpal.svg)](https://crates.io/crates/cpal) [![docs.rs](https://docs.rs/cpal/badge.svg)](https://docs.rs/cpal/)
5
6Low-level library for audio input and output in pure Rust.
7
8This library currently supports the following:
9
10- Enumerate supported audio hosts.
11- Enumerate all available audio devices.
12- Get the current default input and output devices.
13- Enumerate known supported input and output stream formats for a device.
14- Get the current default input and output stream formats for a device.
15- Build and run input and output PCM streams on a chosen device with a given stream format.
16
17Currently, supported hosts include:
18
19- Linux (via ALSA or JACK)
20- Windows (via WASAPI by default, see ASIO instructions below)
21- macOS (via CoreAudio)
22- iOS (via CoreAudio)
23- Android (via Oboe)
24- Emscripten
25
26Note that on Linux, the ALSA development files are required. These are provided
27as part of the `libasound2-dev` package on Debian and Ubuntu distributions and
28`alsa-lib-devel` on Fedora.
29
30## Compiling for Web Assembly
31
32If 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.
33
34## Feature flags for audio backends
35
36Some audio backends are optional and will only be compiled with a [feature flag](https://doc.rust-lang.org/cargo/reference/features.html).
37
38- JACK (on Linux): `jack`
39- ASIO (on Windows): `asio`
40
41## ASIO on Windows
42
43[ASIO](https://en.wikipedia.org/wiki/Audio_Stream_Input/Output) is an audio
44driver protocol by Steinberg. While it is available on multiple operating
45systems, it is most commonly used on Windows to work around limitations of
46WASAPI including access to large numbers of channels and lower-latency audio
47processing.
48
49CPAL allows for using the ASIO SDK as the audio host on Windows instead of
50WASAPI. To do so, follow these steps:
51
521. **Download the ASIO SDK** `.zip` from [this
53   link](https://www.steinberg.net/en/company/developers.html). The version as
54   of writing this is 2.3.1.
552. Extract the files and place the directory somewhere you are happy for it to stay
56   (e.g. `~/.asio`).
573. Assign the full path of the directory (that contains the `readme`, `changes`,
58   `ASIO SDK 2.3` pdf, etc) to the `CPAL_ASIO_DIR` environment variable. This is
59   necessary for the `asio-sys` build script to build and bind to the SDK.
604. `bindgen`, the library used to generate bindings to the C++ SDK, requires
61   clang. **Download and install LLVM** from
62   [here](http://releases.llvm.org/download.html) under the "Pre-Built Binaries"
63   section. The version as of writing this is 7.0.0.
645. Add the LLVM `bin` directory to a `LIBCLANG_PATH` environment variable. If
65   you installed LLVM to the default directory, this should work in the command
66   prompt:
67   ```
68   setx LIBCLANG_PATH "C:\Program Files\LLVM\bin"
69   ```
706. If you don't have any ASIO devices or drivers available, you can [**download
71   and install ASIO4ALL**](http://www.asio4all.org/). Be sure to enable the
72   "offline" feature during installation despite what the installer says about
73   it being useless.
747. **Loading VCVARS**. `rust-bindgen` uses the C++ tool-chain when generating
75   bindings to the ASIO SDK. As a result, it is necessary to load some
76   environment variables in the command prompt that we used to build our project.
77   On 64-bit machines run:
78   ```
79   "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64
80   ```
81   On 32-bit machines run:
82   ```
83   "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" x86
84   ```
85   Note that, depending on your version of Visual Studio, this script might be
86   in a slightly different location.
878. Select the ASIO host at the start of our program with the following code:
88
89   ```rust
90   let host;
91   #[cfg(target_os = "windows")]
92   {
93       host = cpal::host_from_id(cpal::HostId::Asio).expect("failed to initialise ASIO host");
94   }
95   ```
96
97   If you run into compilations errors produced by `asio-sys` or `bindgen`, make
98   sure that `CPAL_ASIO_DIR` is set correctly and try `cargo clean`.
999. Make sure to enable the `asio` feature when building CPAL:
100
101   ```
102   cargo build --features "asio"
103   ```
104
105   or if you are using CPAL as a dependency in a downstream project, enable the
106   feature like this:
107
108   ```toml
109   cpal = { version = "*", features = ["asio"] }
110   ```
111
112In the future we would like to work on automating this process to make it
113easier, but we are not familiar enough with the ASIO license to do so yet.
114
115*Updated as of ASIO version 2.3.3.*
116