Skip to content

Revamped API - #111

Open
SolarLiner wants to merge 45 commits into
mainfrom
refactoring/design-v2
Open

Revamped API#111
SolarLiner wants to merge 45 commits into
mainfrom
refactoring/design-v2

Conversation

@SolarLiner

@SolarLiner SolarLiner commented Nov 1, 2025

Copy link
Copy Markdown
Owner

Supersedes #31.

Description

This PR changes the design around audio devices, streams and callbacks. Instead of separate input and output traits and types, they are now fused into one, as this is a runtime distinction and not a compile-time one.

This PR will also remove bitflags for choosing which inputs/outputs are opened, and instead opts for the more natural choice of specifying a number of audio channels.

Closes #29.

Type of Change

Please delete options that are not relevant.

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Code cleanup or refactor

How Has This Been Tested?

Please describe the tests you added or ran to verify your changes. Provide instructions so we can reproduce. Try to run
on as many audio drivers as you can get your hands on.

  • CI
  • Local testing on CoreAudio, as well as VM testing for ALSA/PipeWire

Checklist:

  • My code follows the style guidelines of this project
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • Wherever possible, I have added tests that prove my fix is effective or that my feature works. For changes that
    need to be validated manually (i.e. a new audio driver), use examples that can be run to easily validate them.
  • New and existing unit tests pass locally with my changes
  • I have checked my code and corrected any misspellings

@SolarLiner
SolarLiner requested a review from geom3trik as a code owner November 1, 2025 19:18
@SolarLiner SolarLiner self-assigned this Nov 1, 2025
@SolarLiner SolarLiner added meta Meta PR (about the project itself) api Issues regarding the general API design labels Nov 1, 2025
Signed-off-by: Nathan Graule <solarliner@gmail.com>
@SolarLiner
SolarLiner marked this pull request as draft November 1, 2025 19:21
@SolarLiner SolarLiner mentioned this pull request Nov 1, 2025
12 tasks
@SolarLiner SolarLiner added this to the 0.1.0 milestone Nov 1, 2025
@github-project-automation github-project-automation Bot moved this to Todo in Backlog Nov 1, 2025
@SolarLiner SolarLiner moved this from Todo to In Progress in Backlog Nov 1, 2025
@SolarLiner SolarLiner mentioned this pull request Nov 1, 2025
12 tasks
Comment thread examples/duplex.rs Outdated
@SolarLiner SolarLiner linked an issue Feb 11, 2026 that may be closed by this pull request
Signed-off-by: Nathan Graule <solarliner@gmail.com>

# Conflicts:
#	Cargo.lock
#	Cargo.toml
#	src/backends/alsa/stream.rs
#	src/backends/pipewire/stream.rs
@SolarLiner
SolarLiner force-pushed the refactoring/design-v2 branch from 9049442 to 7135dc7 Compare July 23, 2026 21:56
@SolarLiner
SolarLiner force-pushed the refactoring/design-v2 branch from b7a21a7 to c47abeb Compare July 25, 2026 15:08
@SolarLiner SolarLiner mentioned this pull request Jul 25, 2026
@SolarLiner

Copy link
Copy Markdown
Owner Author

@Be-ing, @mbernat @strohel sorry for the ping but I thought you might be interested in seeing this. This new API has now matured a little bit, and I have successfully implemented both a CoreAudio and WASAPI backend for it. I believe it is both better ergonomics, the lookup function / extension system is great for optional or non-cross-platform features (and can be used to retrieve the concrete type from a proxy), and simplifies the general use-case of simply wanting an audio callback to process.

It's a significant shift in the API, so it will break everything. I'm open to feedback and suggestions!

@SolarLiner SolarLiner changed the title Draft: Revamped API Revamped API Jul 25, 2026
@SolarLiner
SolarLiner marked this pull request as ready for review July 25, 2026 15:14
Comment on lines +75 to +81
let Some(flow) = bitflags_match!(device_type, {
DeviceType::INPUT => Some(Audio::eCapture),
DeviceType::OUTPUT => Some(Audio::eRender),
_ => None,
}) else {
return Ok(None);
};

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi, I currently cannot run the sine-wave example, because ^this doesn't match on the requested DeviceType::OUTPUT | DeviceType::PHYSICAL (it lands in the wildcard branch and returns Ok(None)). I just discovered interflow and thus know absolutely nothing about it yet, so I can't judge whether it is the example or the platform impl that is wrong, but I know a little bit about WASAPI, and I don't think it has a notion of "physical" devices. E.g. my USB audio interface is recognized as a single 12 channel device by ASIO, but 6 Stereo devices by WASAPI. Hope this helps!

@SolarLiner SolarLiner Aug 8, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Physical" is a device connected to physical speakers, as opposed to "virtual" devices which can be output monitors, or specific applications' output. So yes, it is correct that interflow lists your sound card's I/O as stereo pairs, even though there is only one physical sound card, because that's what WASAPI advertises, somewhat confusingly. An ASIO backend will correctly report a single device, with multichannel I/O.

The code indeed has a bug here, I misunderstood what the match macro does with bit flags. I'll need to change that; but that being said, I also have a USB audio interface and I've tested the WASAPI backend with it, it works correctly.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops, I had assumed it was physical as opposed to "logical" instead. My bad. But then I have to ask: Why care about this difference? And how does the platform even know whether a given driver represents a physical or virtual device?

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On most platforms the query for stuff like application output signals is different from asking for actual devices, so the distinction will be made there. For other platforms it might be more complicated, and I guess there might also be confusion between virtual device drivers (e.g., VoiceMeeter on Windows, or Black Hole on macOS) that will appear as "physical" devices. Maybe better naming is required here.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Welp, looks like I had the wrong idea again then, because I was indeed thinking of virtual device drivers 😅 But I think I get it now. This is conceptually exclusive to platforms which have a central sound server, right? (My expertise is primarily with ASIO, which doesn't)

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not necessarily, as long as the server backend has metadata to distinguish port types (e.g., PipeWire tells you if the port is from a "physical" device, or the output signal from another node or application). I don't think there's a way for ASIO to have "virtual" devices, or connections between applications, so in that case you'll only get "physical" devices.

Comment thread .vscode/settings.json Outdated
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

api Issues regarding the general API design meta Meta PR (about the project itself)

Projects

Status: In Progress

Development

Successfully merging this pull request may close these issues.

Get rid of ndarray API additions for duplex devices

4 participants