diff options
Diffstat (limited to 'docs/TROUBLESHOOTING.org')
| -rw-r--r-- | docs/TROUBLESHOOTING.org | 51 |
1 files changed, 48 insertions, 3 deletions
diff --git a/docs/TROUBLESHOOTING.org b/docs/TROUBLESHOOTING.org index b1fadde..fe78aa0 100644 --- a/docs/TROUBLESHOOTING.org +++ b/docs/TROUBLESHOOTING.org @@ -66,14 +66,59 @@ 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. + +*** The system fix doesn't reach a running Emacs + +alsa-lib parses its configuration once per process. A long-running +=emacs --daemon= that started before you added the ALSA config keeps the old +view, so =play-sound-file= still fails there while it succeeds in a fresh +=emacs -Q=. Restart the daemon, or set =chime-sound-device= to a device that +was already defined ("pipewire" or "pulse" both work without the =default= +fix, because =50-pipewire.conf= defines them). + +This is worth knowing before you conclude the system fix didn't work. + +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: |