asio-sys

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109

# asio-sys

[![Crates.io](https://img.shields.io/crates/v/asio-sys.svg)](https://crates.io/crates/asio-sys)
[![Documentation](https://docs.rs/asio-sys/badge.svg)](https://docs.rs/asio-sys)
[![License](https://img.shields.io/crates/l/asio-sys.svg)](https://github.com/RustAudio/cpal/blob/master/LICENSE)

Low-level Rust bindings for the [Steinberg ASIO SDK](https://www.steinberg.net/developers/).

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.

## Overview

`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.

**Note:** Most users should use [cpal](https://crates.io/crates/cpal)'s safe, cross-platform API rather than using `asio-sys` directly.

## Features

- Automatic binding generation from ASIO SDK headers
- Low-level access to ASIO driver functionality
- Support for both MSVC and MinGW toolchains
- Automated ASIO SDK download and setup during build

## Requirements

### Windows

- **LLVM/Clang**: Required for bindgen to generate bindings
  - Install via [LLVM downloads](https://releases.llvm.org/) or `choco install llvm`
- **ASIO SDK**: Automatically downloaded during build from Steinberg
  - Or set `CPAL_ASIO_DIR` environment variable to point to a local SDK

### Build Dependencies

- `bindgen` - Generates Rust bindings from C/C++ headers
- `cc` - Compiles the ASIO SDK C++ files
- `walkdir` - Finds SDK files

## Usage

Add to your `Cargo.toml`:

```toml
[dependencies]
asio-sys = "0.2"
```

### Example

```rust
use asio_sys as sys;

fn main() {
    // Load ASIO driver
    let driver_name = "ASIO4ALL v2"; // Your ASIO driver name

    unsafe {
        // Initialize ASIO
        let drivers = sys::get_driver_names();
        println!("Available drivers: {drivers:?}");

        // Load a driver
        match sys::load_asio_driver(driver_name) {
            Ok(driver) => println!("Loaded driver: {driver_name}"),
            Err(e) => eprintln!("Failed to load driver: {e:?}"),
        }
    }
}
```

## Environment Variables

- `CPAL_ASIO_DIR`: Path to ASIO SDK directory (optional)
  - If not set, the SDK is automatically downloaded during build
  - Example: `set CPAL_ASIO_DIR=C:\path\to\asiosdk`

## Platform Support

- **Windows** (MSVC and MinGW)
  - x86_64 (64-bit)
  - i686 (32-bit)

ASIO is Windows-only. This crate will not build on other platforms.

## Safety

This crate provides raw FFI bindings to C++ code. Almost all functions are `unsafe` and require careful handling:

- Memory management is manual
- Callbacks must be properly synchronized
- Driver state must be carefully managed
- See [ASIO SDK documentation](https://www.steinberg.net/developers/) for details

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](../LICENSE) for details.

The ASIO SDK is owned by Steinberg Media Technologies GmbH. Users must comply with Steinberg's licensing terms.

## Contributing

Contributions are welcome! Please submit issues and pull requests to the [cpal repository](https://github.com/RustAudio/cpal).

## Resources

- [ASIO SDK Documentation](https://www.steinberg.net/developers/)
- [cpal Documentation](https://docs.rs/cpal)
- [RustAudio Community](https://github.com/RustAudio)
- [Discord](https://discord.gg/vPmmSgJSPV): #cpal Channel