diff --git a/Cargo.lock b/Cargo.lock index a808ce4a..d22baf29 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -73,7 +73,7 @@ checksum = "7c02d123df017efcdfbd739ef81735b36c5ba83ec3c59c80a9d7ecc718f92e50" [[package]] name = "asio-sys" version = "0.3.0" -source = "git+https://github.com/RustAudio/cpal#1d656375ff48216630367807dd8f81b2b811ca4d" +source = "git+https://github.com/RustAudio/cpal#5418f0b43786bcbb4eaf21179e8a0fac76021a58" dependencies = [ "bindgen", "cc", @@ -322,7 +322,7 @@ dependencies = [ [[package]] name = "cpal" version = "0.18.0" -source = "git+https://github.com/RustAudio/cpal#1d656375ff48216630367807dd8f81b2b811ca4d" +source = "git+https://github.com/RustAudio/cpal#5418f0b43786bcbb4eaf21179e8a0fac76021a58" dependencies = [ "alsa", "alsa-sys", diff --git a/Cargo.toml b/Cargo.toml index 2ec428c5..4b2d51d6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -13,14 +13,19 @@ rust-version = "1.89" [features] # Default feature set provides audio playback and common format support default = [ - "playback", - "recording", - "flac", - "mp3", - "mp4", - "vorbis", - "wav", - "dither", + # Core functionality + "playback", + "recording", + # Audio format support + "flac", + "mp3", + "mp4", + "vorbis", + "wav", + # Platform-specific backends + "pulseaudio", + # Performance features + "simd", ] # Core functionality features @@ -48,8 +53,10 @@ noise = ["rand", "rand_distr"] # Perform all calculations with 64-bit floats (instead of 32) 64bit = [] # Real-time audio thread scheduling +# With the realtime-dbus feature, rtkit arranges the necessary limits over D-Bus on typical desktop systems. +# With the plain realtime feature, you must ensure that rtprio is granted yourself. +# See: https://github.com/RustAudio/cpal#alsa-real-time-priority-promotion realtime = ["cpal/realtime"] -# D-Bus/rtkit support on top of `realtime` for RT scheduling on Linux/BSD desktop systems realtime-dbus = ["cpal/realtime-dbus"] # SIMD-accelerated audio processing simd = ["symphonia/opt-simd"] diff --git a/README.md b/README.md index 8454a0cb..446bec86 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,10 @@ Rodio will keep a rolling MSRV (minimum supported rust version) policy of at lea ## Dependencies (Linux only) -Rodio uses `cpal` library to send audio to the OS for playback. ALSA development files are needed to build `cpal` on Linux. These are provided as part of the `libasound2-dev` package on Debian and Ubuntu distributions and `alsa-lib-devel` on Fedora. +Rodio uses `cpal` for audio playback and recording. The following development libraries are required on Linux: + +- **ALSA** (`libasound2-dev` on Debian/Ubuntu, `alsa-lib-devel` on Fedora): always required as the base audio layer. +- **PulseAudio** (`libpulse-dev` on Debian/Ubuntu, `pulseaudio-libs-devel` on Fedora): required when the `pulseaudio` feature is enabled, which it is by default. ### Minimal build diff --git a/src/lib.rs b/src/lib.rs index fbca45f5..dbd6174c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -138,31 +138,53 @@ //! to avoid adding extra crates to your binary. //! See the [available feature flags](https://docs.rs/crate/rodio/latest/features) for all options. //! -//! ## Optional Features +//! ## Feature Flags //! -//! Rodio provides several optional features that are guarded with feature gates. +//! ### Core //! -//! ### Feature "tracing" +//! | Feature | Description | +//! |---------|-------------| +//! | `playback` **(default)** | Audio playback | +//! | `recording` **(default)** | Microphone input | +//! | `wav_output` | Write decoded audio to a WAV file | +//! | `tracing` | Record stream errors as `tracing` events instead of printing to stderr | +//! | `experimental` | Experimental APIs backed by atomic floating-point operations | //! -//! The "tracing" feature replaces the print to stderr when a stream error happens with a -//! recording an error event with tracing. +//! ### Performance //! -//! ### Feature "noise" +//! | Feature | Description | +//! |---------|-------------| +//! | `simd` **(default)** | SIMD-accelerated decoding | +//! | `64bit` | Use `f64` instead of `f32` for all samples and internal math [^1] | +//! | `realtime` | Real-time thread scheduling priority (you must grant `rtprio` yourself) | +//! | `realtime-dbus` | Like `realtime`, but uses D-Bus/rtkit to arrange limits automatically on desktop Linux | //! -//! The "noise" feature adds support for white and pink noise sources. This feature requires the -//! "rand" crate. +//! [^1]: By default, rodio uses 32-bit floats (`f32`), which offers better performance and is +//! sufficient for most use cases. The 64-bit mode addresses precision drift when chaining many +//! audio operations together, in long-running signal generators where phase errors compound +//! over time, and during resampling where rounding errors accumulate. //! -//! ### Feature "playback" +//! ### Audio generation //! -//! The "playback" feature adds support for playing audio. This feature requires the "cpal" crate. +//! | Feature | Description | +//! |---------|-------------| +//! | `noise` | White and pink noise sources | +//! | `dither` | Dithering; implies `noise` | //! -//! ### Feature "64bit" +//! ### Platform backends //! -//! The "64bit" feature enables 64-bit sample precision using `f64` for audio samples and most -//! internal calculations. By default, rodio uses 32-bit floats (`f32`), which offers better -//! performance and is sufficient for most use cases. The 64-bit mode addresses precision drift -//! when chaining many audio operations together and in long-running signal generators where -//! phase errors compound over time. +//! | Feature | Platform | Description | +//! |---------|----------|-------------| +//! | `pulseaudio` **(default)** | Linux | PulseAudio backend; also works on PipeWire systems via `pipewire-pulse`, with ALSA as fallback | +//! | `asio` | Windows | ASIO low-latency backend | +//! | `jack` | Linux/macOS/Windows | JACK Audio Connection Kit | +//! | `pipewire` | Linux | Native PipeWire backend | +//! | `audio-worklet` | Wasm | Audio Worklet backend | +//! | `wasm-bindgen` | Wasm | wasm-bindgen Wasm backend | +//! +//! ### Audio format features +//! +//! See the [Decoder Backends](#decoder-backends) section above. //! //! ## How it works under the hood //!