| Name | i3blocks-mpris JSON |
| Version |
2.2.0
JSON |
| download |
| home_page | None |
| Summary | A persistent i3blocks blocklet for the MPRIS D-Bus interface |
| upload_time | 2024-09-08 08:55:55 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
i3blocks
blocklet
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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.<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][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 `.<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][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": "<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][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
Raw data
{
"_id": null,
"home_page": null,
"name": "i3blocks-mpris",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "i3blocks, blocklet",
"author": null,
"author_email": "Dmitry Meyer <me@undef.im>",
"download_url": "https://files.pythonhosted.org/packages/8d/47/57de0b44695d3f98c7e6169ecd49012bcb582130bef8f17c77a349702633/i3blocks_mpris-2.2.0.tar.gz",
"platform": null,
"description": "# i3blocks-mpris\n\nA persistent [i3blocks][i3blocks] blocklet for the [MPRIS][mpris-spec] D-Bus interface.\n\n[![screenshot][screenshot]][screencast]\n\nClick the image above to watch a [screencast][screencast].\n\nThis project was previously known as **i3blocks-spotify-persist**.\n\n\n## Features\n\n* near-immediate updates thanks to the event-driven model: the blocket is a constantly running process receiving D-Bus signals\n* configurable output\n* configurable mouse click actions (i3blocks [version 1.5][i3blocks-1.5] or later is required)\n\n\n## Installation\n\n**Python version 3.8 or later is required.**\n\nThe blocket can be installed from PyPI using `pip`:\n\n```shell\npython3 -m pip install [--user] i3blocks-mpris\n```\n\nOnce 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`).\n\nTo avoid dependecy hell, [pipx][pipx] can be used:\n\n```shell\npipx install i3blocks-mpris\n```\n\nIn this case the blocket script will be placed in `~/.local/bin` directory.\n\n\n## Dependencies\n\nRequired (installed automatically):\n * [PyGObject][pygobject]\n * [dbus-python][dbus-python]\n\nOptional (installed manually):\n * [Font Awesome][font-awesome] (for status icons)\n\n\n## Usage\n\nAdd the following lines to your i3blocks config:\n\n```\n[mpris]\ncommand=/path/to/bin/i3blocks-mpris -c /path/to/config.json\ninterval=persist\n```\n\n\n## Configuration\n\nThe 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.\n\n### Config parameters\n\n#### player\n\n*Type:* string\n\n*Default value:* no default value, must be specified\n\nA name of the player, either a full bus name \u2014 `org.mpris.MediaPlayer2.<player>[.<instance>]` \u2014 or its `<player>[.<instance>]` part.\n\nExamples:\n\n * org.mpris.MediaPlayer2.spotify\n * org.mpris.MediaPlayer2.vlc.instance7389\n * spotify\n * vlc.instance7389\n\n#### format\n\n*Type:* string\n\n*Default value:* `{status}: {artist} \u2013 {title}`\n\nA template string with placeholders. Placeholder formats are `{field}` and `{field:filter}`.\n\nSupported fields:\n\n * `status`, one of [enum][mpris-playbackstatus-type] values: `Playing`, `Paused`, `Stopped`\n * `artist`\n * `title`\n\nSupported filters:\n\n| Filter | Description | Example |\n|--------------|-----------------------------------------------------------------------------|-------------------------------------------|\n| `upper` | [`str.upper`][python-docs-str-upper] | \u201clorem Ipsum DOLor\u201d \u2192 \u201cLOREM IPSUM DOLOR\u201d |\n| `lower` | [`str.lower`][python-docs-str-lower] | \u201clorem Ipsum DOLor\u201d \u2192 \u201clorem ipsum dolor\u201d |\n| `capitalize` | [`str.capitalize`][python-docs-str-capitalize] | \u201clorem Ipsum DOLor\u201d \u2192 \u201cLorem ipsum dolor\u201d |\n| `title` | [`str.title`][python-docs-str-title] | \u201clorem Ipsum DOLor\u201d \u2192 \u201cLorem Ipsum Dolor\u201d |\n| `icon` | converts a textual `status` to an icon, see the `status_icons` option below | \u201cPaused\u201d \u2192 \u201c\u23f8\u201d |\n\nAny other Python 3.8+ format spec is also supported, [here are some examples][python-docs-str-format-examples].\n\nIn particular, a long `artist` or `title` name can be shortened, centered, padded in a few ways. A new format spec has been added to\ntruncate and add a suffix but only if the string has been shortened, the syntax for this case is `.<max_length>,<suffix>` and the\nlast row of examples in this table use it:\n\n| Artist/Title | Format | Result |\n|----------------------------------------|-----------------------------------|----------------------------------------|\n| `Long Theater` | `{artist:.9}` | `Long Thea` |\n| `Toooooooooooool` | `{artist:\u2026<10.9}` | `Toooooooo\u2026` |\n| `Godzilla` / `Golderia` | `{artist: ^10} - {title: ^10.4}` | ` Godzilla - Gold ` |\n| `Apparatus Superiority` / `Player Two` | `{artist:\u2026<16.15} - {title:>15}` | `Apparatus Super\u2026 - Player Two` |\n| `In Fire` / `Lan Connected` | `{artist:.10,\u2026} - {title:.10,\u2026}` | `In Fire - Lan Connec\u2026` |\n\n#### placeholder\n\n*Type:* string\n\n*Default value:* empty string\n\nA message displayed when there is no player. If an empty string (the default), the blocklet completely disappears.\n\n#### markup_escape\n\n*Type:* boolean\n\n*Default value:* `false`\n\nThis 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.\n\n#### status_icons\n\n*Type:* object\n\n*Default value:* `{\"Playing\": \"\\uf04b\", \"Paused\": \"\\uf04c\", \"Stopped\": \"\\uf04d\"}`\n\nThis option provides a mapping for the `icon` filter (see above). The default value uses icons from [Font Awesome][font-awesome].\n\n#### mouse_buttons\n\n*Type:* object\n\n*Default value:* `{\"1\": \"PlayPause\"}`\n\nThis option provides a mapping of X11 mouse buttons numbers to [MPRIS methods][mpris-methods]. You can use the `xev` program to determine button numbers.\n\n#### sanitize_unicode\n\n*Type:* boolean\n\n*Default value:* `true`\n\nIf 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.\n\n\n#### dedupe\n\n*Type:* boolean\n\n*Default value:* `true`\n\nFor 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.\n\n### Config example\n\n```json\n{\n \"player\": \"spotify\",\n \"format\": \"<span font_family='monospace' color='#ffa651' weight='bold'>{status:icon} {status:upper}</span> <span color='#72bf44' weight='bold'>{artist}</span><span color='#ffa651'>\u16eb</span><span color='#b2d235'>{title}</span>\",\n \"markup_escape\": true,\n \"status_icons\": {\n \"Playing\": \"|>\",\n \"Paused\": \"||\",\n \"Stopped\": \"[]\"\n },\n \"mouse_buttons\": {\n \"1\": \"PlayPause\",\n \"9\": \"Previous\",\n \"8\": \"Next\"\n }\n}\n\n```\n\n\n## Command line arguments\n\n * `-h`, `--help` \u2014 show all command line arguments and exit\n * `-c`, `--config` \u2014 a path to the config file (see above)\n\nThe following arguments override corresponding config options or defaults (that is, command line arguments have the highest precedence):\n\n * `-p`, `--player`\n * `-f`, `--format`\n * `--markup-escape` / `--no-markup-escape`\n * `--sanitize-unicode` / `--no-sanitize-unicode`\n * `--dedupe` / `--no-dedupe`\n\n\n## Changelog\n\nSee [CHANGELOG.md][changelog].\n\n\n## License\n\nThe [MIT License][license].\n\n\n[screenshot]: https://tinystash.undef.im/il/3wQUgnuCRyADYHZ4Vi6qN29p65njk1DdsjUu5WePUBNmUak7Z9y6CqNRnEzMN2pVBVsZvBDJ9GDyJUGGYd3Fgbqd.png\n[screencast]: https://tinystash.undef.im/il/2Xscwkh3rAhw2iqSr9XxJ2Meph57eXiHwkkWiAgroiuGPXB9fYnPJqgdYR7nR4B9U5hHvxxGtr8Sc3QaquwjHT38.mp4\n[license]: https://github.com/un-def/i3blocks-mpris/blob/master/LICENSE\n[changelog]: https://github.com/un-def/i3blocks-mpris/blob/master/CHANGELOG.md\n[i3blocks]: https://github.com/vivien/i3blocks\n[i3blocks-1.5]: https://github.com/vivien/i3blocks/releases/tag/1.5\n[dbus-python]: https://dbus.freedesktop.org/doc/dbus-python/\n[pygobject]: https://pygobject.readthedocs.io/en/latest/\n[font-awesome]: https://fontawesome.com/\n[pipx]: https://pipxproject.github.io/pipx/\n[mpris-spec]: https://specifications.freedesktop.org/mpris-spec/latest/\n[mpris-playbackstatus-type]: https://specifications.freedesktop.org/mpris-spec/latest/Player_Interface.html#Enum:Playback_Status\n[mpris-methods]: https://specifications.freedesktop.org/mpris-spec/latest/Player_Interface.html#methods\n[sanitize-unicode-issue]: https://github.com/un-def/i3blocks-mpris/issues/9\n[sanitize-unicode-categories]: https://en.wikipedia.org/wiki/Unicode_character_property#General_Category\n[python-docs-str-upper]: https://docs.python.org/3/library/stdtypes.html#str.upper\n[python-docs-str-lower]: https://docs.python.org/3/library/stdtypes.html#str.lower\n[python-docs-str-capitalize]: https://docs.python.org/3/library/stdtypes.html#str.capitalize\n[python-docs-str-title]: https://docs.python.org/3/library/stdtypes.html#str.title\n[python-docs-str-format-examples]: https://docs.python.org/3.8/library/string.html#format-examples\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A persistent i3blocks blocklet for the MPRIS D-Bus interface",
"version": "2.2.0",
"project_urls": {
"Changelog": "https://github.com/un-def/i3blocks-mpris/blob/master/CHANGELOG.md",
"Homepage": "https://github.com/un-def/i3blocks-mpris",
"Issues": "https://github.com/un-def/i3blocks-mpris/issues",
"Repository": "https://github.com/un-def/i3blocks-mpris.git"
},
"split_keywords": [
"i3blocks",
" blocklet"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "487abee775125a6f89983b6c8554bc2e5ebacf675dff1f95855e10ed85195364",
"md5": "b363da996b384b1f3f885786b59a2e55",
"sha256": "ed42bd28e8554286330d8cb4d590622752468d4dde04eb2fcb9b75cc2728a500"
},
"downloads": -1,
"filename": "i3blocks_mpris-2.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b363da996b384b1f3f885786b59a2e55",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10862,
"upload_time": "2024-09-08T08:55:53",
"upload_time_iso_8601": "2024-09-08T08:55:53.397316Z",
"url": "https://files.pythonhosted.org/packages/48/7a/bee775125a6f89983b6c8554bc2e5ebacf675dff1f95855e10ed85195364/i3blocks_mpris-2.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8d4757de0b44695d3f98c7e6169ecd49012bcb582130bef8f17c77a349702633",
"md5": "3f18cbf76e3df814060199e99a1cad6c",
"sha256": "5b03cb6320a2d4c20191df3b6a996e537a908cf051311b7f9676d23a12a2fecd"
},
"downloads": -1,
"filename": "i3blocks_mpris-2.2.0.tar.gz",
"has_sig": false,
"md5_digest": "3f18cbf76e3df814060199e99a1cad6c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10594,
"upload_time": "2024-09-08T08:55:55",
"upload_time_iso_8601": "2024-09-08T08:55:55.436307Z",
"url": "https://files.pythonhosted.org/packages/8d/47/57de0b44695d3f98c7e6169ecd49012bcb582130bef8f17c77a349702633/i3blocks_mpris-2.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-08 08:55:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "un-def",
"github_project": "i3blocks-mpris",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "i3blocks-mpris"
}
