feat: stable Device::id()

[xephyris]

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());

[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 😄

[xephyris]

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]

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

[xephyris]

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.

[xephyris]

I have updated the ASIO configuration and fixed the naming for macOS.

I have also made emscripten, webaudio, and iOS return Ok(DeviceId::"API_NAME"("default")) instead of an error.

Currently, I think it is fine as all three of those APIs seem to only return the default device, however I think if they were expanded to be able to select audio devices, it would be better to leave them returning DeviceIdError::UnsupportedPlatform than default, as if someone were to save the id while a different device is selected, it would incorrectly select the device.

As for the syncing issue, I'm unsure about what you mean, would you care to elaborate?

[roderickvd]

From your PR description, which I edited to show the progress made since:

For Windows, to convert the Rust String type to a PWSTR, the following code can be used

Is that still necessary?

[xephyris]

Thanks for the update @roderickvd ! I'll try getting the code updated soon for another review.

Is that still necessary?

Currently I believe it is still necessary to convert it to a PWSTR because to get the IMMDevice from the IMMDeviceEnumerator, it requires a PWSTR at least from what I recall.

This is primarily for if you are using the Device::id() to extend upon cpal functionality like I'm currently working on cpvc and adding the volume controls. If you are just trying to re-select a device from cpal, then that code to convert to PWSTR isn't necessary.

[roderickvd]

But it already does pwstr.to_string() right in src/host/wasapi/device.rs line 332?

I don't have a Windows machine myself, so am trying to understand.

[xephyris]

So right now I'm having it return the Device::id() as a String guid for Windows and if you iterate with device_by_id(id) to get the device, it will work fine.

The snippet about PWSTR that I included is mainly for if you want to access a Windows WASAPI audio device yourself using the id provided by cpal.

That code is more about external access using the ids from cpal, not if you are only using cpal to access and adjust audio devices.

[roderickvd]

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

[roderickvd]

Could we remove this in favor of plain CFString and be less unsafe?

  fn id(&self) -> Result<DeviceId, DeviceIdError> {
      let property_address = AudioObjectPropertyAddress {
          mSelector: kAudioDevicePropertyDeviceUID,
          mScope: kAudioObjectPropertyScopeGlobal,
          mElement: kAudioObjectPropertyElementMain,
      };

      // CFString is retained by the audio object, use wrap_under_get_rule
      let mut uid: *const CFString = std::ptr::null();
      let data_size = size_of::<*const CFString>() as u32;

      // SAFETY: AudioObjectGetPropertyData is documented to write a CFString pointer
      // for kAudioDevicePropertyDeviceUID. We check the status code before use.
      let status = unsafe {
          AudioObjectGetPropertyData(
              self.audio_device_id,
              NonNull::from(&property_address),
              0,
              null(),
              NonNull::from(&data_size),
              NonNull::from(&mut uid).cast(),
          )
      };

      check_os_status(status)?;

      if uid.is_null() {
          return Err(DeviceIdError::BackendSpecific {
              err: BackendSpecificError {
                  description: "Device UID is null".to_string(),
              },
          });
      }

      // SAFETY: We verified uid is non-null and the status was successful
      let uid_string = unsafe { CFString::wrap_under_get_rule(uid).to_string() };
      Ok(DeviceId::CoreAudio(uid_string))
  }

[roderickvd]

Instead of silently discarding, we could:

  fn id(&self) -> Result<DeviceId, DeviceIdError> {
      // SAFETY: Calling GetId on a valid IMMDevice is safe
      unsafe {
          let pwstr = self.device.GetId().map_err(|e| DeviceIdError::BackendSpecific {
              err: e.into(),
          })?;

          let id_str = pwstr.to_string().map_err(|e| DeviceIdError::BackendSpecific {
              err: BackendSpecificError { description: format!("Failed to convert device ID to string: {}", e) },
          })?;

          Ok(DeviceId::WASAPI(id_str))
      }
  }

[roderickvd]

"default" differs from "Default Device" in name. Maybe use shared const?

[xephyris]

I'm slightly unsure about this change, as in most conventions an id would not have spaces inside of it, so I feel like "default" does a better job of this. DeviceIds and names also do not intermix so I don't believe this will be much of an issue either.

Of course if the general consensus is that "Default Device" is better than "default", I would be happy to change it.

[roderickvd]

Good rationale, let’s keep it like it this then.

How do you feel this’ll be for ALSA? Spaces in device names (e.g. for USB devices) would not be impossible.