{"id":13603573,"url":"https://github.com/rustaudio/cpal","last_synced_at":"2026-02-18T22:07:05.085Z","repository":{"id":24468956,"uuid":"27872570","full_name":"RustAudio/cpal","owner":"RustAudio","description":"Cross-platform audio I/O library in pure Rust","archived":false,"fork":false,"pushed_at":"2025-04-17T01:53:37.000Z","size":9076,"stargazers_count":3030,"open_issues_count":247,"forks_count":416,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-05-06T16:13:48.975Z","etag":null,"topics":["audio","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RustAudio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-12-11T13:23:58.000Z","updated_at":"2025-05-06T09:42:16.000Z","dependencies_parsed_at":"2023-10-17T11:52:06.789Z","dependency_job_id":"ee9f5134-33d2-437f-bf01-768bb1218f5a","html_url":"https://github.com/RustAudio/cpal","commit_stats":{"total_commits":723,"total_committers":138,"mean_commits":5.239130434782608,"dds":0.7565698478561549,"last_synced_commit":"d4ba28df733fbb5e5a4d78f7a8fd789206a44cbe"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RustAudio%2Fcpal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RustAudio%2Fcpal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RustAudio%2Fcpal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RustAudio%2Fcpal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RustAudio","download_url":"https://codeload.github.com/RustAudio/cpal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253990456,"owners_count":21995773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","rust"],"created_at":"2024-08-01T19:00:25.636Z","updated_at":"2026-02-18T22:07:05.070Z","avatar_url":"https://github.com/RustAudio.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# CPAL - Cross-Platform Audio Library\n\n[![Actions Status](https://github.com/RustAudio/cpal/workflows/cpal/badge.svg)](https://github.com/RustAudio/cpal/actions)\n[![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/)\n\nLow-level library for audio input and output in pure Rust.\n\n## Minimum Supported Rust Version (MSRV)\n\nThe minimum Rust version required depends on which audio backend and features you're using, as each platform has different dependencies:\n\n- **AAudio (Android):** Rust **1.82** (due to `ndk` crate requirements)\n- **ALSA (Linux/BSD):** Rust **1.82** (due to `alsa-sys` crate requirements)\n- **CoreAudio (macOS/iOS):** Rust **1.80** (due to `coreaudio-rs` crate requirements)\n- **JACK (Linux/BSD/macOS/Windows):** Rust **1.82** (due to `jack` crate requirements)\n- **WASAPI/ASIO (Windows):** Rust **1.82** (due to `windows` crate requirements)\n- **WASM (`wasm32-unknown`):** Rust **1.82** (due to `gloo` crate requirements)\n- **WASM (`wasm32-wasip1`):** Rust **1.78** (target stabilized in 1.78)\n- **WASM (`audioworklet`):** Rust **nightly** (requires `-Zbuild-std` for atomics support)\n\n## Supported Platforms\n\nThis library currently supports the following:\n\n- Enumerate supported audio hosts.\n- Enumerate all available audio devices.\n- Get the current default input and output devices.\n- Enumerate known supported input and output stream formats for a device.\n- Get the current default input and output stream formats for a device.\n- Build and run input and output PCM streams on a chosen device with a given stream format.\n\nCurrently, supported hosts include:\n\n- Linux (via ALSA or JACK)\n- Windows (via WASAPI by default, ASIO or JACK optionally)\n- macOS (via CoreAudio or JACK)\n- iOS (via CoreAudio)\n- Android (via AAudio)\n- Emscripten\n- WebAssembly (via Web Audio API or Audio Worklet)\n\nNote that on Linux, the ALSA development files are required for building (even when using JACK). These are provided as part of the `libasound2-dev` package on Debian and Ubuntu distributions and `alsa-lib-devel` on Fedora.\n\n## Compiling for WebAssembly\n\nIf 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.\n\n## Optional Features\n\nCPAL provides the following optional features:\n\n### `asio`\n\n**Platform:** Windows\n\nEnables the ASIO (Audio Stream Input/Output) backend. ASIO provides low-latency audio I/O by bypassing the Windows audio stack.\n\n**Requirements:**\n- ASIO drivers for your audio device\n- LLVM/Clang for build-time bindings generation\n\n**Setup:** See the [ASIO setup guide](#asio-on-windows) below for detailed installation instructions.\n\n### `jack`\n\n**Platform:** Linux, DragonFly BSD, FreeBSD, NetBSD, macOS, Windows\n\nEnables the JACK (JACK Audio Connection Kit) backend. JACK is an audio server providing low-latency connections between applications and audio hardware.\n\n**Requirements:**\n- JACK server and client libraries must be installed on the system\n\n**Usage:** See the [beep example](examples/beep.rs) for selecting the JACK host at runtime.\n\n**Note:** JACK is available as an alternative backend on all supported platforms. It provides an option for pro-audio users who need JACK's routing and inter-application audio connectivity. The native backends (ALSA for Linux/BSD, WASAPI/ASIO for Windows, CoreAudio for macOS) remain the default and recommended choice for most applications.\n\n### `wasm-bindgen`\n\n**Platform:** WebAssembly (wasm32-unknown-unknown)\n\nEnables the Web Audio API backend for browser-based audio. This is the base feature required for any WebAssembly audio support.\n\n**Requirements:**\n- Target `wasm32-unknown-unknown`\n- Web browser with Web Audio API support\n\n**Usage:** See the `wasm-beep` example for basic WebAssembly audio setup.\n\n### `audioworklet`\n\n**Platform:** WebAssembly (wasm32-unknown-unknown)\n\nEnables the Audio Worklet backend for lower-latency web audio processing compared to the default Web Audio API backend.\n\n**Requirements:**\n- The `wasm-bindgen` feature (automatically enabled)\n- Build with atomics support: `RUSTFLAGS=\"-C target-feature=+atomics,+bulk-memory,+mutable-globals\"`\n- Web server must send Cross-Origin headers for SharedArrayBuffer support\n\n**Setup:** See the `audioworklet-beep` example README for complete setup instructions.\n\n**Note:** Audio Worklet provides better performance than the default Web Audio API by running audio processing on a separate thread.\n\n### `custom`\n\n**Platform:** All platforms\n\nEnables support for user-defined custom host implementations, allowing integration with audio systems not natively supported by CPAL.\n\n**Usage:** See `examples/custom.rs` for implementation details.\n\n## ASIO on Windows\n\n### Locating the ASIO SDK\n\nThe location of ASIO SDK is exposed to CPAL by setting the `CPAL_ASIO_DIR` environment variable.\n\nThe build script will try to find the ASIO SDK by following these steps in order:\n\n1. Check if `CPAL_ASIO_DIR` is set and if so use the path to point to the SDK.\n2. Check if the ASIO SDK is already installed in the temporary directory, if so use that and set the path of `CPAL_ASIO_DIR` to the output of `std::env::temp_dir().join(\"asio_sdk\")`.\n3. If the ASIO SDK is not already installed, download it from \u003chttps://www.steinberg.net/asiosdk\u003e and install it in the temporary directory. The path of `CPAL_ASIO_DIR` will be set to the output of `std::env::temp_dir().join(\"asio_sdk\")`.\n\nIn an ideal situation you don't need to worry about this step.\n\n### Preparing the Build Environment\n\n1. **Install LLVM/Clang**: `bindgen`, the library used to generate bindings to the C++ SDK, requires clang. Download and install LLVM from \u003chttp://releases.llvm.org/download.html\u003e under the \"Pre-Built Binaries\" section.\n\n2. **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:\n   ```\n   setx LIBCLANG_PATH \"C:\\Program Files\\LLVM\\bin\"\n   ```\n\n3. **Install ASIO Drivers** (optional for testing): If you don't have any ASIO devices or drivers available, you can download and install ASIO4ALL from \u003chttp://www.asio4all.org/\u003e. Be sure to enable the \"offline\" feature during installation.\n\n4. **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:\n   ```\n   \"C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\Community\\VC\\Auxiliary\\Build\\vcvarsall.bat\" amd64\n   ```\n   For more information see the [vcvarsall.bat documentation](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line).\n\n### Using ASIO in Your Application\n\n1. **Enable the feature** in your `Cargo.toml`:\n   ```toml\n   cpal = { version = \"*\", features = [\"asio\"] }\n   ```\n\n2. **Select the ASIO host** in your code:\n   ```rust\n   let host = cpal::host_from_id(cpal::HostId::Asio)\n       .expect(\"failed to initialise ASIO host\");\n   ```\n\n### Troubleshooting\n\nIf you encounter compilation errors from `asio-sys` or `bindgen`:\n- Verify `CPAL_ASIO_DIR` is set correctly\n- Try running `cargo clean`\n- Ensure LLVM/Clang is properly installed and `LIBCLANG_PATH` is set\n\n### Cross-Compilation\n\nWhen Windows is the host and target OS, the build script supports all cross-compilation targets supported by the MSVC compiler.\n\nIt is also possible to compile Windows applications with ASIO support on Linux and macOS using the MinGW-w64 toolchain.\n\n**Requirements:**\n- Include the MinGW-w64 include directory in your `CPLUS_INCLUDE_PATH` environment variable\n- Include the LLVM include directory in your `CPLUS_INCLUDE_PATH` environment variable\n\n**Example for macOS** (targeting `x86_64-pc-windows-gnu` with `mingw-w64` installed via brew):\n```\nexport CPLUS_INCLUDE_PATH=\"$CPLUS_INCLUDE_PATH:/opt/homebrew/Cellar/mingw-w64/11.0.1/toolchain-x86_64/x86_64-w64-mingw32/include\"\n```\n\n## Troubleshooting\n\n### No Default Device Available\n\nIf you receive errors about no default input or output device:\n\n- **Linux/ALSA:** Ensure your user is in the `audio` group and that ALSA is properly configured\n- **Linux/PulseAudio:** Check that PulseAudio is running: `pulseaudio --check`\n- **Windows:** Verify your audio device is enabled in Sound Settings\n- **macOS:** Check System Preferences \u003e Sound for available devices\n- **Mobile (iOS/Android):** Ensure your app has microphone/audio permissions\n\n### Buffer Size Issues\n\nIf you experience audio glitches or dropouts:\n\n- Try `BufferSize::Default` first before requesting specific sizes\n- When using `BufferSize::Fixed`, query `SupportedBufferSize` to find valid ranges\n- Smaller buffers reduce latency but increase CPU load and risk dropouts\n- Ensure your audio callback completes quickly and avoids blocking operations\n\n### Build Errors\n\n- **ASIO on Windows:** Verify `LIBCLANG_PATH` is set and LLVM is installed\n- **ALSA on Linux:** Install development packages: `libasound2-dev` (Debian/Ubuntu) or `alsa-lib-devel` (Fedora)\n- **JACK:** Install JACK development libraries before enabling the `jack` feature\n\n## Examples\n\nCPAL comes with several examples demonstrating various features:\n\n- `beep` - Generate a simple sine wave tone\n- `enumerate` - List all available audio devices and their capabilities\n- `feedback` - Pass input audio directly to output (microphone loopback)\n- `record_wav` - Record audio from the default input device to a WAV file\n- `synth_tones` - Generate multiple tones simultaneously\n\nRun an example with:\n```bash\ncargo run --example beep\n```\n\nFor platform-specific features, enable the relevant features:\n```bash\ncargo run --example beep --features asio  # Windows ASIO\ncargo run --example beep --features jack  # JACK backend\n```\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## Resources\n\n- **Documentation:** [docs.rs/cpal](https://docs.rs/cpal)\n- **Examples:** [examples/](examples/) directory in this repository\n- **Discord:** Join the [#cpal channel](https://discord.gg/vPmmSgJSPV) for questions and discussion\n- **GitHub:** [Report issues](https://github.com/RustAudio/cpal/issues) and [view source code](https://github.com/RustAudio/cpal)\n- **RustAudio:** Part of the [RustAudio organization](https://github.com/RustAudio)\n\n## License\n\nLicensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frustaudio%2Fcpal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frustaudio%2Fcpal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frustaudio%2Fcpal/lists"}