Does SDL3 reliably fire SDL_AudioDeviceEvent for USB headset connect/disconnect across platforms?

Direct Answer

No. SDL3 does not guarantee perfectly reliable, single-instance audio device events for USB headset hot-plug across all major platforms. SDL_EVENT_AUDIO_DEVICE_ADDED and SDL_EVENT_AUDIO_DEVICE_REMOVED are dispatched when the native backend detects a change, but the exact timing, duplication, and device identity are backend-dependent.

Confirmed Facts vs. Likely Explanation

Confirmed: SDL3 defines these events and exposes SDL_GetAudioDeviceList and SDL_GetAudioDeviceInfo. Each backend—PulseAudio, PipeWire, WASAPI, and CoreAudio—translates native notifications into SDL events differently. Device IDs returned by SDL_GetAudioDeviceList are logical identifiers that may change after a hot-plug cycle.

Likely explanation: The symptoms you describe—missing events, duplicates, transient IDs, and premature readiness—are consistent with the underlying audio server pipelines rather than an SDL3 bug alone. PulseAudio may signal before the sink/source is fully registered. PipeWire can coalesce node and link changes, producing duplicate or delayed removals. WASAPI is generally deterministic for endpoint changes, but format or sample-rate renegotiation can generate additional events. CoreAudio may report aggregate devices or system reconfigurations that are indistinguishable from a physical plug without extra validation.

Safe Validation Pattern

1. Debounce: After SDL_EVENT_AUDIO_DEVICE_ADDED, call SDL_Delay(200) before enumerating. This gives the backend time to stabilize.
2. Re-enumerate and match by identity: Call SDL_GetAudioDeviceList, then SDL_GetAudioDeviceInfo. Match on the device name and unique ID string; do not cache indices.
3. Validate physical identity: Compare the unique ID against a previously stored value for the known headset. If the ID is new or changed, treat it as a potential aggregate/virtual device until proven otherwise.
4. Probe readiness: Open a short-lived audio stream on the candidate device. If SDL_OpenAudioDeviceStream returns an error or the stream produces no data, discard it and retry after another delay.
5. Invalidate on removal: When SDL_EVENT_AUDIO_DEVICE_REMOVED arrives, immediately mark the old ID as unusable. Do not assume the same numeric ID will refer to the same hardware after replug.

One Diagnostic Detail Needed

Do you need to distinguish the physical USB headset from OS-level aggregate or virtual devices on macOS, or is any output matching the headset name acceptable? This determines whether step 3 requires additional transport/UID filtering.

Assumptions

This guidance assumes SDL3 3.x with current stable backends; exact event timing may vary by OS version and audio server configuration.