oxisound-cpal — CPAL-backed audio device implementation for OxiSound

oxisound-cpal is the CPAL-backed implementation of the device and stream traits defined in oxisound-core. It provides the CpalDevice type (implementing AudioDevice) plus a family of ring-buffer and zero-copy stream wrappers, adaptive buffer sizing, device hot-plug detection, automatic stream recovery, and optional async stream adapters.

Pure-Rust status: platform backend (NOT Pure Rust). CPAL binds the host operating system's native audio APIs through C-FFI: ALSA + libc on Linux/BSD, CoreAudio (coreaudio-rs, objc2-core-foundation) on macOS/iOS, and the WASAPI path of the windows crate on Windows. These bindings are auto-selected by cfg(target_os) — there is no ALSA/CoreAudio/WASAPI feature to toggle. Under the COOLJAPAN Pure Rust Policy, CPAL is treated as a permitted OS-boundary backend (the same rationale as the JACK and Web Audio backends): it provides hardware audio access that no pure-Rust crate can replicate. This crate's own code is #![forbid(unsafe_code)]; the unsafe lives inside CPAL and the OS bindings.

Installation

[dependencies]
oxisound-cpal = "0.1.3"

# async output/input stream wrappers (requires a tokio runtime; sync + rt features)
oxisound-cpal = { version = "0.1.3", features = ["tokio"] }

# WebAudio backend for wasm32-unknown-unknown
oxisound-cpal = { version = "0.1.3", features = ["wasm"] }

Quick Start

Open the default output device and play one second of a 440 Hz sine tone:

use oxisound_core::{AudioDevice, OutputStream, StreamConfig};
use oxisound_cpal::CpalDevice;

let device = CpalDevice::default_output()?;
let mut out = device.open_output(StreamConfig::stereo_48k())?;

let mut buf = vec![0.0f32; 48_000 * 2]; // 1 s stereo @ 48 kHz
for (i, frame) in buf.chunks_mut(2).enumerate() {
    let t = i as f32 / 48_000.0;
    let s = (2.0 * std::f32::consts::PI * 440.0 * t).sin() * 0.2;
    frame[0] = s;
    frame[1] = s;
}
out.write(&buf)?;
# Ok::<(), oxisound_core::OxiSoundError>(())

Enumerate devices:

use oxisound_core::AudioDevice;
use oxisound_cpal::CpalDevice;

for d in CpalDevice::enumerate_all()? {
    println!("{d}");
}
# Ok::<(), oxisound_core::OxiSoundError>(())

API Overview

CpalDevice

Implements oxisound_core::AudioDevice and adds a large set of inherent methods for enumeration, host selection, concrete-typed stream opening, and hot-plug handling.

CpalOutputStream

Ring-buffer-backed output stream (implements OutputStream). The application pushes samples via write; a lock-free SPSC ring buffer feeds the real-time audio callback.

CpalInputStream

Ring-buffer-backed input stream (implements InputStream). The audio callback pushes captured samples; the application pops them via read.

CpalDuplexStream

Paired input + output ring buffers (implements DuplexStream), with clock-drift estimation and a built-in linear-interpolation resampler.

Callback (zero-copy) streams

open_output_callback / open_input_callback invoke your closure directly on the real-time audio thread, bypassing the ring buffer for minimal latency.

Async streams (tokio feature)

Adaptive buffer sizing

AdaptiveBufferSizer is a pure, allocation-free state machine: it doubles the buffer on an underrun (capped at max) and shrinks back toward the initial size after a configurable number of stable periods. It only recommends a size — applying it requires a caller-driven stream rebuild.

Hot-plug & recovery

Feature Flags

wasm32 caveats. The tokio feature is incompatible with wasm32 (enabling both is a compile error — use wasm instead). On wasm32 there are no OS threads, so automatic recovery and hot-plug detection (enable_auto_reconnect, watch_devices, on_device_change) are not compiled in, and std::time::Instant::now() panics without a web-time shim.

Native backend selection is automatic. ALSA / CoreAudio / WASAPI are chosen by cfg(target_os) and have no feature flag. PipeWire is not a CPAL feature in 0.17.3; on Linux it is reached through the ALSA or JACK compatibility layer.

Exclusive (low-latency) mode. CPAL 0.17.3 hardcodes WASAPI shared mode, so StreamConfig::exclusive currently logs a warning and falls back to shared mode.

Errors

All fallible methods return oxisound_core::OxiSoundError. CPAL build/play/enumeration errors are mapped onto its variants — most notably DeviceNotAvailable → Disconnected, format issues → FormatMismatch, and a full ring buffer → Overrun. See the oxisound-core error table.

Cross-references

• Traits & types: oxisound-core — AudioDevice, OutputStream, InputStream, DuplexStream, StreamConfig, DeviceInfo, HostApi.
• Other backends: oxisound-jack (direct JACK client), oxisound-midi (MIDI I/O).
• Facade: oxisound.

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)