Hike through your music library. No window, no mouse, no clicking around.
mpd-hykr is not a music player. It is a small script that lets four programs
that already exist act as one, so that none of them has to be the interface:
- Hyprland is the interface. Playback controls, always available, from any workspace.
- MPD is the player. It holds the queue and makes the sound. It has no window.
- wofi is the file manager. It appears, you pick something, it disappears.
- Neovim is the playlist editor. Playlists are text files, so editing them is just editing text.
Hit a key, type three letters, music plays. The picker is gone before the first note. Nothing lives in a workspace.
Background and the reasoning behind it: Winamp, but for my window manager
Old players like Winamp were direct: point them at a folder, they play it. Modern managers are good at managing, but playing an album became a small project - a library tree, a browser, a details pane, a toolbar, and somewhere in there a play button.
The trick is that this is two unrelated jobs. Holding and playing the music is one. Being the thing you interact with is the other. Your window manager is already doing the second job, and doing it better, because it is always there.
- One list, pick one thing. Same interaction at every level. Nothing to learn after the first time.
- Fuzzy search, keyboard only. Type a few letters that are roughly right.
- Multi alphabet search. Type
zoygkla, getΖούγκλα. Typeβεατλες, getBeatles. Never think about your keyboard layout again. - Playlists are text files. Add an artist by typing a name on a line.
- Folders in playlists. A playlist can mix folders and individual tracks.
If your library spans more than one alphabet, plain fuzzy search is not enough: you still have to know which layout you are on before you start typing.
wofi matches against the entry text but renders whatever pre_display_cmd
prints. Those are two different strings, which is the whole trick. Each entry
carries hidden tab-separated search keys:
Bloody Hawk<TAB>bloody hawk<TAB>βλοοδυ ηαωκ
--pre-display-cmd "cut -f1 <<< '%s'"draws only the real name- piping the result through
cut -f1strips the keys back off
Both keys are needed. Folding to Latin alone only fixes the Greek-named
entries. Carrying the Greek fold as well is what lets a Greek-typed query find
Bloody Hawk.
The folding is plain sed, so there is no new dependency.
mpd, mpc, wofi. Optionally a terminal and nvim for playlist editing,
and mpd-mpris plus a panel (HyprPanel,
Waybar, ...) if you want on-screen controls.
The repo is laid out as a GNU Stow
package: everything under mpd-hykr/ mirrors your $HOME, so one command
symlinks it all into place.
git clone https://github.com/iocanel/mpd-hykr
cd mpd-hykr
stow -t ~ mpd-hykrThat gives you:
~/.local/bin/mpd-hykr
~/.config/hypr/media-submap.conf
~/.config/wofi/style.css
~/.config/systemd/user/mpd.service.d/hyprland.conf
~/.config/systemd/user/mpd-mpris.service.d/hyprland.conf
Then source the keybindings from your hyprland.conf:
source = ~/.config/hypr/media-submap.confand make sure ~/.local/bin is on your PATH.
Not a stow user? The layout is still just files - copy the ones you want.
If MPD is not set up yet, start from docs/mpd.conf.sample.
See docs/systemd.md for making MPD survive a reboot
reliably - there is a real gotcha there.
imports = [ ./path/to/mpd-hykr/nix/home-manager.nix ];
services.mpd.musicDirectory = "${config.home.homeDirectory}/Music";SUPER+m enters media mode, then a single key:
| key | action |
|---|---|
m |
pick something to play |
o |
toggle the panel media menu |
p |
play / pause |
j |
next track |
k |
previous track |
j and k stay in the submap, so skipping four tracks is SUPER+m j j j j
rather than four separate chords. Everything else drops you back out.
The picker itself offers five things: play everything, pick a playlist, pick a folder, pick a folder shuffled, or edit a playlist. "Play everything" is first, so it is highlighted on open and you can just hit Enter.
All optional, all environment variables:
| variable | default |
|---|---|
MUSIC_DIR |
read from mpd.conf, else ~/Music |
PLAYLIST_DIR |
~/.local/share/mpd/playlists |
TERMINAL |
first found: kitty, foot, alacritty, wezterm |
EDITOR |
first found: nvim, vim, vi |
WOFI_ARGS |
empty |
Nothing here is Hyprland-specific except the submap file. The script only needs
wofi and mpc. On Sway, translate the submap to a mode block. Swap
hyprland-session.target for your session's target in the systemd drop-ins.
Apache License 2.0