docs.rs failed to build audio-io-bsd-0.1.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

audio-io-bsd

Audio I/O backend abstraction for real-time audio. It provides the AudioBackend trait — the single contract a host application (an audio engine, a test, or any consumer) uses to reach the kernel audio layer — plus the plain-data types (StreamParams, DeviceInfo) that flow across it. On FreeBSD the concrete backend reaches OSS /dev/dsp indirectly through the cpal ALSA backend (FreeBSD's alsa-lib port translates ALSA calls onto OSS).

The doc comments on each public item are the primary reference. This README is an overview only.

Overview

audio-io-bsd decouples audio consumers (audio engines, gateway code, tests) from the concrete device driver. The default build has no system-audio dependency: the trait surface and an in-memory NullBackend test double compile and test anywhere. The concrete CpalBackend is opt-in via the cpal-backend feature.

Real-time safety boundary

OutputSink::write is designed to be callable from the real-time audio thread: it must not allocate, lock, panic, or perform I/O. CpalBackend implements the canonical callback-driven pattern — write pushes interleaved samples into a lock-free rtrb ring (wait-free); a cpal callback on the audio thread drains it. The heavy device I/O happens in the callback, never on the caller's RT thread. Capture (InputSource::read) is intended for a worker thread.

Core types

Type	Description
`AudioBackend`	The public trait: enumerate devices, open output/input streams.
`OutputSink`	Write side of a playback stream (RT-thread-safe).
`InputSource`	Read side of a capture stream (worker thread).
`StreamParams`	Sample rate / channels / format / buffer size to open a stream with.
`DeviceInfo`	Capabilities of a discovered device.
`NullBackend`	Device-free in-memory backend for tests (always available).
`CpalBackend`	Concrete cpal (ALSA/`/dev/dsp`/CoreAudio) backend (`cpal-backend` feat).
`IoError`	Error enum (thiserror-backed).

Feature flags

Feature	Default	Purpose
`cpal-backend`	off	Pull in `cpal` + `rtrb` and the concrete `CpalBackend`.

Without cpal-backend the crate links no system audio library, so it builds cleanly on docs.rs and CI hosts without ALSA headers.

Dependencies

Dependency	Version	Purpose	License	Optional
`audio-core-bsd`	0.1.0	`AudioFrame`, `SampleFormat`, errors	BSD-2-Clause	no
`thiserror`	2.0	`IoError` derive	MIT OR Apache-2.0	no
`cpal`	0.15	ALSA/CoreAudio backend	Apache-2.0	yes
`rtrb`	0.3	lock-free ring buffer (RT↔callback)	MIT OR Apache-2.0	yes
`proptest` (dev)	1.11.0	property tests	MIT OR Apache-2.0	—

cpal on FreeBSD/Linux links ALSA (LGPL-2.1, runtime only), which is compatible with the BSD-2-Clause license of this crate.

Status

0.x — experimental. The API is not yet frozen. The core trait surface (AudioBackend/OutputSink/InputSource) and NullBackend are implemented and tested. CpalBackend requires the cpal-backend feature and is validated on a FreeBSD CI gate (native cargo test --all-features on FreeBSD 14.2 / 15.1).

Note: cpal is pinned to 0.15 because cpal 0.18's ALSA backend does not compile on FreeBSD (libc::ESTRPIPE is Linux-only). See the CpalBackend docs for details.

edition: 2021
MSRV: 1.85
license: BSD-2-Clause

Example

Open the default output and push silence (works on any host via NullBackend):

use audio_io_bsd::{AudioBackend, NullBackend, StreamParams};

let backend = NullBackend::new();
let dev = backend.default_output().unwrap();
let mut sink = backend.open_output(&dev.name, StreamParams::pcm_48k_stereo())?;
let silence = audio_core_bsd::AudioFrame::silence(2, 256, 48_000);
sink.write(&silence)?;
# Ok::<(), audio_io_bsd::IoError>(())

For real audio, replace NullBackend with CpalBackend::new() and enable the cpal-backend feature (see examples/play_sine.rs).

License

BSD-2-Clause. See LICENSE.

audio-io-bsd 0.1.0