https://github.com/un-def/i3blocks-mpris

A persistent i3blocks blocklet for the MPRIS D-Bus interface (f.k.a. i3blocks-spotify-persist)
https://github.com/un-def/i3blocks-mpris

blocklet i3blocks i3blocks-spotify-persist mpris spotify

Last synced: about 1 year ago
JSON representation

A persistent i3blocks blocklet for the MPRIS D-Bus interface (f.k.a. i3blocks-spotify-persist)

Host: GitHub
URL: https://github.com/un-def/i3blocks-mpris
Owner: un-def
License: mit
Created: 2018-03-08T14:25:40.000Z (over 8 years ago)
Default Branch: master
Last Pushed: 2024-09-08T09:00:23.000Z (almost 2 years ago)
Last Synced: 2025-03-27T01:02:29.149Z (about 1 year ago)
Topics: blocklet, i3blocks, i3blocks-spotify-persist, mpris, spotify
Language: Python
Homepage:
Size: 78.1 KB
Stars: 16
Watchers: 1
Forks: 3
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

README

          # i3blocks-mpris

A persistent [i3blocks][i3blocks] blocklet for the [MPRIS][mpris-spec] D-Bus interface.

[![screenshot][screenshot]][screencast]

Click the image above to watch a [screencast][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][i3blocks-1.5] or later is required)

## Installation

**Python version 3.8 or later is required.**

The blocket can be installed from PyPI using `pip`:

```shell

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][pipx] can be used:

```shell

pipx install i3blocks-mpris

```

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

## Dependencies

Required (installed automatically):

  * [PyGObject][pygobject]

  * [dbus-python][dbus-python]

Optional (installed manually):

  * [Font Awesome][font-awesome] (for status icons)

## 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.[.]` — or its `[.]` 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][mpris-playbackstatus-type] values: `Playing`, `Paused`, `Stopped`

  * `artist`

  * `title`

Supported filters:

| Filter | Description | Example |

|--------------|-----------------------------------------------------------------------------|-------------------------------------------|

| `upper`      | [`str.upper`][python-docs-str-upper]                                        | “lorem Ipsum DOLor” → “LOREM IPSUM DOLOR” |

| `lower`      | [`str.lower`][python-docs-str-lower]                                        | “lorem Ipsum DOLor” → “lorem ipsum dolor” |

| `capitalize` | [`str.capitalize`][python-docs-str-capitalize]                              | “lorem Ipsum DOLor” → “Lorem ipsum dolor” |

| `title`      | [`str.title`][python-docs-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][python-docs-str-format-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 `.,` 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][font-awesome].

#### mouse_buttons

*Type:* object

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

This option provides a mapping of X11 mouse buttons numbers to [MPRIS methods][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][sanitize-unicode-categories]). See [issue #9][sanitize-unicode-issue] 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

```json

{

    "player": "spotify",

    "format": "{status:icon} {status:upper} {artist}᛫{title}",

    "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][changelog].

## License

The [MIT License][license].

[screenshot]: https://tinystash.undef.im/il/3wQUgnuCRyADYHZ4Vi6qN29p65njk1DdsjUu5WePUBNmUak7Z9y6CqNRnEzMN2pVBVsZvBDJ9GDyJUGGYd3Fgbqd.png

[screencast]: https://tinystash.undef.im/il/2Xscwkh3rAhw2iqSr9XxJ2Meph57eXiHwkkWiAgroiuGPXB9fYnPJqgdYR7nR4B9U5hHvxxGtr8Sc3QaquwjHT38.mp4

[license]: https://github.com/un-def/i3blocks-mpris/blob/master/LICENSE

[changelog]: https://github.com/un-def/i3blocks-mpris/blob/master/CHANGELOG.md

[i3blocks]: https://github.com/vivien/i3blocks

[i3blocks-1.5]: https://github.com/vivien/i3blocks/releases/tag/1.5

[dbus-python]: https://dbus.freedesktop.org/doc/dbus-python/

[pygobject]: https://pygobject.readthedocs.io/en/latest/

[font-awesome]: https://fontawesome.com/

[pipx]: https://pipxproject.github.io/pipx/

[mpris-spec]: https://specifications.freedesktop.org/mpris-spec/latest/

[mpris-playbackstatus-type]: https://specifications.freedesktop.org/mpris-spec/latest/Player_Interface.html#Enum:Playback_Status

[mpris-methods]: https://specifications.freedesktop.org/mpris-spec/latest/Player_Interface.html#methods

[sanitize-unicode-issue]: https://github.com/un-def/i3blocks-mpris/issues/9

[sanitize-unicode-categories]: https://en.wikipedia.org/wiki/Unicode_character_property#General_Category

[python-docs-str-upper]: https://docs.python.org/3/library/stdtypes.html#str.upper

[python-docs-str-lower]: https://docs.python.org/3/library/stdtypes.html#str.lower

[python-docs-str-capitalize]: https://docs.python.org/3/library/stdtypes.html#str.capitalize

[python-docs-str-title]: https://docs.python.org/3/library/stdtypes.html#str.title

[python-docs-str-format-examples]: https://docs.python.org/3.8/library/string.html#format-examples

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/un-def/i3blocks-mpris

Awesome Lists containing this project

README