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](https://raw.githubusercontent.com/uriel1998/vindauga/master/vindauga.png "logo")
![Output example](https://raw.githubusercontent.com/uriel1998/vindauga/master/output.gif "Example output")
4. [How to use](#4-how-to-use)
5. [Album Art Cache](#5-album-art-cache)
6. [Using With Conky](#6-using-with-conky)
7. [Using With SXIV](#7-using-with-sxiv)
8. [Cantata Helper](#8-cantata-helper)
## 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](https://github.com/sdushantha/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](http://lmazy.verrech.net/2011/01/cover-art-with-conky-and-mpd/)
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.
* `curl` command-line tool for getting data using HTTP protocol. `curl` can be found on major Linux distributions.
* `wget` command-line tool for getting data using HTTP protocol. `wget` can be found on major Linux distributions.
* `grep` command-line tool used for parsing downloaded XML data. `grep` can be found on major Linux distributions.
* `awk` command-line tool for parsing string data. `awk` can be found on major Linux distributions.
* `ffmpeg` command-line tool for parsing string data. `ffmpeg` can be found on major Linux distributions.
* `imagemagick` command-line tool for parsing string data. `imagemagick` can be found on major Linux distributions.
### You may have to install these
* `base64` command-line tool for encoding/decoding data. `base64` can be found on major Linux distributions.
* `mpc` command-line tool for controlling mpd. `mpc` can be found on major Linux distributions.
* `mpd`, the music player daemon. `mpd` can be found on major Linux distributions.
* `jq` command-line tool for parsing JSON data. `jq` can be found on major Linux distributions or on [GitHub](https://github.com/stedolan/jq)
### You do not have to choose all or any of these.
* [Optional] `ionice`, to lower the io priority of the script. `ionice` can be found on major Linux distributions.
* [Optional] `sxiv`, the Simple X Image Viewer, available in most major distributions or on [GitHub](https://github.com/muennich/sxiv)
* [Optional] `conky`, a light-weight system monitor for X available in most major distributions or on [GitHub](https://github.com/brndnmtthws/conky)
* [Optional] `simple_placeholder_images` to subsitute in generic images found online when cover art is not found. Available on [GitHub](https://github.com/uriel1998/simple_placeholder_images),[GitLab](https://gitlab.com/uriel1998/simple_placeholder_images), or my [personal repository](https://git.faithcollapsing.com/simple_placeholder_images)
## 4. How to use
* As a daemon: Execute `vindauga.sh` from the terminal. It is safe to run it as `vindauga.sh &` and use the `-k` switch to kill a running vindauga process.
* If `ionice` is detected, it is automatically applied to the current script.
* To run it once (for example, from within a `conky` configuration), execute `vindauga.sh -c` . Note that this is almost certainly less efficient than running it as a daemon.
* To not call `sxiv`, execute `vindauga -y`.
* To invoke vindauga's control of its conky window, execute `vindauga -z` - though realistically you should probably `vindauga -y -z`.
* To kill an existing background `vindauga`, execute `vindauga -k`. This will kill both the instance of `sxiv` in use and the background script.
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 `vindauga_toggle.sh` 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
#Last.FM API key (OPTIONAL)
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
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
Front Line Assembly-Echoes.album.jpg
In Flames-I, the Mask.album.jpg
KMFDM-Naïve: Hell to Go.album.jpg
Nine Inch Nails-220.127.116.117 [Deceased].album.jpg
Skinny Puppy-Mind: The Perpetual Intercourse.album.jpg
THE FEVER 333-STRENGTH IN NUMB333RS.album.jpg
Throbbing Gristle-The First Annual Report of Throbbing Gristle.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 Last.fm (if you obtain a
last.fm [API key](https://www.last.fm/api) and put it in the config file) and
stored in the cache directory.
If you use the `ffixer_covers.sh` 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
![Output example](https://raw.githubusercontent.com/uriel1998/vindauga/master/updated_vindauga_conky.png "Example output")
## 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:
Or if you don't want to move it around, and have it be below other windows:
## 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 `cantata-helper.sh` reads vindauga's rc, then symlinks
the appropriate artist images from vindauga's cache.
## 9. Todo
* Write folder.jpg and cover.jpg to music directories, if desired.
* Embed found album art, if desired.
* Create script to retrieve artwork without or using `vindauga`
* Specify different mpd profiles to MPC so that you can view albumart for a remote MPD
* Incorporate makefile for those who want it?
* Automatically softlink data for Ario / GMPC
* Automatically softlink albumart for cantata