Duplex support

[gulbrand]

UPDATE on AI Usage

I've since reviewed the Rust Audio AI policy and want to be fully transparent: the implementation in this PR was generated by Claude Code under my direction and design. While I provided the architectural decisions, API design, and iterative feedback throughout development, the code itself was AI-generated rather than human-written with AI review.

I understand this likely falls outside the policy's acceptable use guidelines, regardless of the level of human oversight involved. I respect the community's concerns around maintainer burden and copyright, and I'll defer to the maintainers on how to proceed.

If this work is useful as a reference or design proposal, I'm happy for it to serve that purpose. If the preference is to close the PR, I completely understand.

Add synchronized duplex stream support

Summary

This PR introduces synchronized duplex streams to cpal, starting with CoreAudio support on macOS. Duplex streams provide hardware-level clock synchronization between audio input and output, eliminating the need for ring buffers and manual latency management and synchoronization between separate audio callbacks (one for input and one for output). With this change, one callback handles both input and output.

Development Note

Developed with assistance from Claude Code (Anthropic's AI coding assistant).

Motivation

Currently, applications requiring synchronized input/output (like DAWs, real-time effects, or audio analysis tools) must use separate input and output streams with ring buffers for synchronization. This approach:

• Adds latency due to buffering
• Requires manual synchronization logic
• Can experience drift between input and output clocks
• Is more complex to implement correctly

Duplex streams solve this by using a single device context for both input and output, guaranteeing sample-accurate alignment at the hardware level.

API Overview

use cpal::duplex::DuplexStreamConfig;
use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};

let host = cpal::default_host();
let device = host.default_output_device()?;

let config = DuplexStreamConfig::symmetric(2, 48000, BufferSize::Fixed(512));

let stream = device.build_duplex_stream::<f32, _, _>(
    &config,
    |input, output, info| {
        // Process audio with guaranteed synchronization
        output.copy_from_slice(input);
    },
    |err| eprintln!("Stream error: {}", err),
    None,
)?;

stream.play()?;

Example Comparison

See examples/duplex_feedback.rs for a complete example. Compare with examples/feedback.rs to see the simplification:

Before (separate streams):

• Ring buffer setup and management
• Manual latency calculation
• Two separate callbacks
• Producer/consumer synchronization

After (duplex stream):

• Single callback
• Direct buffer copy
• Hardware-guaranteed synchronization

Current Status

• ✅ CoreAudio (macOS): Fully implemented and tested
• ⏳ ASIO (Windows): Planned
• ⏳ ALSA (Linux): Planned

Potentially Breaking Changes

build_duplex_stream and build_duplex_stream_raw have been added to DeviceTrait with a default impl. This shouldn't break any existing implementations, but just calling this out.

Future Work

I have a lab setup ready to implement Windows and Linux support once the CoreAudio implementation and API design are reviewed and approved.

Feedback Requested

While I have some audio/DSP programming experience, I'm relatively new to this domain. I'd especially appreciate feedback on:

1. API design: Is the DuplexStreamConfig / build_duplex_stream interface intuitive?
2. Timestamp API: Does AudioTimestamp provide the right information for real-world use cases?
3. Design flaws: Any architectural issues or better approaches I should consider?
4. Platform compatibility: Will this design work well for Windows (WASAPI) and Linux (ALSA)?

Testing

All existing tests pass. New tests added:

• Unit tests for duplex types (DuplexStreamConfig, AudioTimestamp, etc.)
• Integration test for CoreAudio duplex stream creation and playback
• Example demonstrating real-time audio passthrough

[damyanp]

Is there something inherent about supporting duplex streams that makes AudioTimestamp required? Or is this something that would also be useful for normal streams?

[gulbrand]

No I don't think the duplex stream case has a unique or special need for AudioTimestamp (one caveat below). I think it would be helpful for input and output streams as well. But, adding support to input and output streams might be a breaking change? (I'm unsure).

I added it to support sample accurate operations in the application. For example, a DAW with automation events on nodes in a graph needs to know with high degrees of accuracy the sample position as a reference point for position and offset calculations for ramp ups, ramp downs, parameter automation, etc.

I believe it is technically possible to implement those without the hardware clock derived sample offset, but I think the edge case count increases when not doing so.

The only caveat I can think of for duplex is during simultaneous playback and recording in a DAW where its far more convenient to the user for the software to calculate latencies and offsets and adjust the final position of the recorded audio on the timeline. The math is precise (nearly perfectly so) with hardware clock sample offset rather than application-based timing calculations. Not critical though, just far simpler and more precise.

If removing this would be more consistent with the existing API would help, I can do that and then perhaps this concept could be introduced across all APIs in a future PR.

What do you think?

[damyanp]

My opinion here shouldn't have a huge amount of weight since I'm pretty new to this community. But I'll give it anyway :)

For something like this that seems to have had several attempts over the years, I think it might be worth figuring out what the minimum surface area would be for the feature and try and get that supported for all the target platforms.

I haven't looked closely enough to figure out if AudioTimestamp is something that can only be obtained from host-specific data? If it's something that could be entirely derived from information that's already in OutputCallbackInfo then it seems like a no-brainer to remove it for now.

If it is an abstraction that can be provided by all hosts, and would be useful for simplex as well as duplex, then IMO it'd be good to add it to both in one go. I'm not sure what the bar is for introducing breaking changes.

Similar to the concern with breaking changes, I'd suggest having proofs of concept, if not full implementations, for all platforms so we can be confident that the proposed API can work everywhere and won't need to be revised as soon as, say, Windows support is added.

[gulbrand]

Thanks for the feedback. This is helpful.

If I'm reading the feedback correctly, then if I remove the AudioTimestamp change from this, it greatly simplifies the scope since we don't need to worry about testing all the different platforms and host implementations for compatibility with the AudioTimestamp interface. Doing all of that work would be time consuming and is arguably orthogonal to adding duplex support to one platform / host.

Am I understanding the feedback correctly? (If so, I agree and I will remove AudioTimestamp)

[damyanp]

Yes, that's an accurate summary of my feedback.

[gulbrand]

Great, thanks, I'll remove AudioTimestamp

[gulbrand]

PR is updated to remove AudioTimestamp. Any concerns with resolving this conversation?

[Decodetalkers]

I think this line can just be e.to_string()

[gulbrand]

Yep, I changed the rest of them as well. Thanks!

[gulbrand]

PR is updated to change these to to_string. Thank you! Any concerns if I resolve this?

[Decodetalkers]

maybe we also need to collect the thread handler?

[gulbrand]

Ah, good catch. I need to think about this one a bit more, but I think your suggestion is correct because the thread should be joined during drop and without the handle, drop can't join.

I need to make sure I understand how this works. I'll update this comment when I'm more confident on this.

Thanks for pointing this out.

[gulbrand]

Thank you for your feedback!

I dug deeper into this and I have a weakly held opinion that this is fine as-is.

I reviewed the threads and their terminating conditions and to me it looks like the shutdown_tx value does a good enough job of making sure the thread terminates after the StreamInner is dropped.

This thread's sole job is to make sure the property_address value is dropped in the same thread that it is created in ... The CoreAudio docs are not clear to me that this is indeed 100% required, but it is safer to keep the allocation and the drop on the same thread just in case.

That said, I'm working on getting rid of DuplexStream entirely so that the duplex code paths can work with Stream and StreamInner directly. If that works, then this extra code for DuplexDisconnectManager will be deleted and the implementations will be unified to the DisconnectManager.

[gulbrand]

In terms of the join, I think a case could be made to change this code to allow for a join, but I'm not convinced it is necessary for this to be correct. The lifetimes do appear to be correct and the only benefit of joining would be to catch an error.

I agree there is a case to be made for that, but I'd like to try to keep that change and discussion separate from this PR. Is that a reasonable approach?

[gulbrand]

I've updated the PR to reuse the existing DisconnectManager. You're concern is still valid, but I think it should be addressed outside of this PR as it is an existing issue. I think this is ok though. Any concerns if I resolve this?

[Decodetalkers]

what is the meaning of Weak<Mutex>? I cannot understand

[gulbrand]

I believe there the purposes here are:

1. Allow the StreamInner to be dropped regardless of the DisconnectManager's state. Using an Arc means the DisconnectManager will block dropping until it is ready to drop.
2. Additionally this is also the key indication to the thread that is handling disconnect events to exit its while loop.

See the else block here:

If the upgrade from Weak to Arc fails, it means the stream has been dropped and this thread should exit immediately.

        std::thread::spawn(move || {
            while disconnect_rx.recv().is_ok() {
                // Check if stream still exists
                if let Some(stream_arc) = stream_weak_clone.upgrade() {
                    // First, try to pause the stream to stop playback
                    if let Ok(mut stream_inner) = stream_arc.try_lock() {
                        let _ = stream_inner.pause();
                    }

                    // Always try to notify about device disconnection
                    invoke_error_callback(
                        &error_callback_clone,
                        crate::StreamError::DeviceNotAvailable,
                    );
                } else {
                    // Stream is gone, exit the handler thread
                    break;
                }
            }
        });

All of that said, and like I mentioned in the other comment, I am working on removing DuplexStream and DuplexStreamInner which would unify this change onto the existing Stream types and also reuse the existing DisconnectManager. At that point, this area would seem to me to be out of scope for this PR.

Any thoughts on this I should consider?

Thank you!

[Decodetalkers]

I do not know why we need a _private here.. And maybe here just use #[derive(Default)] will be ok

[gulbrand]

I think your suggestion is correct. I am not sure but I think this was added in anticipation of this maybe, possibly, needing an additional field for one of the backends. But now that I've implemented the necessary traits for each backend, it is clear this is not needed. I'll remove this and make this a unit struct.

[gulbrand]

I've updated to PR to not even have this type anymore and to just use the StreamConfigNotSupported error instead.

Any concerns if I resolve this? Thank you!

[roderickvd]

@gulbrand thanks for your contribution. I don't mind the AI usage as long as the output is of high quality and what I'd expect from a seasoned developer.

Let me know when you've addressed @Decodetalkers review points, and are ready for my detailed review.

Very quickly, I like having build_duplex_stream analogous to the input and output stream build functions, but wonder if we need a separate DuplexStream or whether we could unify it with the existing Stream. I admit I've given the latter very little thought, so tell me if I'm missing something entirely obvious.

[gulbrand]

@gulbrand thanks for your contribution. I don't mind the AI usage as long as the output is of high quality and what I'd expect from a seasoned developer.

Let me know when you've addressed @Decodetalkers review points, and are ready for my detailed review.

Very quickly, I like having build_duplex_stream analogous to the input and output stream build functions, but wonder if we need a separate DuplexStream or whether we could unify it with the existing Stream. I admit I've given the latter very little thought, so tell me if I'm missing something entirely obvious.

Agreed. I've updated the PR but need a bit of time to test in separate projects again and to double check the safety claims. I'll ping again once I'm done with testing but I think this PR is in a much better state now.