feat: stable Device::id()

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Unreleased
 
+- Add `DeviceTrait::id` method that returns a stable audio device ID.
+- Add `HostTrait::device_by_id` to select a device by its stable ID.
 - Add `Sample::bits_per_sample` method.
 - Update `audio_thread_priority` to 0.34.
 - AAudio: Configure buffer to ensure consistent callback buffer sizes.

src/error.rs

@@ -65,6 +65,35 @@ impl From<BackendSpecificError> for DevicesError {
     }
 }
 
+/// An error that may occur while attempting to retrieve a device id.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum DeviceIdError {
+    /// See the [`BackendSpecificError`] docs for more information about this error variant.
+    BackendSpecific {
+        err: BackendSpecificError,
+    },
+    UnsupportedPlatform,
+    ParseError,
+}
+
+impl Display for DeviceIdError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::BackendSpecific { err } => err.fmt(f),
+            Self::UnsupportedPlatform => f.write_str("Device ids are unsupported for this OS"),
+            Self::ParseError => f.write_str("Failed to parse the device_id"),
+        }
+    }
+}
+
+impl Error for DeviceIdError {}
+
+impl From<BackendSpecificError> for DeviceIdError {
+    fn from(err: BackendSpecificError) -> Self {
+        Self::BackendSpecific { err }
+    }
+}
+
 /// An error that may occur while attempting to retrieve a device name.
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 pub enum DeviceNameError {

src/host/aaudio/mod.rs

@@ -11,10 +11,10 @@ use java_interface::{AudioDeviceDirection, AudioDeviceInfo};
 
 use crate::traits::{DeviceTrait, HostTrait, StreamTrait};
 use crate::{
-    BackendSpecificError, BufferSize, BuildStreamError, Data, DefaultStreamConfigError,
-    DeviceNameError, DevicesError, InputCallbackInfo, InputStreamTimestamp, OutputCallbackInfo,
-    OutputStreamTimestamp, PauseStreamError, PlayStreamError, SampleFormat, SampleRate,
-    SizedSample, StreamConfig, StreamError, SupportedBufferSize, SupportedStreamConfig,
+    BackendSpecificError, BufferSize, BuildStreamError, Data, DefaultStreamConfigError, DeviceId,
+    DeviceIdError, DeviceNameError, DevicesError, InputCallbackInfo, InputStreamTimestamp,
+    OutputCallbackInfo, OutputStreamTimestamp, PauseStreamError, PlayStreamError, SampleFormat,
+    SampleRate, SizedSample, StreamConfig, StreamError, SupportedBufferSize, SupportedStreamConfig,
     SupportedStreamConfigRange, SupportedStreamConfigsError,
 };
 
@@ -329,6 +329,13 @@ impl DeviceTrait for Device {
         }
     }
 
+    fn id(&self) -> Result<DeviceId, DeviceIdError> {
+        match &self.0 {
+            None => Ok(DeviceId::AAudio(-1)), // Default device
+            Some(info) => Ok(DeviceId::AAudio(info.id)),
+        }
+    }
+
     fn supported_input_configs(
         &self,
     ) -> Result<Self::SupportedInputConfigs, SupportedStreamConfigsError> {

src/host/alsa/mod.rs

@@ -16,9 +16,9 @@ pub use self::enumerate::{default_input_device, default_output_device, Devices};
 use crate::{
     traits::{DeviceTrait, HostTrait, StreamTrait},
     BackendSpecificError, BufferSize, BuildStreamError, ChannelCount, Data,
-    DefaultStreamConfigError, DeviceNameError, DevicesError, FrameCount, InputCallbackInfo,
-    OutputCallbackInfo, PauseStreamError, PlayStreamError, Sample, SampleFormat, SampleRate,
-    StreamConfig, StreamError, SupportedBufferSize, SupportedStreamConfig,
+    DefaultStreamConfigError, DeviceId, DeviceIdError, DeviceNameError, DevicesError, FrameCount,
+    InputCallbackInfo, OutputCallbackInfo, PauseStreamError, PlayStreamError, Sample, SampleFormat,
+    SampleRate, StreamConfig, StreamError, SupportedBufferSize, SupportedStreamConfig,
     SupportedStreamConfigRange, SupportedStreamConfigsError, I24, U24,
 };
 
@@ -96,6 +96,10 @@ impl DeviceTrait for Device {
         Device::name(self)
     }
 
+    fn id(&self) -> Result<DeviceId, DeviceIdError> {
+        Device::id(self)
+    }
+
     fn supported_input_configs(
         &self,
     ) -> Result<Self::SupportedInputConfigs, SupportedStreamConfigsError> {
@@ -347,6 +351,11 @@ impl Device {
         Ok(self.to_string())
     }
 
+    #[inline]
+    fn id(&self) -> Result<DeviceId, DeviceIdError> {
+        Ok(DeviceId::ALSA(self.pcm_id.clone()))
+    }
+
     fn supported_configs(
         &self,
         stream_t: alsa::Direction,

src/host/asio/device.rs

@@ -4,6 +4,8 @@ pub type SupportedOutputConfigs = std::vec::IntoIter<SupportedStreamConfigRange>
 use super::sys;
 use crate::BackendSpecificError;
 use crate::DefaultStreamConfigError;
+use crate::DeviceId;
+use crate::DeviceIdError;
 use crate::DeviceNameError;
 use crate::DevicesError;
 use crate::SampleFormat;
@@ -54,6 +56,10 @@ impl Device {
         Ok(self.driver.name().to_string())
     }
 
+    fn id(&self) -> Result<DeviceId, DeviceIdError> {
+        Ok(DeviceId::ASIO(self.driver.name().to_string()))
+    }
+
     /// Gets the supported input configs.
     /// TODO currently only supports the default.
     /// Need to find all possible configs.

src/host/asio/mod.rs

@@ -2,9 +2,9 @@ extern crate asio_sys as sys;
 
 use crate::traits::{DeviceTrait, HostTrait, StreamTrait};
 use crate::{
-    BuildStreamError, Data, DefaultStreamConfigError, DeviceNameError, DevicesError,
-    InputCallbackInfo, OutputCallbackInfo, PauseStreamError, PlayStreamError, SampleFormat,
-    StreamConfig, StreamError, SupportedStreamConfig, SupportedStreamConfigsError,
+    BuildStreamError, Data, DefaultStreamConfigError, DeviceId, DeviceIdError, DeviceNameError,
+    DevicesError, InputCallbackInfo, OutputCallbackInfo, PauseStreamError, PlayStreamError,
+    SampleFormat, StreamConfig, StreamError, SupportedStreamConfig, SupportedStreamConfigsError,
 };
 
 pub use self::device::{Device, Devices, SupportedInputConfigs, SupportedOutputConfigs};
@@ -62,6 +62,10 @@ impl DeviceTrait for Device {
         Device::name(self)
     }
 
+    fn id(&self) -> Result<DeviceId, DeviceIdError> {
+        Device::id(self)
+    }
+
     fn supported_input_configs(
         &self,
     ) -> Result<Self::SupportedInputConfigs, SupportedStreamConfigsError> {

src/host/coreaudio/ios/mod.rs

@@ -32,10 +32,11 @@ use super::{asbd_from_config, frames_to_duration, host_time_to_stream_instant};
 use crate::traits::{DeviceTrait, HostTrait, StreamTrait};
 
 use crate::{
-    BackendSpecificError, BufferSize, BuildStreamError, Data, DefaultStreamConfigError,
-    DeviceNameError, DevicesError, InputCallbackInfo, OutputCallbackInfo, PauseStreamError,
-    PlayStreamError, SampleFormat, SampleRate, StreamConfig, StreamError, SupportedBufferSize,
-    SupportedStreamConfig, SupportedStreamConfigRange, SupportedStreamConfigsError,
+    BackendSpecificError, BufferSize, BuildStreamError, Data, DefaultStreamConfigError, DeviceId,
+    DeviceIdError, DeviceNameError, DevicesError, InputCallbackInfo, OutputCallbackInfo,
+    PauseStreamError, PlayStreamError, SampleFormat, SampleRate, StreamConfig, StreamError,
+    SupportedBufferSize, SupportedStreamConfig, SupportedStreamConfigRange,
+    SupportedStreamConfigsError,
 };
 
 use self::enumerate::{
@@ -88,6 +89,10 @@ impl Device {
         Ok("Default Device".to_owned())
     }
 
+    fn id(&self) -> Result<DeviceId, DeviceIdError> {
+        Ok(DeviceId::IOS("default".to_string()))
+    }
+
     #[inline]
     fn supported_input_configs(
         &self,
@@ -154,6 +159,11 @@ impl DeviceTrait for Device {
         Device::name(self)
     }
 
+    #[inline]
+    fn id(&self) -> Result<DeviceId, DeviceIdError> {
+        Device::id(self)
+    }
+
     #[inline]
     fn supported_input_configs(
         &self,

src/host/coreaudio/macos/device.rs

@@ -6,16 +6,18 @@ use crate::host::coreaudio::macos::StreamInner;
 use crate::traits::DeviceTrait;
 use crate::{
     BackendSpecificError, BufferSize, BuildStreamError, ChannelCount, Data,
-    DefaultStreamConfigError, DeviceNameError, InputCallbackInfo, OutputCallbackInfo, SampleFormat,
-    SampleRate, StreamConfig, StreamError, SupportedBufferSize, SupportedStreamConfig,
-    SupportedStreamConfigRange, SupportedStreamConfigsError,
+    DefaultStreamConfigError, DeviceId, DeviceIdError, DeviceNameError, InputCallbackInfo,
+    OutputCallbackInfo, SampleFormat, SampleRate, StreamConfig, StreamError, SupportedBufferSize,
+    SupportedStreamConfig, SupportedStreamConfigRange, SupportedStreamConfigsError,
 };
 use coreaudio::audio_unit::render_callback::{self, data};
 use coreaudio::audio_unit::{AudioUnit, Element, Scope};
 use objc2_audio_toolbox::{
     kAudioOutputUnitProperty_CurrentDevice, kAudioOutputUnitProperty_EnableIO,
     kAudioUnitProperty_StreamFormat,
 };
+use objc2_core_audio::kAudioDevicePropertyDeviceUID;
+use objc2_core_audio::kAudioObjectPropertyElementMain;
 use objc2_core_audio::{
     kAudioDevicePropertyAvailableNominalSampleRates, kAudioDevicePropertyBufferFrameSize,
     kAudioDevicePropertyBufferFrameSizeRange, kAudioDevicePropertyDeviceIsAlive,
@@ -29,6 +31,8 @@ use objc2_core_audio::{
 use objc2_core_audio_types::{
     AudioBuffer, AudioBufferList, AudioStreamBasicDescription, AudioValueRange,
 };
+use objc2_core_foundation::CFString;
+use objc2_core_foundation::Type;
 
 pub use super::enumerate::{
     default_input_device, default_output_device, SupportedInputConfigs, SupportedOutputConfigs,
@@ -44,6 +48,7 @@ use std::time::{Duration, Instant};
 
 use super::property_listener::AudioObjectPropertyListener;
 use coreaudio::audio_unit::macos_helpers::get_device_name;
+
 /// Attempt to set the device sample rate to the provided rate.
 /// Return an error if the requested sample rate is not supported by the device.
 fn set_sample_rate(
@@ -301,6 +306,10 @@ impl DeviceTrait for Device {
         Device::name(self)
     }
 
+    fn id(&self) -> Result<DeviceId, DeviceIdError> {
+        Device::id(self)
+    }
+
     fn supported_input_configs(
         &self,
     ) -> Result<Self::SupportedInputConfigs, SupportedStreamConfigsError> {
@@ -395,6 +404,44 @@ impl Device {
         })
     }
 
+    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: *mut CFString = std::ptr::null_mut();
+        let data_size = size_of::<*mut 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)?;
+
+        // SAFETY: We verified uid is non-null and the status was successful
+        if !uid.is_null() {
+            let uid_string = unsafe { CFString::wrap_under_get_rule(uid).to_string() };
+            Ok(DeviceId::CoreAudio(uid_string))
+        } else {
+            Err(DeviceIdError::BackendSpecific {
+                err: BackendSpecificError {
+                    description: "Device UID is null".to_string(),
+                },
+            })
+        }
+    }
+
     // Logic re-used between `supported_input_configs` and `supported_output_configs`.
     #[allow(clippy::cast_ptr_alignment)]
     fn supported_configs(

src/host/coreaudio/mod.rs

@@ -20,10 +20,7 @@ pub use self::ios::{
 };
 
 #[cfg(target_os = "macos")]
-pub use self::macos::{
-    enumerate::{Devices, SupportedInputConfigs, SupportedOutputConfigs},
-    Device, Host, Stream,
-};
+pub use self::macos::Host;
 
 // Common helper methods used by both macOS and iOS
 

src/host/emscripten/mod.rs

@@ -7,10 +7,10 @@ use web_sys::AudioContext;
 
 use crate::traits::{DeviceTrait, HostTrait, StreamTrait};
 use crate::{
-    BufferSize, BuildStreamError, Data, DefaultStreamConfigError, DeviceNameError, DevicesError,
-    InputCallbackInfo, OutputCallbackInfo, PauseStreamError, PlayStreamError, SampleFormat,
-    SampleRate, StreamConfig, StreamError, SupportedBufferSize, SupportedStreamConfig,
-    SupportedStreamConfigRange, SupportedStreamConfigsError,
+    BufferSize, BuildStreamError, Data, DefaultStreamConfigError, DeviceId, DeviceIdError,
+    DeviceNameError, DevicesError, InputCallbackInfo, OutputCallbackInfo, PauseStreamError,
+    PlayStreamError, SampleFormat, SampleRate, StreamConfig, StreamError, SupportedBufferSize,
+    SupportedStreamConfig, SupportedStreamConfigRange, SupportedStreamConfigsError,
 };
 
 // The emscripten backend currently works by instantiating an `AudioContext` object per `Stream`.
@@ -69,6 +69,11 @@ impl Device {
         Ok("Default Device".to_owned())
     }
 
+    #[inline]
+    fn id(&self) -> Result<DeviceId, DeviceIdError> {
+        Ok(DeviceId::Emscripten("default".to_string()))
+    }
+
     #[inline]
     fn supported_input_configs(
         &self,
@@ -144,6 +149,10 @@ impl DeviceTrait for Device {
         Device::name(self)
     }
 
+    fn id(&self) -> Result<DeviceId, DeviceIdError> {
+        Device::id(self)
+    }
+
     fn supported_input_configs(
         &self,
     ) -> Result<Self::SupportedInputConfigs, SupportedStreamConfigsError> {

src/host/jack/device.rs

@@ -1,9 +1,9 @@
 use crate::traits::DeviceTrait;
 use crate::{
-    BackendSpecificError, BuildStreamError, Data, DefaultStreamConfigError, DeviceNameError,
-    InputCallbackInfo, OutputCallbackInfo, SampleFormat, SampleRate, StreamConfig, StreamError,
-    SupportedBufferSize, SupportedStreamConfig, SupportedStreamConfigRange,
-    SupportedStreamConfigsError,
+    BackendSpecificError, BuildStreamError, Data, DefaultStreamConfigError, DeviceId,
+    DeviceIdError, DeviceNameError, InputCallbackInfo, OutputCallbackInfo, SampleFormat,
+    SampleRate, StreamConfig, StreamError, SupportedBufferSize, SupportedStreamConfig,
+    SupportedStreamConfigRange, SupportedStreamConfigsError,
 };
 use std::hash::{Hash, Hasher};
 use std::time::Duration;
@@ -64,6 +64,10 @@ impl Device {
         }
     }
 
+    fn id(&self) -> Result<DeviceId, DeviceIdError> {
+        Ok(DeviceId::Jack(self.name.clone()))
+    }
+
     pub fn default_output_device(
         name: &str,
         connect_ports_automatically: bool,
@@ -146,6 +150,10 @@ impl DeviceTrait for Device {
         Ok(self.name.clone())
     }
 
+    fn id(&self) -> Result<DeviceId, DeviceIdError> {
+        Device::id(self)
+    }
+
     fn supported_input_configs(
         &self,
     ) -> Result<Self::SupportedInputConfigs, SupportedStreamConfigsError> {

src/host/null/mod.rs

@@ -2,9 +2,9 @@ use std::time::Duration;
 
 use crate::traits::{DeviceTrait, HostTrait, StreamTrait};
 use crate::{
-    BuildStreamError, Data, DefaultStreamConfigError, DeviceNameError, DevicesError,
-    InputCallbackInfo, OutputCallbackInfo, PauseStreamError, PlayStreamError, SampleFormat,
-    StreamConfig, StreamError, SupportedStreamConfig, SupportedStreamConfigRange,
+    BuildStreamError, Data, DefaultStreamConfigError, DeviceId, DeviceIdError, DeviceNameError,
+    DevicesError, InputCallbackInfo, OutputCallbackInfo, PauseStreamError, PlayStreamError,
+    SampleFormat, StreamConfig, StreamError, SupportedStreamConfig, SupportedStreamConfigRange,
     SupportedStreamConfigsError,
 };
 
@@ -47,6 +47,11 @@ impl DeviceTrait for Device {
         Ok("null".to_owned())
     }
 
+    #[inline]
+    fn id(&self) -> Result<DeviceId, DeviceIdError> {
+        Ok(DeviceId::Null)
+    }
+
     #[inline]
     fn supported_input_configs(
         &self,