Skip to main content

A persistent i3blocks blocklet for the Spotify desktop app

Project description


A persistent i3blocks blocklet for the Spotify desktop app.


Click the image above to watch a screencast.


  • 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.5 or later is required.

The blocket can be installed from PyPI using pip:

python3 -m pip install [--user] i3blocks-spotify-persist

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

To avoid dependecy hell, pipx can be used:

pipx install i3blocks-spotify-persist

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


Required (installed automatically):

Optional (installed manually):


Add the following lines to your i3blocks config:

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


The blocket can be configured using a JSON config file. The config itself and all its options are optional.

Config options


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 fitlers:

  • upper — converts a string to uppercase
  • lower — converts a string to lowercase
  • capitalize — converts the first character of a string to uppercase and the rest to lowercase
  • icon — for status field only: converts a textual status to an icon (see the status_icons option below)


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

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.

Config example

    "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"

Command line arguments

  • -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):

  • --format
  • --markup-escape / --no-markup-escape
  • --dedupe / --no-dedupe


The MIT License.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

i3blocks-spotify-persist-1.2.0.tar.gz (7.6 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page