refactor(duplex): Remove AudioTimestamp and all Duplex stream and error types

Simplify the duplex implementation by unifying it with existing Stream types instead
of introducing separate types. This removes AudioTimestamp, DuplexStream wrappers,
and the duplicate DuplexDisconnectManager, making duplex streams work the same way
as regular input/output streams.

DuplexCallbackInfo now uses StreamInstant fields directly, matching the existing
Input/OutputCallbackInfo pattern.

Author: gulbrand

CHANGELOG.md

@@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - `DeviceTrait::build_duplex_stream` and `build_duplex_stream_raw` for synchronized input/output.
-- `duplex` module with `DuplexStreamConfig`, `AudioTimestamp`, and `DuplexCallbackInfo` types.
+- `duplex` module with `DuplexStreamConfig` and `DuplexCallbackInfo` types.
 - **CoreAudio**: Duplex stream support with hardware-synchronized input/output.
 - Example `duplex_feedback` demonstrating duplex stream usage.
 - `DeviceBusy` error variant for retriable device access errors (EBUSY, EAGAIN).
@@ -19,7 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- **BREAKING**: `DeviceTrait` now requires `DuplexStream` associated type and `build_duplex_stream_raw()` method. External implementations must add stubs returning `StreamConfigNotSupported`.
+- **BREAKING**: `DeviceTrait` now includes `build_duplex_stream()` and `build_duplex_stream_raw()` methods. The default implementation returns `StreamConfigNotSupported`, so external implementations are compatible without changes.
 - Overall MSRV increased to 1.78.
 - **ALSA**: Update `alsa` dependency from 0.10 to 0.11.
 - **ALSA**: MSRV increased from 1.77 to 1.82 (required by alsa-sys 0.4.0).

README.md

@@ -28,6 +28,7 @@ This library currently supports the following:
 - Enumerate known supported input and output stream formats for a device.
 - Get the current default input and output stream formats for a device.
 - Build and run input and output PCM streams on a chosen device with a given stream format.
+- Build and run duplex (simultaneous input/output) streams with hardware clock synchronization (macOS only, more platforms coming soon).
 
 Currently, supported hosts include:
 
@@ -209,6 +210,7 @@ CPAL comes with several examples demonstrating various features:
 - `beep` - Generate a simple sine wave tone
 - `enumerate` - List all available audio devices and their capabilities
 - `feedback` - Pass input audio directly to output (microphone loopback)
+- `duplex_feedback` - Hardware-synchronized duplex stream loopback (macOS only)
 - `record_wav` - Record audio from the default input device to a WAV file
 - `synth_tones` - Generate multiple tones simultaneously
 

examples/custom.rs

@@ -54,7 +54,6 @@ impl DeviceTrait for MyDevice {
     type SupportedInputConfigs = std::iter::Empty<cpal::SupportedStreamConfigRange>;
     type SupportedOutputConfigs = std::iter::Once<cpal::SupportedStreamConfigRange>;
     type Stream = MyStream;
-    type DuplexStream = cpal::duplex::UnsupportedDuplexStream;
 
     fn name(&self) -> Result<String, cpal::DeviceNameError> {
         Ok(String::from("custom"))
@@ -190,7 +189,7 @@ impl DeviceTrait for MyDevice {
         _data_callback: D,
         _error_callback: E,
         _timeout: Option<std::time::Duration>,
-    ) -> Result<Self::DuplexStream, cpal::BuildStreamError>
+    ) -> Result<Self::Stream, cpal::BuildStreamError>
     where
         D: FnMut(&cpal::Data, &mut cpal::Data, &cpal::duplex::DuplexCallbackInfo) + Send + 'static,
         E: FnMut(cpal::StreamError) + Send + 'static,

examples/duplex_feedback.rs

@@ -40,16 +40,17 @@ fn main() -> anyhow::Result<()> {
     let opt = Opt::parse();
     let host = cpal::default_host();
 
-    // Find the device.
-    let device = if let Some(device_name) = opt.device {
-        let id = &device_name.parse().expect("failed to parse device id");
-        host.device_by_id(id)
+    // Find the device by device ID or use default
+    let device = if let Some(device_id_str) = opt.device {
+        let device_id = device_id_str.parse().expect("failed to parse device id");
+        host.device_by_id(&device_id)
+            .expect(&format!("failed to find device with id: {}", device_id_str))
     } else {
         host.default_output_device()
-    }
-    .expect("failed to find device");
+            .expect("no default output device")
+    };
 
-    println!("Using device: \"{}\"", device.id()?);
+    println!("Using device: \"{}\"", device.description()?.name());
 
     // Create duplex stream configuration.
     let config = DuplexStreamConfig::new(

src/duplex.rs

@@ -37,139 +37,36 @@
 //! ).expect("failed to build duplex stream");
 //! ```
 
-use crate::{PauseStreamError, PlayStreamError, SampleRate, StreamInstant};
-
-/// Hardware timestamp information from the audio device.
-///
-/// This provides precise timing information from the audio hardware, essential for
-/// sample-accurate synchronization between input and output, and for correlating
-/// audio timing with other system events.
-///
-/// # Detecting Xruns
-///
-/// Applications can detect xruns (buffer underruns/overruns) by tracking the
-/// `sample_time` field across callbacks. Under normal operation, `sample_time`
-/// advances by exactly the buffer size each callback. A larger jump indicates
-/// missed buffers:
-///
-/// ```ignore
-/// let mut last_sample_time: Option<f64> = None;
-///
-/// // In your callback:
-/// if let Some(last) = last_sample_time {
-///     let expected = last + buffer_size as f64;
-///     let discontinuity = (info.timestamp.sample_time - expected).abs();
-///     if discontinuity > 1.0 {
-///         println!("Xrun detected: {} samples missed", discontinuity);
-///     }
-/// }
-/// last_sample_time = Some(info.timestamp.sample_time);
-/// ```
-#[derive(Clone, Copy, Debug, PartialEq)]
-pub struct AudioTimestamp {
-    /// Hardware sample counter from the device clock.
-    ///
-    /// This is the authoritative position from the device's clock and increments
-    /// by the buffer size each callback. Use this for xrun detection by tracking
-    /// discontinuities.
-    ///
-    /// This is an f64 to allow for sub-sample precision in rate-adjusted scenarios.
-    /// For most purposes, cast to i64 for an integer value.
-    pub sample_time: f64,
-
-    /// System host time reference (platform-specific high-resolution timer).
-    ///
-    /// Can be used to correlate audio timing with other system events or for
-    /// debugging latency issues.
-    pub host_time: u64,
-
-    /// Clock rate scalar (1.0 = nominal rate).
-    ///
-    /// Indicates if the hardware clock is running faster or slower than nominal.
-    /// Useful for applications that need to compensate for clock drift when
-    /// synchronizing with external sources.
-    pub rate_scalar: f64,
-
-    /// Callback timestamp from cpal's existing timing system.
-    ///
-    /// This provides compatibility with cpal's existing `StreamInstant` timing
-    /// infrastructure.
-    pub callback_instant: StreamInstant,
-}
-
-impl AudioTimestamp {
-    /// Create a new AudioTimestamp.
-    pub fn new(
-        sample_time: f64,
-        host_time: u64,
-        rate_scalar: f64,
-        callback_instant: StreamInstant,
-    ) -> Self {
-        Self {
-            sample_time,
-            host_time,
-            rate_scalar,
-            callback_instant,
-        }
-    }
-
-    /// Get the sample position as an integer.
-    ///
-    /// This rounds the hardware sample time to the nearest integer. The result
-    /// is suitable for use as a timeline position or for sample-accurate event
-    /// scheduling.
-    #[inline]
-    pub fn sample_position(&self) -> i64 {
-        self.sample_time.round() as i64
-    }
-
-    /// Check if the clock is running at nominal rate.
-    ///
-    /// Returns `true` if `rate_scalar` is very close to 1.0 (within 0.0001).
-    #[inline]
-    pub fn is_nominal_rate(&self) -> bool {
-        (self.rate_scalar - 1.0).abs() < 0.0001
-    }
-}
-
-impl Default for AudioTimestamp {
-    fn default() -> Self {
-        Self {
-            sample_time: 0.0,
-            host_time: 0,
-            rate_scalar: 1.0,
-            callback_instant: StreamInstant::new(0, 0),
-        }
-    }
-}
+use crate::{SampleRate, StreamInstant};
 
 /// Information passed to duplex callbacks.
 ///
-/// This contains timing information and metadata about the current audio buffer,
-/// including latency-adjusted timestamps for input capture and output playback.
-#[derive(Clone, Copy, Debug)]
+/// This contains timing information for the current audio buffer, combining
+/// both input and output timing similar to [`InputCallbackInfo`](crate::InputCallbackInfo)
+/// and [`OutputCallbackInfo`](crate::OutputCallbackInfo).
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub struct DuplexCallbackInfo {
-    /// Hardware timestamp for this callback.
-    pub timestamp: AudioTimestamp,
+    /// The instant the stream's data callback was invoked.
+    pub callback: StreamInstant,
 
-    /// Estimated time when the input audio was captured.
+    /// The instant that input data was captured from the device.
     ///
-    /// This is calculated by subtracting the device latency from the callback time,
-    /// representing when the input samples were actually captured by the hardware.
+    /// This is calculated by subtracting the input device latency from the callback time,
+    /// representing when the input samples were actually captured by the hardware (e.g., by an ADC).
     pub capture: StreamInstant,
 
-    /// Estimated time when the output audio will be played.
+    /// The predicted instant that output data will be delivered to the device for playback.
     ///
-    /// This is calculated by adding the device latency to the callback time,
-    /// representing when the output samples will actually reach the hardware.
+    /// This is calculated by adding the output device latency to the callback time,
+    /// representing when the output samples will actually be played by the hardware (e.g., by a DAC).
     pub playback: StreamInstant,
 }
 
 impl DuplexCallbackInfo {
     /// Create a new DuplexCallbackInfo.
-    pub fn new(timestamp: AudioTimestamp, capture: StreamInstant, playback: StreamInstant) -> Self {
+    pub fn new(callback: StreamInstant, capture: StreamInstant, playback: StreamInstant) -> Self {
         Self {
-            timestamp,
+            callback,
             capture,
             playback,
         }
@@ -254,104 +151,19 @@ impl DuplexStreamConfig {
     }
 }
 
-/// A placeholder duplex stream type for backends that don't yet support duplex.
-///
-/// This type implements `StreamTrait` but all operations return errors.
-/// Backend implementations should replace this with their own type once
-/// duplex support is implemented.
-#[derive(Default)]
-pub struct UnsupportedDuplexStream;
-
-impl UnsupportedDuplexStream {
-    /// Create a new unsupported duplex stream marker.
-    ///
-    /// This should not normally be called - it exists only to satisfy
-    /// type requirements for backends without duplex support.
-    pub fn new() -> Self {
-        Self
-    }
-}
-
-impl crate::traits::StreamTrait for UnsupportedDuplexStream {
-    fn play(&self) -> Result<(), PlayStreamError> {
-        Err(PlayStreamError::BackendSpecific {
-            err: crate::BackendSpecificError {
-                description: "Duplex streams are not yet supported on this backend".to_string(),
-            },
-        })
-    }
-
-    fn pause(&self) -> Result<(), PauseStreamError> {
-        Err(PauseStreamError::BackendSpecific {
-            err: crate::BackendSpecificError {
-                description: "Duplex streams are not yet supported on this backend".to_string(),
-            },
-        })
-    }
-}
-
-// Safety: UnsupportedDuplexStream contains no mutable state
-unsafe impl Send for UnsupportedDuplexStream {}
-unsafe impl Sync for UnsupportedDuplexStream {}
-
 #[cfg(test)]
 mod tests {
     use super::*;
 
-    #[test]
-    fn test_audio_timestamp_sample_position() {
-        let ts = AudioTimestamp::new(1234.5, 0, 1.0, StreamInstant::new(0, 0));
-        assert_eq!(ts.sample_position(), 1235); // rounds up
-
-        let ts = AudioTimestamp::new(1234.4, 0, 1.0, StreamInstant::new(0, 0));
-        assert_eq!(ts.sample_position(), 1234); // rounds down
-
-        let ts = AudioTimestamp::new(-100.0, 0, 1.0, StreamInstant::new(0, 0));
-        assert_eq!(ts.sample_position(), -100); // negative values work
-    }
-
-    #[test]
-    fn test_audio_timestamp_nominal_rate() {
-        let ts = AudioTimestamp::new(0.0, 0, 1.0, StreamInstant::new(0, 0));
-        assert!(ts.is_nominal_rate());
-
-        let ts = AudioTimestamp::new(0.0, 0, 1.00005, StreamInstant::new(0, 0));
-        assert!(ts.is_nominal_rate()); // within tolerance
-
-        let ts = AudioTimestamp::new(0.0, 0, 1.001, StreamInstant::new(0, 0));
-        assert!(!ts.is_nominal_rate()); // outside tolerance
-    }
-
-    #[test]
-    fn test_audio_timestamp_default() {
-        let ts = AudioTimestamp::default();
-        assert_eq!(ts.sample_time, 0.0);
-        assert_eq!(ts.host_time, 0);
-        assert_eq!(ts.rate_scalar, 1.0);
-        assert_eq!(ts.sample_position(), 0);
-        assert!(ts.is_nominal_rate());
-    }
-
-    #[test]
-    fn test_audio_timestamp_equality() {
-        let ts1 = AudioTimestamp::new(1000.0, 12345, 1.0, StreamInstant::new(0, 0));
-        let ts2 = AudioTimestamp::new(1000.0, 12345, 1.0, StreamInstant::new(0, 0));
-        let ts3 = AudioTimestamp::new(1000.0, 12346, 1.0, StreamInstant::new(0, 0));
-
-        assert_eq!(ts1, ts2);
-        assert_ne!(ts1, ts3);
-    }
-
     #[test]
     fn test_duplex_callback_info() {
         let callback = StreamInstant::new(1, 0);
         let capture = StreamInstant::new(0, 500_000_000); // 500ms before callback
         let playback = StreamInstant::new(1, 500_000_000); // 500ms after callback
 
-        let ts = AudioTimestamp::new(512.0, 1000, 1.0, callback);
-        let info = DuplexCallbackInfo::new(ts, capture, playback);
+        let info = DuplexCallbackInfo::new(callback, capture, playback);
 
-        assert_eq!(info.timestamp.sample_time, 512.0);
+        assert_eq!(info.callback, callback);
         assert_eq!(info.capture, capture);
         assert_eq!(info.playback, playback);
     }
@@ -421,30 +233,4 @@ mod tests {
         let config3 = DuplexStreamConfig::new(2, 4, 44100, crate::BufferSize::Fixed(512));
         assert_ne!(config1, config3);
     }
-
-    #[test]
-    fn test_unsupported_duplex_stream() {
-        use crate::traits::StreamTrait;
-
-        let stream = UnsupportedDuplexStream::new();
-
-        // play() should return an error
-        let play_result = stream.play();
-        assert!(play_result.is_err());
-
-        // pause() should return an error
-        let pause_result = stream.pause();
-        assert!(pause_result.is_err());
-    }
-
-    #[test]
-    fn test_unsupported_duplex_stream_default() {
-        let _stream = UnsupportedDuplexStream::default();
-    }
-
-    #[test]
-    fn test_unsupported_duplex_stream_send_sync() {
-        fn assert_send_sync<T: Send + Sync>() {}
-        assert_send_sync::<UnsupportedDuplexStream>();
-    }
 }

src/host/aaudio/mod.rs

@@ -115,18 +115,6 @@ pub struct Host;
 #[derive(Clone)]
 pub struct Device(Option<AudioDeviceInfo>);
 
-pub struct DuplexStream(pub crate::duplex::UnsupportedDuplexStream);
-
-impl StreamTrait for DuplexStream {
-    fn play(&self) -> Result<(), PlayStreamError> {
-        StreamTrait::play(&self.0)
-    }
-
-    fn pause(&self) -> Result<(), PauseStreamError> {
-        StreamTrait::pause(&self.0)
-    }
-}
-
 /// Stream wraps AudioStream in Arc<Mutex<>> to provide Send + Sync semantics.
 ///
 /// While the underlying ndk::audio::AudioStream is neither Send nor Sync in ndk 0.9.0
@@ -395,7 +383,6 @@ impl DeviceTrait for Device {
     type SupportedInputConfigs = SupportedInputConfigs;
     type SupportedOutputConfigs = SupportedOutputConfigs;
     type Stream = Stream;
-    type DuplexStream = DuplexStream;
 
     fn name(&self) -> Result<String, DeviceNameError> {
         match &self.0 {