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