feat: stable Device::id() #1014

xephyris · 2025-09-23T02:43:39Z

This PR adds a Device::id() command that returns the OS native device id on supported operating systems.
~~Currently, only macOS and Windows (WASAPI) are supported.~~

Function

By returning a Device::id(), it will be easier to ensure that the same device gets connected on application startup. This also allows for greater extension capability for other libraries to extend upon cpal function.

Architecture

The OS specific device ids are all stored in a DeviceId enum, that allows for support for the various data types that different operating systems and APIs use to store device ids (e.g. u32 for macOS and String for WASAPI.

#[derive(Clone, Debug, Eq, PartialEq)]
pub enum DeviceId {
    CoreAudio(String),
    WASAPI(String),
    // ..
}

To handle any errors that might be outputted in when running Device::id(), there is also a new DeviceIdError enum

#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub enum DeviceIdError {
    /// See the [`BackendSpecificError`] docs for more information about this error variant.
    BackendSpecific { err: BackendSpecificError },
    UnsupportedOS,
    ParseError,
}

Calling Device::id() will return a Result<DeviceId, DeviceIdError>. If the OS is supported and the device id is obtained, it will return a DeviceId. If the OS is unsupported, a DeviceIdError::UnsupportedOS error will be returned.

Current Status

~~Currently, support for Windows WASAPI String Ids has been added, along with support for macOS u32 Ids. I am working to add support for ALSA and maybe pulseaudio (once that gets merged).~~

For other APIs, I do not have the hardware to test or program for them, ~~so they currently return a DeviceIdError::UnsupportedOS error.~~

Testing

Device::id() for macOS should return the ~~standard u32~~ device uid that can be used anywhere.
For Windows, to convert the Rust String type to a PWSTR, the following code can be used

// device_id is the id returned by cpal
 let mut id = format!("{}\0", device_id).encode_utf16().collect::<Vec<u16>>(); 
 let pwstr = PWSTR(id.as_mut_ptr());

…mplementations

…ility

roderickvd

This is great! Your proposal literally crossed paths as I was working on something also. No matter, all the better I could provide some review comments with actual code suggestions.

Please also add a changelog, it's worth it 😄

src/lib.rs

src/host/null/mod.rs

src/traits.rs

src/lib.rs

…es, and more

xephyris · 2025-09-25T06:59:31Z

Hello @roderickvd !

I have implemented most of the changes requested and renamed the enum variants to the suggested names.

For jack and aaudio, I just copied the code that you provided, and because I cannot test it, there may or may not be some errors.

I have also added alsa support which currently just returns the same content as name, because I was unable to find any other specific identifiers that could work better.

I will work on changing the macOS CoreAudio type to kAudioDevicePropertyDeviceUID in the coming days.

The changelog has also been updated 😄.

roderickvd · 2025-09-25T19:29:09Z

Cool stuff let me know when you're ready for me to take another look.

…nstead of u32

xephyris · 2025-09-26T02:32:13Z

I have finished the changes and now DeviceId::CoreAudio has a String type instead of u32.

One thing that I noticed was that there was already a uid() function in loopback.rs for Device, however I wasn't sure if it should be moved into device.rs or not as it seems to rely on some types inside of loopback.rs.

The code I'm currently using is basically 90% the same as the uid() function, just with a different return type. If needed, I can attempt moving the uid() function over into device.rs

roderickvd

Some ideas and one point about the macOS implementation.

src/host/coreaudio/macos/device.rs

CHANGELOG.md

src/host/asio/device.rs

src/host/coreaudio/ios/mod.rs

src/host/emscripten/mod.rs

src/host/webaudio/mod.rs

src/lib.rs

roderickvd

Thanks for sticking through 👍 this is a pretty important feature so let's get it right!

src/host/coreaudio/macos/device.rs

src/host/wasapi/device.rs

src/host/coreaudio/ios/mod.rs

CHANGELOG.md

src/host/coreaudio/macos/device.rs

roderickvd · 2025-10-18T17:08:12Z

Thanks, I’ll review later as I’m away for a few days.

xephyris · 2025-11-12T08:17:15Z

Hello @roderickvd,

Just wondering if you were available to review the updates, as I was hoping to get the device_ids integrated as soon as possible.

If it comes at an inconvenient time, I'm happy to wait.

roderickvd

Thanks for the ping and sorry for the wait. Yes lots of work done, thanks for that. Here's a few hopefully small ones.

src/lib.rs

src/host/coreaudio/macos/device.rs

roderickvd · 2025-11-13T00:43:18Z

src/lib.rs

+            "emscripten" => Ok(DeviceId::Emscripten(data.to_string())),
+            "ios" => Ok(DeviceId::IOS(data.to_string())),
+            "null" => Ok(DeviceId::Null),
+            &_ => todo!("implement DeviceId::FromStr for {platform}"),


I know we discussed this earlier but I find myself doubting here.
Should we panic here or return DeviceIdError::UnsupportedPlatform?

I think a DeviceIdError::UnsuportedPlatform would be better in this case as it would leave more flexibility for the end user, if they want their application to panic if the API is unsupported that option is allowed, but we also give them the option to accept it as an error instead of crashing their app.

…iceId

roderickvd · 2025-11-14T00:21:09Z

Thanks for all the work and updating with the custom host support. I wonder if we can support custom hosts better in the future, but that can be added later if necessary.

Eager to get this out with v0.17 and see the community response!

xephyris and others added 9 commits September 13, 2025 23:10

feat: add device_id support for macOS to DeviceTrait

8cc6f25

fix: fix import statements for other APIs

9161bbb

wip: use DeviceId enum instead to work around conflicting device_id i…

845baac

…mplementations

feat: transition to using DeviceId for enum for better cross compatib…

bd9b071

…ility

docs: add description for DeviceId

60c3c26

feat: implemented device id for windows wasapi

2a93a70

docs: update description

fb1efd0

fix: reformat existing code and fix android build error

626b823

feat: add ALSA support to device id() function

c9d6b05

xephyris marked this pull request as ready for review September 24, 2025 16:08

roderickvd added enhancement platform - windows platform - macos labels Sep 24, 2025

roderickvd requested changes Sep 24, 2025

View reviewed changes

src/lib.rs Outdated Show resolved Hide resolved

src/lib.rs Outdated Show resolved Hide resolved

src/host/null/mod.rs Outdated Show resolved Hide resolved

src/traits.rs Show resolved Hide resolved

src/lib.rs Outdated Show resolved Hide resolved

src/lib.rs Outdated Show resolved Hide resolved

xephyris added 5 commits September 24, 2025 21:54

fix: resolve merge conflicts

6f8587f

feat: add support for jack and aaudio (untested). fix naming structur…

24ef5ac

…es, and more

docs: update changelog

8b5b8d0

fix: fix function names causing compile errors

068e171

fix: fix aaudio DeviceId type

f9301b8

xephyris added 2 commits September 25, 2025 19:26

feat: implement macos DeviceId to use kAudioDevicePropertyDeviceUID i…

2972b52

…nstead of u32

fmt: reformat with rustfmt

99fc8b7

xephyris requested a review from roderickvd September 26, 2025 02:32

roderickvd requested changes Sep 26, 2025

View reviewed changes

xephyris added 4 commits September 26, 2025 19:00

docs: update changelog

43bc3e0

feat: add asio support and reformat macos id function

6e93a1b

fmt: reformat code

59f4a9f

feat: return default for ios, emscripten, and webaudio

b811266

roderickvd reviewed Oct 6, 2025

View reviewed changes

src/host/coreaudio/macos/device.rs Outdated Show resolved Hide resolved

src/host/wasapi/device.rs Show resolved Hide resolved

src/host/coreaudio/ios/mod.rs Show resolved Hide resolved

CHANGELOG.md Outdated Show resolved Hide resolved

xephyris added 3 commits October 6, 2025 22:20

docs: fix changelog

01a240d

refactor: improve safety of get_id() function, remove CFStringRef

6eb9e7a

fmt: run rustfmt

d516476

yury reviewed Oct 10, 2025

View reviewed changes

src/host/coreaudio/macos/device.rs Outdated Show resolved Hide resolved

xephyris and others added 6 commits October 13, 2025 16:12

fix: resolve wrap_under rule error for CFString

5c56868

fix: Merge branch 'master' into master

82b4abd

fix: add Stream import to coreaudio

ab3b8a2

Merge remote-tracking branch 'upstream/master'

fa1c0d7

fix: return backend error on parse error for PWSTR

7bc3c4f

fmt: run cargo fmt

3580a67

xephyris requested a review from roderickvd October 18, 2025 14:17

roderickvd requested changes Nov 13, 2025

View reviewed changes

xephyris and others added 11 commits November 12, 2025 17:03

merge: merge remote-tracking branch 'upstream/master'

e544436

docs: update relevant documentation for DeviceId

59baa53

feat: remove ParseError and replace with BackendSpecificError for Dev…

4c5a744

…iceId

fmt: run cargo fmt

59db290

merge: merge branch 'master' into master

f426526

fix: add unsupported id() for custom device

8c96975

fix: add id() for custom device

9ddd8b7

fix: add id() to DeviceErased trait

823a931

fix: fix ios build error

81af674

fmt: run cargo fmt

fa1c41b

Merge branch 'master' into master

ea84a39

roderickvd merged commit 11dea8d into RustAudio:master Nov 14, 2025
17 checks passed

This was referenced Nov 14, 2025

Add a (serialisable) means to uniquely identify a device #922

Closed

feat: introduce description() for devices #1046

Open

feat: stable Device::id() #1014

feat: stable Device::id() #1014

Uh oh!

Conversation

xephyris commented Sep 23, 2025 • edited by roderickvd Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Function

Architecture

Current Status

Testing

Uh oh!

roderickvd left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

xephyris commented Sep 25, 2025

Uh oh!

roderickvd commented Sep 25, 2025

Uh oh!

xephyris commented Sep 26, 2025

Uh oh!

roderickvd left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

roderickvd left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

roderickvd commented Oct 18, 2025

Uh oh!

xephyris commented Nov 12, 2025

Uh oh!

roderickvd left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

roderickvd Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

xephyris Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

roderickvd commented Nov 14, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

xephyris commented Sep 23, 2025 •

edited by roderickvd

Loading