DOCSEARCHbyAlgolia
Submit Docs

cpal Documentation

repository·master·Indexed 26 days ago

https://github.com/rustaudio/cpal

A low-level, cross-platform audio I/O library for Rust (version 0.18.1) providing access to audio input and output devices. It supports device enumeration, metadata inspection, and stream management across various backends including ASIO (Windows), JACK, PipeWire, PulseAudio (Linux/BSD), and Web Audio API/Audio Worklet (WebAssembly).

Tokens
12.3K
Snippets
44
Records
78
Agent score
86%

What's inside cpal

  1. Overview of CPAL functionality

    master

    CPAL (Cross-Platform Audio Library) is a low-level Rust library for audio input and output. It provides the following capabilities:

    • Device Enumeration: List audio hosts, devices, and their supported stream configurations.
    • Device Lookup: Find devices by stable ID or by default input/output roles.
    • Metadata Inspection: Access device name, manufacturer, type, and bus type.
    • Stream Management: Build input and output streams using compile-time or runtime sample formats; play, pause, and query buffer size and clock.

    For higher-level audio playback and capture, consider using Rodio.

  4. Install Linux build dependencies

    master

    To build CPAL on Linux, you must install the ALSA development files. This is required even if you intend to use JACK, PipeWire, or PulseAudio.

    • Debian/Ubuntu: sudo apt install libasound2-dev
    • Fedora: sudo dnf install alsa-lib-devel

    If you use the realtime-dbus feature, you also need:

    • Debian/Ubuntu: sudo apt install libdbus-1-dev
    • Fedora: sudo dnf install dbus-devel

  9. Configure asio-sys build requirements

    master

    To build asio-sys on Windows, ensure the following requirements are met:

    1. LLVM/Clang: Required for bindgen to generate bindings. Install via LLVM downloads or using Chocolatey: choco install llvm.
    2. ASIO SDK: The crate automatically downloads the SDK from Steinberg during the build process.

    If you prefer to use a local copy of the SDK instead of an automatic download, set the CPAL_ASIO_DIR environment variable to the path of your local ASIO SDK directory.

  11. Build the iOS Feedback Example

    master

    The iOS Feedback Example is an Xcode project that demonstrates simultaneous input and output audio streams by routing microphone input to the output device with a delay.

    To build a universal binary (supporting both x86 for the simulator and aarch64 for physical devices), you must install cargo-lipo.

    cargo install cargo-lipo

  12. Upgrade from v0.16 to v0.17: BufferSize::Default and Fixed validation

    master

    BufferSize::Default

    BufferSize::Default now defers to the audio host/device defaults instead of using CPAL's internal defaults. This may change latency characteristics. If you require specific latency, use BufferSize::Fixed(size).

    BufferSize::Fixed Validation

    Backends have updated validation for fixed buffer sizes:

    • ALSA: Uses set_buffer_size_near() for better hardware compatibility.
    • JACK: Must exactly match the server buffer size.
    • ASIO: Stricter lower bound validation.

    Fallback Pattern: If build_output_stream returns BuildStreamError::StreamConfigNotSupported, you should fallback to BufferSize::Default.

    match device.build_output_stream(&config, data_fn, err_fn, None) {
    Ok(stream) => { /* success */ },
    Err(BuildStreamError::StreamConfigNotSupported) => {
        config.buffer_size = BufferSize::Default;  // Fallback
        device.build_output_stream(&config, data_fn, err_fn, None)?
    },
    Err(e) => return Err(e),
}