Merge pull request #888 from RustAudio/chore/improve-default-features

chore: update dependencies and improve feature documentation

Author: yara-blue

Cargo.lock

@@ -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"]

Cargo.toml

@@ -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
 

README.md

@@ -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
 //!