Skip to content

Latest commit

 

History

History
234 lines (148 loc) · 8.87 KB

README.md

File metadata and controls

234 lines (148 loc) · 8.87 KB
Raw

i3blocks-mpris

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

screenshot

Click the image above to watch a screencast.

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

Features

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

Installation

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.

Dependencies

Required (installed automatically):

Optional (installed manually):

Usage

Add the following lines to your i3blocks config:

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

Configuration

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.

Config parameters

player

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

format

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:

Filter Description Example
upper str.upper “lorem Ipsum DOLor” → “LOREM IPSUM DOLOR”
lower str.lower “lorem Ipsum DOLor” → “lorem ipsum dolor”
capitalize str.capitalize “lorem Ipsum DOLor” → “Lorem ipsum dolor”
title str.title “lorem Ipsum DOLor” → “Lorem Ipsum Dolor”
icon converts a textual status to an icon, see the status_icons option below “Paused” → “⏸”

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:

Artist/Title Format Result
Long Theater {artist:.9} Long Thea
Toooooooooooool {artist:…<10.9} Toooooooo…
Godzilla / Golderia {artist: ^10} - {title: ^10.4} Godzilla - Gold
Apparatus Superiority / Player Two {artist:…<16.15} - {title:>15} Apparatus Super… - Player Two
In Fire / Lan Connected {artist:.10,…} - {title:.10,…} In Fire - Lan Connec…

placeholder

Type: string

Default value: empty string

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

markup_escape

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.

status_icons

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.

mouse_buttons

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.

sanitize_unicode

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.

dedupe

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

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

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

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

Changelog

See CHANGELOG.md.

License

The MIT License.