| Lift freeq's AV media plane out of sleek 90f8b89 nandi 19d ago | 1 | # asio-sys |
| 2 | |
| 3 | [](https://crates.io/crates/asio-sys) |
| 4 | [](https://docs.rs/asio-sys) |
| 5 | [](https://github.com/RustAudio/cpal/blob/master/LICENSE) |
| 6 | |
| 7 | Low-level Rust bindings for the [Steinberg ASIO SDK](https://www.steinberg.net/developers/). |
| 8 | |
| 9 | ASIO (Audio Stream Input/Output) is a low-latency audio API for Windows that provides direct hardware access, bypassing the Windows audio stack for minimal latency. |
| 10 | |
| 11 | ## Overview |
| 12 | |
| 13 | `asio-sys` provides raw FFI bindings to the ASIO SDK, automatically generated using [bindgen](https://rust-lang.github.io/rust-bindgen/). This crate is used by [cpal](https://crates.io/crates/cpal)'s ASIO backend to provide low-latency audio on Windows. |
| 14 | |
| 15 | **Note:** Most users should use [cpal](https://crates.io/crates/cpal)'s safe, cross-platform API rather than using `asio-sys` directly. |
| 16 | |
| 17 | ## Features |
| 18 | |
| 19 | - Automatic binding generation from ASIO SDK headers |
| 20 | - Low-level access to ASIO driver functionality |
| 21 | - Support for both MSVC and MinGW toolchains |
| 22 | - Automated ASIO SDK download and setup during build |
| 23 | |
| 24 | ## Requirements |
| 25 | |
| 26 | ### Windows |
| 27 | |
| 28 | - **LLVM/Clang**: Required for bindgen to generate bindings |
| 29 | - Install via [LLVM downloads](https://releases.llvm.org/) or `choco install llvm` |
| 30 | - **ASIO SDK**: Automatically downloaded during build from Steinberg |
| 31 | - Or set `CPAL_ASIO_DIR` environment variable to point to a local SDK |
| 32 | |
| 33 | ### Build Dependencies |
| 34 | |
| 35 | - `bindgen` - Generates Rust bindings from C/C++ headers |
| 36 | - `cc` - Compiles the ASIO SDK C++ files |
| 37 | - `walkdir` - Finds SDK files |
| 38 | |
| 39 | ## Usage |
| 40 | |
| 41 | Add to your `Cargo.toml`: |
| 42 | |
| 43 | ```toml |
| 44 | [dependencies] |
| 45 | asio-sys = "0.2" |
| 46 | ``` |
| 47 | |
| 48 | ### Example |
| 49 | |
| 50 | ```rust |
| 51 | use asio_sys as sys; |
| 52 | |
| 53 | fn main() { |
| 54 | // Load ASIO driver |
| 55 | let driver_name = "ASIO4ALL v2"; // Your ASIO driver name |
| 56 | |
| 57 | unsafe { |
| 58 | // Initialize ASIO |
| 59 | let drivers = sys::get_driver_names(); |
| 60 | println!("Available drivers: {drivers:?}"); |
| 61 | |
| 62 | // Load a driver |
| 63 | match sys::load_asio_driver(driver_name) { |
| 64 | Ok(driver) => println!("Loaded driver: {driver_name}"), |
| 65 | Err(e) => eprintln!("Failed to load driver: {e:?}"), |
| 66 | } |
| 67 | } |
| 68 | } |
| 69 | ``` |
| 70 | |
| 71 | ## Environment Variables |
| 72 | |
| 73 | - `CPAL_ASIO_DIR`: Path to ASIO SDK directory (optional) |
| 74 | - If not set, the SDK is automatically downloaded during build |
| 75 | - Example: `set CPAL_ASIO_DIR=C:\path\to\asiosdk` |
| 76 | |
| 77 | ## Platform Support |
| 78 | |
| 79 | - **Windows** (MSVC and MinGW) |
| 80 | - x86_64 (64-bit) |
| 81 | - i686 (32-bit) |
| 82 | |
| 83 | ASIO is Windows-only. This crate will not build on other platforms. |
| 84 | |
| 85 | ## Safety |
| 86 | |
| 87 | This crate provides raw FFI bindings to C++ code. Almost all functions are `unsafe` and require careful handling: |
| 88 | |
| 89 | - Memory management is manual |
| 90 | - Callbacks must be properly synchronized |
| 91 | - Driver state must be carefully managed |
| 92 | - See [ASIO SDK documentation](https://www.steinberg.net/developers/) for details |
| 93 | |
| 94 | ## License |
| 95 | |
| 96 | Licensed under the Apache License, Version 2.0. See [LICENSE](../LICENSE) for details. |
| 97 | |
| 98 | The ASIO SDK is owned by Steinberg Media Technologies GmbH. Users must comply with Steinberg's licensing terms. |
| 99 | |
| 100 | ## Contributing |
| 101 | |
| 102 | Contributions are welcome! Please submit issues and pull requests to the [cpal repository](https://github.com/RustAudio/cpal). |
| 103 | |
| 104 | ## Resources |
| 105 | |
| 106 | - [ASIO SDK Documentation](https://www.steinberg.net/developers/) |
| 107 | - [cpal Documentation](https://docs.rs/cpal) |
| 108 | - [RustAudio Community](https://github.com/RustAudio) |
| 109 | - [Discord](https://discord.gg/vPmmSgJSPV): #cpal Channel |