Download and display album art or display embedded (or folder-based) album art using a bash script; a largely rewritten fork of kunst

Project maintained by uriel1998 Hosted on GitHub Pages — Theme by mattgraham


Download and display album art or display embedded (or folder-based) album art using a bash script; a largely rewritten fork of kunst

vindauga logo

Output example


  1. About
  2. License
  3. Prerequisites
  4. How to use
  5. Album Art Cache
  6. Using With Conky
  7. Using With SXIV
  8. Cantata Helper
  9. TODO

1. About

vindauga is a program (and probably daemon) that finds or extracts (if needed) the album art for the currently playing song in mpd, and then displays it in a little window or as part of a conky display.

It is a (largely rewritten) fork of kunst by Siddharth Dushantha. There were some behaviors of kunst that I wanted to fix and improve upon, so I created vindauga. There is also a great debt to this blog post by “Raphael” for the conky bits.

vindauga does not loop on a timer. Instead it waits for mpd to send a “player” event. When it receives a “player” event, it wakes up and takes action. This makes vindauga really lightweight as a daemon.

When vindauga wakes up, it looks at the currently playing track from mpd. It then checks its own cache of album artwork (see below for details), then the music folder, then embedded artwork, then the CoverArt Archive (if the music has the MusicBrainz ID embedded), then Deezer.

If none of those exist, it checks if there is a configured local directory with images in it designated as placeholder images. If that doesn’t exist, it checks for a designated placeholder image.

If that doesn’t exist, it will use the optional simple_placeholder_images to download a nice picture from online and use that as a temporary album cover.

If that doesn’t exist, then it decodes a built in default album image to the cache directory.

At that point, sxiv or conky can display the image.

The filestructure in the cache is meant to be fairly straightforward and obvious so that the images may be used (if desired) with other programs.

vindauga means “window”.

2. License

This project is licensed under the MIT license. For the full license, see LICENSE.

3. Prerequisites

These may already be installed on your system.

You may have to install these

You do not have to choose all or any of these.

4. How to use

For example, as I use the conky interface, I have two keybinds. One calls vindauga -y -z. That starts vindauga and the conky interface. The other calls vindauga -k and kills the process efficiently. You can even do this in a single script. For example, a single binding that calls will start the conky process and daemon, and a second run of it will turn it off.


The file vindauga.rc is optional, and goes in $HOME\.config. Do NOT remove the commented lines. The example below has the defaults (if there is no rc file) in place.

# Music Dir
# Cache Dir
# Placeholder Image

# Placeholder Directory

# Display Size
#SXIV X position
#SXIV Y position
#ConkyFile location

#MPD Host

As the functionality expands, additional lines may be added to the bottom, allowing for backward compatibility.

5. Album Art Cache

The cache - by default in $HOME/.cache/vindauga - stores the discovered and cached album art in the format:


This is deliberately very similar to the way Ario and other programs store the information.

For example, a partial list of my cache is:

Aesthetic Perfection-Love Like Lies.album.jpg
Asking Alexandria-A Lesson Never Learned.album.jpg
Avatar-Hail the Apocalypse.album.jpg
Fear Factory-Demanufacture.album.jpg
Front Line Assembly-Echoes.album.jpg
In Flames-I, the Mask.album.jpg
KMFDM-Naïve: Hell to Go.album.jpg
Nine Inch Nails- [Deceased].album.jpg
Skinny Puppy-Mind: The Perpetual Intercourse.album.jpg
Throbbing Gristle-The First Annual Report of Throbbing Gristle.album.jpg
外山雄三-Civilization V.album.jpg

When there is a special character - /()& - it is completely omitted in writing the cache filename. This is intentional behavior to minimize the number of times that the program chokes. (Hopefully zero!)

The artist image is likewise obtained from Deezer or (if you obtain a API key and put it in the config file) and stored in the cache directory.

If you use the file, it will softlink from the music directory. This is obviously superior in terms of space saved.

6. Using with Conky

I have enclosed a basic configuration for conky (as seen in the video above) that has the information and layout that I want. You can obviously incorporate this into your own conky or edit it to your aesthetic delight. Editing conky configurations is well past the scope of this document.

See the file vindauga_conkyrc for the example. It includes both the base image seen in the screenshot below as well as an XCF file if you wish to design your own.

Output example

7. Using with SXIV

In kunst, the call to sxiv does not include the -S 2 switch. On my Debian system, without that switch, sxiv does not change the image once loaded.

Unfortunately, if sxiv tries to reload the image at the same time that a new one is being loaded, it aborts. There is a PID check built in to vindauga that relaunches sxiv if it’s closed. If it is relaunched, it loads back to the default location (or location specified in the rc file).

SXIV and OpenBox

I use this configuration with my OpenBox:

    <application class="Sxiv">

Or if you don’t want to move it around, and have it be below other windows:

    <application class="Sxiv">

8. Cantata Helper

The artist images that Cantata fetches are - for me at least - frequently not correct. I’m not sure why, honestly. But I figured that since I’m pulling down the artist images anyway and storing them in the cache directory, I might as well use them. The script reads vindauga’s rc, then symlinks the appropriate artist images from vindauga’s cache.

9. Todo

Steven Saus injects people with radioactivity for his day job, but only to serve the forces of good.