Merge pull request #97 from BillyDM/rtaudio

add RtAudio backend

Author: BillyDM

.github/workflows/ci.yml

@@ -25,7 +25,7 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
 
       - name: Install dependencies
-        run: sudo apt-get update; sudo apt-get install -y --no-install-recommends libasound2-dev libudev-dev libwayland-dev libxkbcommon-dev
+        run: sudo apt-get update; sudo apt-get install -y --no-install-recommends libasound2-dev libudev-dev libwayland-dev libxkbcommon-dev cmake libpulse-dev
 
       - name: Populate target directory from cache
         uses: Leafwing-Studios/cargo-cache@v2
@@ -70,7 +70,7 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
 
       - name: Install dependencies
-        run: sudo apt-get update; sudo apt-get install -y --no-install-recommends libasound2-dev libudev-dev libwayland-dev libxkbcommon-dev
+        run: sudo apt-get update; sudo apt-get install -y --no-install-recommends libasound2-dev libudev-dev libwayland-dev libxkbcommon-dev cmake libpulse-dev
 
       - name: Populate target directory from cache
         uses: Leafwing-Studios/cargo-cache@v2

Cargo.toml

@@ -24,7 +24,14 @@ exclude = ["assets/"]
 repository = "https://github.com/BillyDM/firewheel"
 
 [features]
-default = ["std", "cpal", "symphonium", "symphonium_resample", "sampler_node", "tracing"]
+default = [
+    "std",
+    "cpal",
+    "symphonium",
+    "symphonium_resample",
+    "sampler_node",
+    "tracing",
+]
 std = [
     "firewheel-core/std",
     "firewheel-graph/std",
@@ -34,9 +41,14 @@ std = [
 # Enable this if "std" is disabled.
 libm = ["firewheel-core/libm", "firewheel-nodes/libm"]
 # Use the `tracing` crate for logging. Currently requires `std`.
-tracing = ["firewheel-graph/tracing", "firewheel-cpal?/tracing", "std"]
+tracing = [
+    "firewheel-graph/tracing",
+    "firewheel-cpal?/tracing",
+    "firewheel-rtaudio?/tracing",
+    "std",
+]
 # Use the `log` crate for logging
-log = ["firewheel-graph/log", "firewheel-cpal?/log"]
+log = ["firewheel-graph/log", "firewheel-cpal?/log", "firewheel-rtaudio?/log"]
 # Enables scheduling events for nodes
 scheduled_events = [
     "firewheel-core/scheduled_events",
@@ -54,6 +66,12 @@ musical_transport = [
 cpal = ["std", "dep:firewheel-cpal"]
 # Enables resampling input streams in the cpal backend
 cpal_resample_inputs = ["firewheel-cpal?/resample_inputs"]
+# Enables the alternative RtAudio backend
+# This backend has better support for "full duplex" audio devices than
+# the default CPAL backend, which allows for less latency between input
+# and output streams. The drawback is that this backend only supports
+# Windows, MacOS, and Linux desktop platforms.
+rtaudio = ["std", "firewheel-rtaudio"]
 # Enables using Symphonium for loading audio files.
 # Requires the standard library.
 symphonium = ["dep:firewheel-symphonium"]
@@ -155,11 +173,13 @@ members = [
     "crates/firewheel-nodes",
     "crates/firewheel-macros",
     "crates/firewheel-pool",
+    "crates/firewheel-rtaudio",
     "crates/firewheel-symphonium",
     "examples/beep_test",
     "examples/cpal_input",
     "examples/custom_nodes",
     "examples/play_sample",
+    "examples/rtaudio_beep_test",
     "examples/sampler_pool",
     "examples/sampler_test",
     "examples/spatial_basic",
@@ -197,8 +217,8 @@ eframe = { version = "0.33.3", default-features = false, features = [
     "default_fonts",
     "wayland",
     "x11",
-    "glow"
-]}
+    "glow",
+] }
 
 [dependencies]
 firewheel-core = { path = "crates/firewheel-core", version = "0.10.0", default-features = false }
@@ -207,6 +227,7 @@ firewheel-cpal = { path = "crates/firewheel-cpal", version = "0.10.0", default-f
 firewheel-nodes = { path = "crates/firewheel-nodes", version = "0.10.0", default-features = false }
 firewheel-pool = { path = "crates/firewheel-pool", version = "0.10.0", default-features = false, optional = true }
 firewheel-symphonium = { path = "crates/firewheel-symphonium", version = "0.10.0", default-features = false, optional = true }
+firewheel-rtaudio = { path = "crates/firewheel-rtaudio", version = "0.10.0", default-features = false, optional = true }
 thunderdome = { workspace = true, optional = true }
 smallvec = { workspace = true, optional = true }
 thiserror.workspace = true

crates/firewheel-core/src/lib.rs

@@ -25,17 +25,34 @@ extern crate self as firewheel_core;
 /// Information about a running audio stream.
 #[derive(Debug, Clone, PartialEq)]
 pub struct StreamInfo {
+    /// The sample rate of the audio stream.
     pub sample_rate: NonZeroU32,
     /// The reciprocal of the sample rate.
+    ///
+    /// This is provided for convenience since dividing by the sample rate is such a
+    /// common operation.
+    ///
+    /// Note to users implementing a custom `AudioBackend`: The context will overwrite
+    /// this value, so just set this to the default value.
     pub sample_rate_recip: f64,
     /// The sample rate of the previous stream. (If this is the first stream, then this
     /// will just be a copy of [`StreamInfo::sample_rate`]).
+    ///
+    /// Note to users implementing a custom `AudioBackend`: The context will overwrite
+    /// this value, so just set this to the default value.
     pub prev_sample_rate: NonZeroU32,
+    /// The maximum number of frames that can appear in a single process cyle.
     pub max_block_frames: NonZeroU32,
+    /// The number of input audio channels in the stream.
     pub num_stream_in_channels: u32,
+    /// The number of output audio channels in the stream.
     pub num_stream_out_channels: u32,
     /// The latency of the input to output stream in seconds.
     pub input_to_output_latency_seconds: f64,
+    /// The number of frames used in the shared declicker DSP.
+    ///
+    /// Note to users implementing a custom `AudioBackend`: The context will overwrite
+    /// this value, so just set this to the default value.
     pub declick_frames: NonZeroU32,
     /// The identifier of the output audio device (converted to a string).
     pub output_device_id: String,