Skip to content

audio: Added SDL_GetAudioDeviceProperties() and a unique-id property for it. - #16341

Merged
icculus merged 2 commits into
libsdl-org:mainfrom
icculus:sdl3-audio-guids
Sep 21, 2026
Merged

icculus merged 2 commits into
libsdl-org:mainfrom
icculus:sdl3-audio-guids

Conversation

@icculus

@icculus icculus commented Sep 17, 2026 •

Copy link
Copy Markdown
Collaborator
  • I confirm that I am the author of this code and release it to the SDL project under the zlib license. This contribution does not contain code from other sources, including code generated by a Large Language Model ("AI").

(EDIT: this was the original text, but this now offers audio device properties instead of an API for specifically this one thing.)

This allows a best-effort option to find the same specific audio device used on a previous run of a program, even in an imperfect way. Most backends don't support this, but CoreAudio on macOS and IMMDevice on Windows can.

coreaudio: Rework device enumeration queries, acquire unique_id.

  • No longer keeps multiple AudioObjectPropertyAddress objects, just change the selector for each query.
  • Move string retrieval off to a separate function.
  • Query for unique_id.
  • If a device name is blank, don't reject the device, try to come up with a name of some sort (either the unique_id or "Unnamed audio device").

windows: Add unique audio device identifiers to IMMDevice support.

This uses the new "StableId" property on Windows 11 if available, and the device id (IMMDevice::GetId()) otherwise.

Microsoft claims that GetId() remains valid between reboots and even disconnecting and reconnecting the audio device (although I am dubious that is universally true when plugging into a different USB port, etc), but driver and OS updates might change the identifier. StableId goes further, promising that software updates won't change it, either.

This adds support to our WASAPI and DirectSound backends, if you're on at least Windows Vista. Windows XP will not offer a unique ID for devices.

Fixes #16258.

@icculus icculus added this to the 3.6.0 milestone Sep 17, 2026
@icculus icculus self-assigned this Sep 17, 2026
@icculus

icculus commented Sep 17, 2026

Copy link
Copy Markdown
Collaborator Author

Debated doing this as an optional property, but we'd still have to add an API for that, since we don't have an SDL_GetAudioDeviceProperties() function at the moment (and do logical and physical devices have separate properties? etc).

But I'm not against making that change, or even just renaming the new wordy function.

@slouken

slouken commented Sep 18, 2026

Copy link
Copy Markdown
Collaborator

This does seem like a perfect opportunity for properties

@icculus

icculus commented Sep 18, 2026

Copy link
Copy Markdown
Collaborator Author

Okay, pivoting!

The specific changes are in 881f46d, but I'm squashing this down to remove the original API now.

…for it.

In addition to adding properties to audio devices, the new property,
`SDL_PROP_AUDIO_DEVICE_UNIQUE_ID_STRING`, allows a best-effort option to find
the same specific audio device used on a previous run of a program, even in an
imperfect way. Most backends don't support this, but CoreAudio on macOS and
IMMDevice on Windows can.

coreaudio: Rework device enumeration queries, acquire unique_id.

- No longer keeps multiple AudioObjectPropertyAddress objects, just change the
  selector for each query.
- Move string retrieval for AudioObjectProperties off to a separate function.
- Query for unique_id.
- If a device name is blank, don't reject the device, try to come up with a
  name of some sort (either the unique_id or "Unnamed audio device").

windows: Add unique audio device identifiers to IMMDevice support.

This uses the new "StableId" property on Windows 11 if available, and the
device id (IMMDevice::GetId()) otherwise.

Microsoft claims that GetId() remains valid between reboots and even
disconnecting and reconnecting the audio device (although I am dubious that is
universally true when plugging into a different USB port, etc), but driver and
OS updates might change the identifier. StableId goes further, promising that
software updates won't change it, either.

This adds support to our WASAPI and DirectSound backends, if you're on at
least Windows Vista. Windows XP will not offer a unique ID for devices.

Fixes libsdl-org#16258.
@icculus icculus changed the title api: Added SDL_GetAudioDeviceUniqueIdentifier(). audio: Added SDL_GetAudioDeviceProperties() and a unique-id property for it. Sep 18, 2026
@icculus
icculus merged commit 0ccb0bf into libsdl-org:main Sep 21, 2026
10 checks passed
@icculus
icculus deleted the sdl3-audio-guids branch September 21, 2026 14:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add unique identifier to audio hardware

2 participants