Album Art

Currently there are three methods which rmpc can use to display images. Each of these methods functions differently from the other and have their own advantages, disadvantages and quirks. The preferred and default method is Kitty. Special thanks to yazi for some inspirtion on detecting different kinds of terminals.

The method can be overridden in the config file. Please refer to the Configuration for more information.

Image loading

Images are loaded either from an embedded image inside the music file itself or from cover.png, cover.jpg, or cover.webp located inside the music file’s directory.

Supported terminals

If your terminal is not listed here and you experience issues. Please disable the image method in the config file. Some of the terminals do not correctly report their size, thus some tweaking is needed. For those you need to set max_size_px.

Terminal	Backend	Tmux	Additional Info
All	Block	yes	Only prints ANSI.
Kitty	Kitty	yes	-
Ghostty	Kitty	yes	-
WezTerm	ITerm2	yes	-
vscode	ITerm2	yes	Needs to set max_size_px. Needs to be enabled in vscode.
Tabby	ITerm2	yes	Needs to set max_size_px
Foot	Sixel	yes	Limited image size in tmux
Alacritty	Ueberzug	yes	Needs ueberzugpp
Konsole	Block	yes	Has support for other protocols but they are either incomplete or have severe issues
Others	Ueberzug/Sixel/Kitty	yes	Untested/unsupported. Might need ueberzugpp. Try other backends or disabling album_art altogether if you experience issues.

Configuration

method

method: Kitty | Iterm2 | Sixel | UeberzugWayland | UeberzugX11 | Block | None | Auto

Rendering method used to display images. Currently Kitty, UeberzugWayland and UeberzugX11 are supported. Defaults to Auto which tries to use Kitty first and then Ueberzug if Kitty is not available. For all terminals, Block is now supported. It will fall_back to ANSI if the terminal doesn’t support truecolor.

None completely disables album art display.

order

order: EmbeddedFirst | FileFirst | EmbeddedOnly | FileOnly

Rmpc looks either for cover.jpg, cover.png or cover.webp file in the song’s directory or for an image embedded in the song’s metadata. This configures the order in which these locations are checked.

Defaults to EmbeddedFirst which first searches the embedded metadata and then tries to look for the cover image file.

max_size_px

max_size_px: (<width>, <height>)

Sets limit for the album art size. If the album art is larger than this, it will be resized to fit the limit.

You can set this to (0, 0) (no limit) if you use terminal emulator which properly reports its size and rmpc will figure out the maximum size itself. This is needed only for terminals which do not report their size correctly. Default is (1200, 1200). Ueberzug backend is not influenced by this setting.

disabled_protocols

disabled_protocols: string[]

Album art will NOT be fetched and displayed for songs with path starting with any of the given protocols. Set to empty array to enable all protocols. Defaults to ["http://", "https://]

vertical_align

vertical_align: Top | Center | Bottom

Where to align album art vertically. Not supported by ueberzugpp backend.

horizontal_align

horizontal_align: Left | Center | Right

Where to align album art horizontally. Not supported by ueberzugpp backend.

default_album_art_path

default_album_art_path: None | Some("<string>")

The default album art image can also be changed in your theme.

custom_loader

custom_loader: <string[]>

A custom script/program to use to load album art image from instead of using the inbuilt functionality. The script must uphold several invariants, failure to do so will result in errors and undefined behavior. Supported formats are jpg, png and webp.

Example: custom_loader: ["~/.config/rmpc/scripts/custom_art_loader"]

Protocol

The script must always exit with code 0. The output must be printed to stdout. The current song’s file path is available as the environment variable $FILE. There are three possible actions to take and each of them must print the following exactly.

• Display a successfully loaded custom image
  • size: <bytes> followed by a newline where <bytes> is the image’s size in bytes
  • action: display followed by a newline and the raw image bytes
• Fallback to rmpc default behavior
  • action: fallback followed by a newline
• Display the default_album_art
  • action: displaydefault followed by a newline

Example script that always displays my_custom_cover.jpg in the songs’s directory and the default album art if not found:

#!/usr/bin/env bash

# This script is only for illustrative purposes only. You should also check if the $FILE is really
# relative to your music_dir or comes from a mount/absolute file path etc.

music_dir="$HOME/Music"
path="$music_dir/$FILE"
parent_dir=$(dirname "$path")
cover_path="$parent_dir/my_custom_cover.jpg"

if [ -f "$cover_path" ]; then
    size=$(stat -c%s "$cover_path")
    echo "size: $size" # tell rmpc to read this many bytes
    echo "action: display" # instruct rmpc that a custom image should be displayed
    cat "$cover_path" # print the raw bytes to stdout
else
    echo "action: fallback" # tell rmpc to fall back to ask MPD for image as usual
fi

Backends

Kitty

This method should work out of the box if your terminal supports it. It is a reliable but a little bit slower method. Supports animated gifs.

Cons:

• Image does not change when using tmux and possibly other methods of multiplexing if the change occurs while the tab is not currently active.

Ueberzugpp

Requires ueberzugpp. Art is aligned to the top of and its position cannot be changed.

Pros:

• In my testing a bit faster than Kitty

Cons:

• Requires third party dependency
• Is a separate window on top of the terminal. This might require some additional configuration to make it look good in your environment.
• Album art has to be hidden completely when modal windows are shown

Iterm2 Inline image protocol

Supported only in select few terminals and some of them need additional configuration. Works best in WezTerm. Supports animated gifs, but suffers from the same issues as Sixel in Tmux, more info here.

Sixel

Cons:

• Has lower color depth than the alternatives.
• Much lower image size can be transmitted through tmux due to sixel being a very size inefficient protocol. Tmux supports only 1MB of data by default. Increase this limit by setting input-buffer-size in your tmux config. See man tmux for more info.

Block

Displays images using ASCII blocks. Results in a very pixelated/low resolution image but should be supported pretty much everywhere.