style: standardize error messages across backends

[roderickvd]

Claude assisted in standardizing error messages across backends based on the following rules:

R1: Start with a capital letter, no trailing period.

R2: No backend name. The caller knows which backend they are on, and can choose to include it if it wishes. Exception: Include the name when the backend itself is the subject. Examples: "ASIO driver is not initialized", "JACK server shut down: {reason}", "PulseAudio disconnected", "PipeWire is not available".

R3: No device name. The caller knows the device both at build-time and at runtime, and can choose to include it if it wishes.

R4: Use the same phrasing across all backends for the same class of failure.

R5: No Debug format in user-facing messages. Use Display or use a static description.

R6: No implementation details. Describe what failed from the caller's perspective, not internal mechanisms.

R7: No hedging or implementation notes like "currently". State what is true, not what might change.

R8: No custom message where it adds no value over ErrorKind's Display implementation

[Copilot]

Pull request overview

This PR standardizes user-facing error message phrasing across CPAL host backends, mainly aligning capitalization, removing backend/device names where possible, and replacing debug-formatted errors with static or display-oriented messages.

Changes:

• Normalizes capitalization and wording for unsupported configs, unavailable hosts/devices, stream invalidation, and thread/resource failures.
• Replaces several backend-specific or debug-formatted messages with generic user-facing descriptions.
• Removes some redundant stored device identifiers used only in ALSA error messages.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/host/webaudio/mod.rs	Standardizes WebAudio configuration, stream, and context error messages.
src/host/wasapi/stream.rs	Updates WASAPI stream/thread/event error message capitalization and wording.
src/host/wasapi/device.rs	Updates WASAPI device/config/client setup error messages.
src/host/pulseaudio/stream.rs	Simplifies PulseAudio sample-format error messages.
src/host/pulseaudio/mod.rs	Standardizes PulseAudio availability, device listing, and config messages.
src/host/pipewire/stream.rs	Updates PipeWire stream/device-change and negotiated-format mismatch messages.
src/host/pipewire/mod.rs	Simplifies PipeWire host availability message.
src/host/pipewire/device.rs	Updates PipeWire device support and thread creation messages.
src/host/jack/stream.rs	Updates JACK port/client/system-port/xrun messages.
src/host/jack/mod.rs	Capitalizes JACK client/server status messages.
src/host/jack/device.rs	Standardizes JACK device/config validation messages.
src/host/coreaudio/mod.rs	Updates timestamp overflow message.
src/host/coreaudio/macos/mod.rs	Updates macOS CoreAudio stream/disconnect messages.
src/host/coreaudio/macos/loopback.rs	Replaces a null UID custom message with the generic error kind.
src/host/coreaudio/macos/device.rs	Updates macOS CoreAudio device/config format messages.
src/host/coreaudio/ios/session_event_manager.rs	Capitalizes iOS audio route/media-service messages.
src/host/coreaudio/ios/mod.rs	Updates iOS CoreAudio config, lock, unit, and buffer-duration messages.
src/host/audioworklet/mod.rs	Standardizes AudioWorklet availability/config/context/stream messages.
src/host/asio/stream.rs	Updates ASIO lock, driver, format, channel, and stream event messages.
src/host/asio/device.rs	Updates ASIO channel/sample-format support messages.
src/host/alsa/mod.rs	Standardizes ALSA availability/config/device/stream messages and removes stream PCM ID storage.
src/host/aaudio/mod.rs	Updates AAudio config, stream, pause, and lock messages.

Comments suppressed due to low confidence (5)

src/host/webaudio/mod.rs:449

• This if let Err(_) pattern triggers Clippy's redundant pattern matching lint; CI runs cargo clippy ... -- -D warnings, so this will fail the lint job. Use an is_err() check (or bind and use the error) when the error value is intentionally discarded.

                            if let Err(_) = ctx_buffer
                                .unchecked_ref::<ExternalArrayAudioBuffer>()
                                .copy_to_channel(&temporary_channel_array_view, channel as i32)
                            {

src/host/webaudio/mod.rs:481

• This if let Err(_) pattern triggers Clippy's redundant pattern matching lint; CI runs cargo clippy ... -- -D warnings, so this will fail the lint job. Use an is_err() check (or bind and use the error) when the error value is intentionally discarded.

                    if let Err(_) = source.connect_with_audio_node(&ctx_handle.destination()) {

src/host/webaudio/mod.rs:496

• This if let Err(_) pattern triggers Clippy's redundant pattern matching lint; CI runs cargo clippy ... -- -D warnings, so this will fail the lint job. Use an is_err() check (or bind and use the error) when the error value is intentionally discarded.

                    if let Err(_) = source.add_event_listener_with_callback(
                        "ended",
                        on_ended_closure_handle
                            .read()
                            .unwrap()

src/host/webaudio/mod.rs:513

• This if let Err(_) pattern triggers Clippy's redundant pattern matching lint; CI runs cargo clippy ... -- -D warnings, so this will fail the lint job. Use an is_err() check (or bind and use the error) when the error value is intentionally discarded.

                    if let Err(_) = source.start_with_when(time_at_start_of_buffer) {

src/host/pipewire/stream.rs:834

• The mismatch condition still includes sample-format differences, but the new message omits both the expected and negotiated formats. If only the format differs, users will see a contradictory message saying the expected and actual channel/rate values are identical, with no indication of the real mismatch.

                                format!("Negotiated format mismatch: expected {channels} channels at {rate} Hz, got {current_channels} channels at {current_rate} Hz"),

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.