#+TITLE: Design: music-config Without EMMS #+AUTHOR: Craig Jennings #+DATE: 2026-05-15 * Status Specification only. No implementation has been started. Effort: Large. This is a multi-week module rewrite involving process management, player state, playlist state, a playlist major mode, and updates across the existing music test suite. * Problem =modules/music-config.el= is currently an EMMS configuration module, not an independent music module. The useful workflows are local to this config, but the core state lives in EMMS: the playlist buffer is the source of truth, player state is reported through EMMS hooks, and track metadata is read through EMMS track objects. That shape makes the module harder to test and evolve than it needs to be. Simple playlist operations have to load or stub EMMS, and UI refresh, consume-on-finish, random history, and auto-advance are all coupled to EMMS player hooks. The target design is a standalone music module that owns playlist state, controls =mpv= directly through a small backend protocol, and renders a playlist buffer as a view over package-owned data. This remains a personal config module in =modules/music-config.el=. It should be internally coherent enough that it could later become a package, but v1 does not target MELPA or a public package boundary. * Goals - Keep the current user workflows: fuzzy add, recursive directory add, Dired/Dirvish add, M3U load/save/edit/reload, append-track-to-M3U, radio station creation, playlist window toggle, random/repeat/single/consume controls, track reordering, and mpv playback. - Make EMMS unnecessary for =music-config.el= load, tests, and normal use. - Separate domain logic from playback and UI so helpers stay easy to test. - Replace EMMS-bound keymap entries with =cj/music-*= commands. - Keep playlist files portable M3U files. * Non-Goals - Reimplementing the full EMMS feature set. - Building a music library database, tag editor, or metadata indexer. - Supporting multiple player daemons in v1. - Supporting album art, lyrics, queue persistence across Emacs restarts, or remote control protocols beyond mpv. - Publishing a standalone =cj-music= package, adding MELPA metadata, or converting all personal configuration variables to public =defcustom= forms. * Existing EMMS Coupling The current module depends on EMMS in these areas: - Playback commands: =emms-pause=, =emms-stop=, =emms-next=, =emms-previous=, =emms-start=, =emms-random=, =emms-seek-forward=, =emms-seek-backward=, =emms-volume-raise=, =emms-volume-lower=, and shuffle/repeat/random toggles. - Add/load/save commands: =emms-add-file=, =emms-add-directory-tree=, =emms-play-playlist=, =emms-playlist-save=, =emms-source-playlist-ask-before-overwrite=, and =emms-playlist-clear=. - Playlist buffer operations: =emms-playlist-buffer=, =emms-playlist-mode=, =emms-playlist-track-at=, =emms-playlist-current-selected-track=, =emms-playlist-select=, =emms-playlist-mode-go=, =emms-playlist-mode-bury-buffer=, =emms-playlist-mode-center-current=, =emms-playlist-mode-shift-track-up=, =emms-playlist-mode-shift-track-down=, =emms-playlist-mode-kill-track=, and =emms-playlist-selected-marker=. - Track representation: =emms-track-name=, =emms-track-type=, =emms-track-get=, =emms-track-simple-description=, and =emms-track-description-function=. - Lifecycle hooks and state: =emms-player-started-hook=, =emms-player-stopped-hook=, =emms-player-paused-hook=, =emms-player-finished-hook=, =emms-playlist-cleared-hook=, =emms-player-playing-p=, =emms-player-paused-p=, =emms-random-playlist=, =emms-repeat-playlist=, and =emms-repeat-track=. - EMMS setup: =emms-all=, =emms-mode-line-mode=, =emms-playing-time-disable-display=, =emms-source-file-default-directory=, =emms-playlist-default-major-mode=, =emms-player-list=, =emms-player-mpv-parameters=, =emms-player-mpv-regexp=, and EMMS playlist faces. Anything outside those areas, especially file discovery, safe filename generation, M3U parsing, and radio station file creation, can remain mostly unchanged. * Proposed Architecture ** Data Model Introduce a package-owned track model: #+begin_src emacs-lisp (cl-defstruct cj/music-track type ; 'file or 'url name ; absolute file path or stream URL title artist duration) #+end_src The =title=, =artist=, and =duration= slots are populated opportunistically from mpv IPC metadata after a track starts. V1 must still behave correctly when metadata is absent by displaying a filename or decoded URL. Introduce playlist state that belongs to this package: #+begin_src emacs-lisp (cl-defstruct cj/music-playlist tracks selected-index file repeat-playlist repeat-track random consume random-history) #+end_src The playlist buffer should render this state. It should not be the source of truth. Buffer text becomes a view over =cj/music-current-playlist=. Track construction should use a small type helper instead of EMMS's mpv regex: #+begin_src emacs-lisp (defun cj/music--track-type-from-name (name) (cond ((string-match-p "\\`\\(?:https?\\|mms\\)://" name) 'url) ((cj/music--valid-file-p name) 'file) (t nil))) #+end_src ** Read-Side State API UI code should read player and playlist state through package-owned helpers, not through backend internals: - =cj/music-playing-p= - =cj/music-paused-p= - =cj/music-current-track= - =cj/music-playlist-state= - =cj/music-track-description= The playlist header, modeline indicators, and tests should use these helpers. ** Backend Protocol Playback should go through a narrow backend plist: #+begin_src emacs-lisp (:name 'mpv :available-p cj/music-mpv-available-p :play cj/music-mpv-play :pause cj/music-mpv-pause :resume cj/music-mpv-resume :stop cj/music-mpv-stop :seek cj/music-mpv-seek :volume cj/music-mpv-volume :status cj/music-mpv-status :metadata cj/music-mpv-metadata) #+end_src The module should provide commands such as =cj/music-play=, =cj/music-pause=, =cj/music-stop=, =cj/music-next=, =cj/music-previous=, =cj/music-seek-forward=, =cj/music-seek-backward=, =cj/music-volume-raise=, and =cj/music-volume-lower=. Those commands operate on package playlist state and then call the selected backend. ** State-Change Hooks Replace EMMS player hooks with one package-owned abnormal hook: #+begin_src emacs-lisp (defvar cj/music-state-change-functions nil "Abnormal hook run when music player state changes. Each function receives a plist: (:event EVENT :track TRACK :error ERROR).") #+end_src Events for v1: - =started= - =paused= - =resumed= - =stopped= - =finished= - =error= - =playlist-changed= - =mode-changed= The mpv backend is responsible for dispatching player events from process sentinels and IPC event messages. Package features should subscribe here: - Header refresh runs on every event. - Random history records on =started= when random mode is active. - Consume mode removes the finished track on =finished=. - Auto-advance runs on =finished= unless playback was deliberately stopped. - Playlist-file reset runs on =playlist-changed= when the playlist is cleared. ** mpv Backend V1 should use mpv JSON IPC from the start. Pause, seek, and volume are core workflow parity, and implementing them later would leave a worse player than the current EMMS+mpv setup. Spawn mpv with: #+begin_src sh mpv --no-video --quiet --audio-display=no \ --input-ipc-server= TRACK #+end_src The socket path lives under =temporary-file-directory= (=/tmp/= on Linux/macOS, =%TEMP%= on Windows) and includes the effective UID and Emacs process id, e.g. =cj-music-mpv-1000-12345.sock=. On startup, remove stale =cj-music-mpv-*= sockets for the current UID when no matching process owns them. On Emacs exit, stop playback and remove the active socket. Minimum mpv version: 0.17 (when JSON IPC stabilized). All current Linux/macOS/Windows distributions ship something newer. Backend responsibilities: - Start mpv for the selected track and connect to the IPC socket with =make-network-process=. - Send JSON commands for pause/resume, seek, and volume. - Subscribe to mpv events such as =playback-restart=, =pause=, and =end-file=. - Query metadata on track start with =get_property metadata= and update the selected track's metadata slots. - Distinguish deliberate stops from natural track completion so the sentinel does not auto-advance after an explicit stop. - Report process and IPC errors through =cj/music-state-change-functions= with =:event error=. ** Platform Support Linux and macOS are the primary v1 targets. Both expose mpv's JSON IPC over a Unix domain socket, which Emacs reads with =make-network-process :family 'local=. All features (play/stop/next/previous, pause/resume, seek, volume, metadata) work identically on those platforms. Windows is best-effort. mpv on Windows uses named pipes (=\\.\pipe\=) for IPC instead of Unix sockets, and Emacs's =make-network-process= does not natively connect to Windows named pipes. Rather than block v1 on a Windows IPC layer, v1 ships a degraded mode on Windows: - Spawn mpv with =start-process= and feed commands over stdin or via per-command =call-process= invocations. - Available commands: play, stop, next, previous. - Not available on Windows in v1: pause/resume, seek, volume. - =M-x cj/music-doctor= reports the degraded state on Windows so the user is not surprised by missing functionality. Craig's call, 2026-05-15: best-effort on Windows is acceptable for v1. Anyone who needs full Windows parity can fund a follow-up that wires named pipes via =mpvc.exe= shellout or a =w32-*= named-pipe client. This call unblocks the implementer to focus on the Linux/macOS path without spending v1 budget on Windows IPC plumbing. ** Selected-Track Representation Use =selected-index= as the durable state value. The playlist buffer should display the selected/current track with an overlay plus a selected-track face. Reordering should: 1. Swap entries in the playlist state's =tracks= vector/list. 2. Update =selected-index= so it continues to point at the same logical track. 3. Re-render the playlist buffer. 4. Reposition the selected overlay. Consume mode should remove the finished track from playlist state, then re-render. It should not edit raw buffer text as the source of truth. ** Playlist Buffer Define a package-owned major mode, for example =cj/music-playlist-mode=. The buffer should preserve the current key surface: - =RET= or =p= to play the selected track. - =SPC= to pause/resume. - =s= to stop. - =>= / =n= and =<= / =P= for next/previous. - =f= / =b= for seek forward/backward. - =+= / === / =-= for volume. - =a= to add music. - =A= to append the track at point to an M3U. - =c= / =C= to clear. - =L=, =S=, =E=, and =g= for playlist load/save/edit/reload. - =r=, =t=, =z=, and =x= for repeat playlist, repeat track, random, and consume. - =Z= to shuffle. - =i= for track info. - =o= to jump to the playing track. - =q= to bury the playlist buffer. - =S-= / =S-= and =C-= / =C-= for reordering. The current overlay/header design can stay, but it should read from the package state APIs instead of EMMS variables. The active-window background highlight should be preserved, because it is part of the current playlist window affordance. ** Playlist State Rules - Shuffle changes playlist order and clears random history. - Reload replaces playlist tracks from disk and clears random history. - Save writes only track names/URLs to M3U; random history and mode state are not persisted. - Repeat playlist, repeat track, random, and consume are package-owned runtime flags. - Clearing a playlist clears the associated M3U file path. ** M3U Handling Keep M3U as the persistence format. Existing helpers should be reused or moved behind pure APIs: - =cj/music--m3u-file-tracks= should parse paths and URLs. - Saving should write one track per line, using relative paths where possible. - Radio station creation should keep writing =#EXTM3U= and =#EXTINF= entries. ** Test Architecture The rewrite should not update every command-flow test with one-off mocks. Introduce a shared fake backend first: #+begin_src emacs-lisp ;; tests/testutil-music-backend.el (defvar cj/test-music-fake-backend '(:name fake :available-p cj/test-music--fake-available-p :play cj/test-music--fake-play :pause cj/test-music--fake-pause :resume cj/test-music--fake-resume :stop cj/test-music--fake-stop :seek cj/test-music--fake-seek :volume cj/test-music--fake-volume :status cj/test-music--fake-status :metadata cj/test-music--fake-metadata)) #+end_src The fake backend should keep a simple event ledger, for example =(:playing-p BOOL :paused-p BOOL :track TRACK :events LIST)=. Command tests bind =cj/music-current-backend= to this fake and assert ordered backend events instead of stubbing individual EMMS functions. Before rewriting non-pure command implementations, add or preserve characterization tests for: - =cj/music-next= - =cj/music-previous= - =cj/music-toggle-consume= - =cj/music-playlist-toggle= - =cj/music-playlist-load= - =cj/music-playlist-clear= The existing pure-helper tests should mostly survive unchanged. The command tests, random-navigation tests, consume tests, playlist-buffer tests, and header tests should migrate to package state plus the fake backend. The real mpv IPC client should have integration tests tagged =:slow= and skipped when =mpv= is not on =PATH=. Default =make test= should not depend on mpv being installed. ** Performance Budget V1 should keep the UI responsive for realistic playlist sizes: - =cj/music-playlist-load= on a 1000-track M3U should complete in under 500 ms, excluding disk cold-cache effects. - =S-= and =S-= should return control within 50 ms for playlists up to 5000 tracks. - Pause/resume command dispatch over mpv IPC should complete in under 100 ms, excluding audio-device resume latency. - Header refresh after metadata arrival should stay below a frame budget target of 16 ms. Full playlist re-rendering is acceptable for load, clear, shuffle, reload, and consume-after-finish. Reordering should avoid an obvious O(n) full erase and insert on every keypress if it misses the 50 ms budget. Start simple, measure, then add incremental line swaps or rendered-line caching only if needed. Metadata extraction must be lazy. Query mpv metadata when a track starts and refresh the header when it arrives. Do not eagerly scan all tracks on playlist load. ** Parity Walk Before removing the EMMS implementation, run a manual parity walk against the new implementation: 1. =F10= opens the playlist in a bottom side window; =F10= again closes it. 2. =C-; m a= completes files and dirs under =cj/music-root=; choosing a file adds that track. 3. Choosing a directory adds music files from that tree. 4. In Dirvish, marking files and pressing =+= adds them. 5. In the playlist, =RET= plays, =SPC= pauses, and =SPC= resumes. 6. =>= advances and =<= goes back. 7. =z= toggles random; next chooses randomly; previous uses random history. 8. =r= toggles repeat-playlist. 9. =t= toggles repeat-track. 10. =x= toggles consume; finished tracks disappear. 11. =S= saves an M3U in =cj/music-m3u-root=. 12. =L= loads a saved playlist in order. 13. =g= reloads the current M3U after manual edits. 14. =E= opens the M3U for editing. 15. =R= creates a radio-station M3U that can be loaded and played. 16. =S-= and =S-= reorder tracks while state and view stay in sync. 17. =c= and =C= clear the playlist. 18. =q= buries the playlist buffer. 19. =i= shows current track info. 20. =o= centers the playlist on the current track. 21. =+= and =-= adjust volume and the change persists across track changes. 22. =f= and =b= seek forward/backward. * Migration Plan 1. Extract pure helpers and tests into EMMS-free units: file validation, recursive collection, M3U parsing/writing, safe filenames, radio station content, URL/file track typing, and playlist state operations. 2. Introduce package-owned track and playlist state structs. 3. Add =cj/music-playlist-mode= and make it render package playlist state with selected-track overlay support. 4. Add =tests/testutil-music-backend.el= and migrate command-flow tests to the fake backend. 5. Implement the mpv backend in focused steps: - Process spawn, socket path management, IPC connection, and state-change hook plumbing. - Play, stop, next, and previous, including finished-track auto-advance. - Pause/resume, seek, and volume through IPC. - Metadata read on track start through IPC. 6. Rewire public commands and Dired/Dirvish integration to use the new state/backend APIs. 7. Replace EMMS functions in =cj/music-map= and the playlist-mode keymap with =cj/music-*= commands. 8. Remove =cj/emms--setup= and the on-demand EMMS loading pattern. 9. Delete the =use-package emms= block once parity is covered. No EMMS compatibility adapter is planned. This is a personal config, and the cleaner migration is to keep existing public =cj/music-*= command names while swapping their implementation behind the scenes. * Acceptance Criteria - Loading =music-config.el= does not require EMMS or reference EMMS symbols. - =init.el= still loads after the =use-package emms= block is removed. - A new smoke test confirms =music-config.el= can be required in batch with no EMMS package installed. - Existing focused music tests pass without EMMS preload or EMMS stubs. - =tests/testutil-music-backend.el= exists and command-flow tests use it instead of direct EMMS stubs. - New tests cover playlist state, backend command dispatch, IPC command formatting, M3U persistence, Dired/Dirvish add routing, and the EMMS-free load smoke path. - Slow mpv IPC integration tests are tagged =:slow= and skipped when =mpv= is unavailable. - The F10 and =C-; m= workflows still open/show the playlist and expose the same high-level commands. - All keys from the current playlist-mode keymap work in =cj/music-playlist-mode=. - M3U load/save/reload/edit and radio station creation work without EMMS. - Local-file and stream URL playback work through mpv. - Pause/resume, seek, and volume work through mpv IPC. - Random, repeat playlist, repeat track, consume, shuffle, and track reordering are represented in package-owned state and covered by focused tests. - The parity walk passes. - The performance budget is met or deviations are documented with measurements. * Risks | Risk | Mitigation | |-----------------------------------------------+-------------------------------------------------------------------------------------------------------------| | mpv IPC socket races or stale sockets | Use UID/PID-stamped socket paths, clean stale sockets on startup, and remove the active socket on exit. | | Auto-advance fires after explicit stop | Track deliberate stop state and test sentinel/event ordering. | | Metadata availability differs by stream/file | Treat metadata as optional; filename/URL descriptions remain the fallback. | | Playlist buffer gets out of sync with state | Make state the only source of truth and render buffer text from state after every playlist mutation. | | Dirvish =+= workflow regresses | Include Dired/Dirvish add routing in migration and tests. | | Test rewrite spreads bespoke fakes everywhere | Add one shared fake backend and migrate command tests through it. | | Playlist rendering is too slow on large M3Us | Start simple, measure against the budget, and add incremental rendering only if needed. | | Rewrite is too broad for one commit | Split implementation by the migration plan; keep pure helpers and state changes separate from backend work. | * Considered But Not Chosen ** Publish as a standalone MELPA package in v1 Rejected for v1. A public package would require namespace cleanup, =Package-Requires=, autoload cookies, defgroups/defcustoms, license headers, README/CHANGELOG work, package-lint/checkdoc cleanup, CI matrix support, and removal of personal config dependencies like =user-constants= and =cj/custom-keymap=. That work is real and useful only after the personal module migration proves the design. The v1 scope stays in =modules/music-config.el=. ** Rewrite every test individually Rejected. Roughly half of the current music tests exercise EMMS-backed command flows. Replacing each EMMS mock one at a time would duplicate setup and make backend semantics inconsistent across tests. A shared fake backend gives the rewrite one seam to test command dispatch, state changes, and event ordering. ** Eager metadata extraction for every playlist track Rejected. Scanning metadata for every track on load would require either many short mpv invocations or another tag-reading dependency, and it scales poorly for large M3Us. V1 reads metadata lazily from mpv IPC only when a track starts. ** Full incremental playlist renderer from the start Deferred. Incremental rendering is more complex and may not be needed for the actual playlist sizes in this config. The spec sets a budget instead: full rendering is fine where it meets the budget, and reorder operations should only gain incremental swaps or cached rendered lines if measurement shows a problem. ** Depend on an external mpv IPC package immediately Undecided, not chosen as a requirement. A local JSON IPC helper may be small enough and easier to test in this config. Depending on an existing package is still open if the local helper starts to recreate too much protocol machinery. ** Add =webm= and =ape= to =cj/music-file-extensions= Rejected. =~/music= contains a small number of =webm= and =ape= files (~22 each), and mpv can play both, but Craig's call (2026-05-15) is to leave the extension list as-is. Those files stay silently filtered out of fuzzy completion and recursive directory adds. Easy to revisit later by adding the two strings to the list; no architectural impact. * Open Decisions - Exact mpv IPC client implementation: small local JSON helper or dependency on an existing mpv IPC package. - Whether metadata should be cached only in memory or written into extended M3U comments later.