audio-io-bsd 0.2.0

Audio I/O backend abstraction (AudioBackend trait) with a cpal ALSA/OSS backend for FreeBSD-first real-time audio
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

//! Audio I/O backend abstraction for real-time audio.
//!
//! This crate provides the [`AudioBackend`] trait — the single contract a host
//! application (an audio engine, an integration test, or any consumer) uses to
//! reach the kernel audio layer — together with 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).
//!
//! ## 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. The canonical
//! pattern is for the concrete backend to own a device callback that pulls from
//! a lock-free ring buffer, so `write` only ever *pushes* samples (a wait-free
//! operation). This mirrors the real-time contract stated on
//! [`audio_core_bsd::AudioNode`]. Capture ([`InputSource::read`]) is intended
//! for a worker thread, not the RT thread.
//!
//! ## Feature flags
//!
//! - **`cpal-backend`** *(off by default)* — pulls in the [`cpal`] crate and
//!   the concrete [`CpalBackend`](cpal_backend/struct.CpalBackend.html). The
//!   default build has **no** system-audio dependency, so the core contract
//!   compiles and tests anywhere (docs.rs, CI hosts without ALSA headers).
//!
//! ## Dependency licensing
//!
//! This crate depends on [`audio-core-bsd`] (**BSD-2-Clause**) and
//! [`thiserror`] (**MIT OR Apache-2.0**). With the `cpal-backend` feature it
//! additionally links [`cpal`] (**Apache-2.0**), which on FreeBSD/Linux links
//! ALSA (**LGPL-2.1**, runtime only) — compatible with the BSD-2-Clause
//! license of this crate.
//!
//! [`audio-core-bsd`]: https://crates.io/crates/audio-core-bsd
//! [`thiserror`]: https://crates.io/crates/thiserror
//! [`cpal`]: https://crates.io/crates/cpal

#![cfg_attr(docsrs, feature(doc_cfg))]
#![warn(missing_docs)]
#![warn(clippy::all, clippy::pedantic)]

pub mod backend;
pub mod device;
pub mod error;
pub mod null_backend;
pub mod sample_conv;

#[cfg(feature = "cpal-backend")]
#[cfg_attr(docsrs, doc(cfg(feature = "cpal-backend")))]
pub mod cpal_backend;

#[cfg(all(target_os = "freebsd", feature = "oss"))]
#[cfg_attr(docsrs, doc(cfg(all(target_os = "freebsd", feature = "oss"))))]
pub mod oss_backend;

pub use backend::{AudioBackend, InputSource, OutputSink};
pub use device::{BufferSize, CoreSampleFormat, DeviceDirection, DeviceInfo, StreamParams};
pub use error::{IoError, Result};
pub use null_backend::NullBackend;

#[cfg(feature = "cpal-backend")]
pub use cpal_backend::CpalBackend;

#[cfg(all(target_os = "freebsd", feature = "oss"))]
pub use oss_backend::OssBackend;