A persistent i3blocks blocklet for the MPRIS D-Bus interface.

Click the image above to watch a screencast.

This project was previously known as i3blocks-spotify-persist.

• near-immediate updates thanks to the event-driven model: the blocket is a constantly running process receiving D-Bus signals
• configurable output
• configurable mouse click actions (i3blocks version 1.5 or later is required)

Python version 3.8 or later is required.

The blocket can be installed from PyPI using pip:

python3 -m pip install [--user] i3blocks-mpris

Once the package is installed, there will be a blocket script named i3blocks-mpris somewhere depending on the presence of a --user pip flag (e.g., /usr/local/bin/i3blocks-mpris or ~/.local/bin/i3blocks-mpris).

To avoid dependecy hell, pipx can be used:

pipx install i3blocks-mpris

In this case the blocket script will be placed in ~/.local/bin directory.

Required (installed automatically):

• PyGObject
• dbus-python

Optional (installed manually):

• Font Awesome (for status icons)

Add the following lines to your i3blocks config:

[mpris]
command=/path/to/bin/i3blocks-mpris -c /path/to/config.json
interval=persist

The blocket can be configured using a JSON config file and/or command line arguments. The only required parameter is player. It must be specified using either the config or the command line argument. Other config parameters and the config itself are optional.

Type: string

Default value: no default value, must be specified

A name of the player, either a full bus name — org.mpris.MediaPlayer2.<player>[.<instance>] — or its <player>[.<instance>] part.

Examples:

• org.mpris.MediaPlayer2.spotify
• org.mpris.MediaPlayer2.vlc.instance7389
• spotify
• vlc.instance7389

Type: string

Default value: {status}: {artist} – {title}

A template string with placeholders. Placeholder formats are {field} and {field:filter}.

Supported fields:

• status, one of enum values: Playing, Paused, Stopped
• artist
• title

Supported filters:

Any other Python 3.8+ format spec is also supported, here are some examples.

In particular, a long artist or title name can be shortened, centered, padded in a few ways. A new format spec has been added to truncate and add a suffix but only if the string has been shortened, the syntax for this case is .<max_length>,<suffix> and the last row of examples in this table use it:

Type: string

Default value: empty string

A message displayed when there is no player. If an empty string (the default), the blocklet completely disappears.

Type: boolean

Default value: false

This option specifies whether to escape special characters (such as <, >, &) using corresponding XML entities. Set to true if Pango markup is used (markup=pango in your i3blocks config), false otherwise.

Type: object

Default value: {"Playing": "\uf04b", "Paused": "\uf04c", "Stopped": "\uf04d"}

This option provides a mapping for the icon filter (see above). The default value uses icons from Font Awesome.

Type: object

Default value: {"1": "PlayPause"}

This option provides a mapping of X11 mouse buttons numbers to MPRIS methods. You can use the xev program to determine button numbers.

Type: boolean

Default value: true

If this option is set to true, the blocklet removes some unicode characters (more specifically, characters belonging to Cc, Cs, Co, and Cn general categories). See issue #9 for details.

Type: boolean

Default value: true

For some reason, the Spotify app emits several identical signals for one action/event (e.g., it produces four PropertiesChanged signals when a track is played or paused). If this option is set true, the blocklet will compare the updated message with the previous one and print it only if it has changed. There is no reason to turn off deduplication except for debugging.

{
    "player": "spotify",
    "format": "<span font_family='monospace' color='#ffa651' weight='bold'>{status:icon} {status:upper}</span> <span color='#72bf44' weight='bold'>{artist}</span><span color='#ffa651'>᛫</span><span color='#b2d235'>{title}</span>",
    "markup_escape": true,
    "status_icons": {
        "Playing": "|>",
        "Paused": "||",
        "Stopped": "[]"
    },
    "mouse_buttons": {
        "1": "PlayPause",
        "9": "Previous",
        "8": "Next"
    }
}

• -h, --help — show all command line arguments and exit
• -c, --config — a path to the config file (see above)

The following arguments override corresponding config options or defaults (that is, command line arguments have the highest precedence):

• -p, --player
• -f, --format
• --markup-escape / --no-markup-escape
• --sanitize-unicode / --no-sanitize-unicode
• --dedupe / --no-dedupe

See CHANGELOG.md.

The MIT License.