docs: document sound-player selection and the ALSA device failure

CONFIGURATION.org covers how the player is chosen and when chime-sound-device applies.

TROUBLESHOOTING.org names the "No usable sound device driver found" error, how to confirm it outside Emacs with aplay, and the two ways out: name a device that resolves, or repair the system so default routes to PipeWire.

2 files changed, 81 insertions, 4 deletions

diff --git a/docs/CONFIGURATION.org b/docs/CONFIGURATION.org
index 3565c4a..225b840 100644
--- a/docs/CONFIGURATION.org
+++ b/docs/CONFIGURATION.org
@@ -73,7 +73,50 @@ org-wild-notifier's =:WILD_NOTIFIER_NOTIFY_BEFORE:= property is honored as a dep
 (setq chime-sound-file "/path/to/chime.wav")
 #+END_SRC
 
-Chime uses Emacs's built-in =play-sound-file=. WAV and AU are the safest formats.
+WAV and AU are the safest formats.
+
+** How the sound gets played
+
+By default chime hands the file to an external player — the first of
+=pw-play=, =paplay=, =afplay= or =aplay= found on =exec-path=. That player runs
+asynchronously, so a clip never blocks Emacs, and it goes through the
+system's sound server, so it respects the default sink and the
+per-application volume.
+
+When no external player is installed, chime falls back to Emacs's built-in
+=play-sound-file=. That function opens an audio device directly and blocks
+until the clip finishes.
+
+#+BEGIN_SRC elisp
+;; Always use Emacs's built-in player
+(setq chime-sound-player 'emacs)
+
+;; Use a specific command, invoked as "COMMAND SOUND-FILE"
+(setq chime-sound-player "paplay")
+#+END_SRC
+
+An explicit command that isn't installed falls back to =play-sound-file=
+rather than failing.
+
+** Choosing a device for the built-in player
+
+=chime-sound-device= is passed to =play-sound-file= as its DEVICE argument.
+It only matters when the built-in player is in use. nil, the default, lets
+the system choose — on Linux that means ALSA's =default= PCM.
+
+Set it when =default= is unusable but a named device works. Under PipeWire
+that is usually "pipewire" or "pulse":
+
+#+BEGIN_SRC elisp
+(setq chime-sound-player 'emacs)
+(setq chime-sound-device "pipewire")
+#+END_SRC
+
+Test a candidate before committing to it:
+
+#+BEGIN_SRC elisp
+M-: (play-sound-file chime-sound-file nil "pipewire")
+#+END_SRC
 
 * Notification Icon
 
diff --git a/docs/TROUBLESHOOTING.org b/docs/TROUBLESHOOTING.org
index b1fadde..832fa9d 100644
--- a/docs/TROUBLESHOOTING.org
+++ b/docs/TROUBLESHOOTING.org
@@ -66,14 +66,48 @@ Check these in order:
    #+BEGIN_SRC elisp
    M-: (file-exists-p chime-sound-file)
    #+END_SRC
-3. Test sound directly:
+3. See which player chime picked:
    #+BEGIN_SRC elisp
-   M-: (play-sound-file chime-sound-file)
+   M-: (chime--find-sound-player)
    #+END_SRC
-4. Ensure your system has audio support configured.
+   A string is the external player it will spawn. nil means it falls back
+   to Emacs's built-in =play-sound-file=.
+4. Play the file the same way chime does:
+   #+BEGIN_SRC elisp
+   M-: (chime--play-sound)
+   #+END_SRC
+   A process object or t means playback started. nil means it failed, and
+   =*Messages*= carries the reason. An external player that starts and then
+   exits non-zero — an unsupported file, say — also reports to =*Messages*=.
+5. Ensure your system has audio support configured.
 
 Set =chime-sound-file= to nil to disable sound.
 
+** "No usable sound device driver found"
+
+Emacs's =play-sound-file= opens an ALSA device directly. It reports this
+error when ALSA's =default= PCM doesn't resolve, which happens on a
+PipeWire system where nothing points =pcm.!default= at the sound server.
+Confirm it outside Emacs — =aplay <file>= fails the same way — and note
+that =aplay -D pipewire <file>= usually works, which tells you the sound
+server itself is healthy.
+
+Chime avoids the problem by preferring an external player. You only reach
+this error when none of =pw-play=, =paplay=, =afplay= or =aplay= is installed,
+or when =chime-sound-player= is set to ='emacs=. Two fixes:
+
+- Name a device that resolves: =(setq chime-sound-device "pipewire")=.
+- Or repair the system so =default= routes to PipeWire. On Arch, the
+  needed config ships with =pipewire-audio= but is not enabled:
+  #+BEGIN_SRC sh
+  sudo ln -s /usr/share/alsa/alsa.conf.d/99-pipewire-default.conf /etc/alsa/conf.d/
+  #+END_SRC
+  This one repairs every ALSA client on the machine, not just Emacs.
+
+On macOS, Emacs is built without sound support, so =play-sound-file=
+signals rather than playing. Chime uses =afplay=, which ships with the OS,
+so this only bites if =chime-sound-player= is forced to ='emacs=.
+
 * Events Not Being Detected
 
 Common causes: