Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


StumpWM interface for the zbucium music player. No actual music files needed on your pc. It's all played from youtube with mpv and info from


Follow the steps from the zbucium's README to install the music player first. More importantly, you will need a account and an API key.

After that,

# Clone to stumpwm's modules folder 
git clone ~/stumpwm.d/modules/zbucium-stump
; And load the module in your init file
(load-module "zbucium-stump")


This is an interface for the above mentioned music player. My greatest wish was to be able to play, in the background, without ever having to leave Emacs again. That means, I would be able to skip songs, see what's playing, add the current playing song to the list of loved songs, change the 'radio' by playing a single artist, similar artists, my loved songs or playing songs from a given genre. On top of that, see the lyrics, again, without leaving the editor. And best of all, search through all the songs that I've ever played (with this player, at least) for that tune that keeps bugging me but the artist of which eludes me. That is, ask the player for all the songs that have a given lyrics and then select and play the one that seems to best fit it from a list of candidates, interactively. And if I ever want to leave Emacs, I can open the browser with the currently playing song's youtube video at any time with the press of a key.

Enough talk!

zbucium play artist

What happened? First, I'm calling the stumpwm command defined by zbucium's module, zbucium-play-artist. I'm only calling this as such for illustration purposes. Normally you'll bind this command to a key combination. It asks me for an artist and if I want random(i.e. shuffle) play or not. The next command is zbucium-what-is-playing, which, surely enough, shows me the top song from this artist playing in the background. The next command is zbucium-lyrics.

Here is another nice one. I can choose to play an album. Again it asks me for an artist (non random by default) and displays the albums for this artist. If I would to chose one at this stage, it will play it, starting from the first song till the last, and back again. But I can also browse the album contents, go back to the album page, chose another album (C-l), etc. In this case, I've chosen to play a single song, from one of the albums.

zbucium play album

All the commands expected from a player are available. Stop, pause, skip song and seek, either as standalone command (+- 5 seconds seek, for exemple), or interactively.

zbucium seek song

The same song is playing. You can go forward or backward, in real time (with the , and '.' keys, respectively). As you can see, the timings are not quite right. This is a limitation of the player used, mpv, which is clearly stated in their documentation as being only an approximation. Still, good enough for small searches.

Every song played also saves the lyrics. So let's try to play a song, by searching it's lyrics.

zbucium search song

The player is stopped initially. Suddently, I have this i feel i know you tune in my head. Who is playing that?! Fire up the song search, put in the verse, or part of it, and select a song from the list of candidates (if they're too many, you can begin writing something to filter them in real time). Sure enough, after the selection, the right song is now playing.

But, the best of all, is that you can start playing some genre or similar artists and leave it on forever. That's a nice way to discover new music.

Zbucium Commands (API)

These are all commands defined by zbucium. You can call them directly or, better, have some keybindings for them.

zbucium-play-song artist

Play a single song, over and over again.

zbucium-play-artist artist random

Play *ntracks* (see the configuration bellow) for the given artist. Can be
played random.

zbucium-play-album artist

Play a single album for the given artist. While selecting the album, `C-l`
can be used to peek inside the album tracklist and then go back to the album
list. So this command can actually play either an album or a single song
from an album.

zbucium-play-tag tagname random

Play the best *ntracks* (see configuration) for the given tag.

zbucium-play-user-songs username random

Play *user-ntracks* (see configuration) numbers of songs from the given user name.

zbucium-play-my-loved-songs random

Same as above, only it uses the default configured username from the lastfm library.

zbucium-play-artist-similar artist

Play artists similar to the given artist. The number of artists considered
can be configured by setting the *nartists* parameter. Each song is picked
by first chosing a random artist similar to the given artist and then
chosing a random song from this artist.

zbucium-play-tag-similar tag

Similar with zbucium-play-tag, but I've had better results with this
one. The toptracks for a given tag are sometimes taken up by a single artist
so there no actual diversity there. With this command, a random artist is
picked from the list of artists most representative for this tag. And from
that artist a random song is selected.


Display the currently playing artist and songs.


Display the currentply playing songs' lyrics.


Add the currently playing song to the list of loved songs for the user
configured by the lastfm library


The reverse of the above.


Play the next song.


Stop playing and go do something else with your day.

zbucium-search-song lyrics

Return a list of artist / song / lyrics verse line that matches the string
supplied by the user. On choosing one entry in the list, that artist's song
is played.


Toggle the play/pause status.


Replay the song from the beginning


Go back 5 seconds.


Go forward 5 seconds.


Song position, in %. Not very accurate.


This is the interactive forward or backward song seeking, and it is actually
a Stump [interactive
keymap]( After entering
it, `,` and '.' are used to seek backwards and forwards, respectively. `C-g`
quits the interactive keymap.


Return the current song position, in seconds, from the beginning. This is
returned by mpv, which is imprecise.


Pause the player (mpv) and open the default browser with the youtube page
for the currently playing song.


This will exit the current player instance (mpv) and restart it with video
support, continuing from where it left off.


The number of songs or artists taken into consideration when playing something can be configured. Just set these variables in your init file, otherwise, the default values are used. More can be added in the future if they can enhance the listening experience in any way.

*ntracks* 20

Number of tracks to request from lastfm. These are the first best number of
tracks for the given artist, according to the charts.

*user-ntracks* 500

Number of songs to consider when playing a list of loved songs.

*nartists* 20

Number of artists to request from lastfm. These are used when playing similar
artists or artists with a given tag.


This is just an example to get you started. I'm using my leader key, C-t and bind the zbucium map to m. So asking for the lyrics would be C-t m l. Modify your init file to suit your wants.

(define-key *top-map* (kbd "XF86AudioPlay") "zbucium-play/pause")
(define-key *top-map* (kbd "XF86AudioPrev") "zbucium-replay")
(define-key *top-map* (kbd "XF86AudioNext") "zbucium-next-song")
(define-key *top-map* (kbd "XF86AudioStop") "zbucium-stop")

(defvar *zbucium-map* (make-sparse-keymap))
(define-key *root-map* (kbd "m") '*zbucium-map*)

(define-key *zbucium-map* (kbd "v") "zbucium-turn-video-on")
(define-key *zbucium-map* (kbd "f") "zbucium-switch-to-browser")
(define-key *zbucium-map* (kbd "w") "zbucium-what-is-playing")
(define-key *zbucium-map* (kbd "l") "zbucium-lyrics")
(define-key *zbucium-map* (kbd "s") "zbucium-search-song")
(define-key *zbucium-map* (kbd "p") "zbucium-play-artist")
(define-key *zbucium-map* (kbd ",") "zbucium-seek-backward")
(define-key *zbucium-map* (kbd ".") "zbucium-seek-forward")
(define-key *zbucium-map* (kbd "n") "zbucium-next-song")


Copyright (c) 2019 Mihai Olteanu

Licensed under the GPLv3 license.


StumpWM interface for the zbucium music player






No releases published


No packages published