{"id":17136975,"url":"https://github.com/un-def/i3blocks-mpris","last_synced_at":"2025-04-13T09:25:14.844Z","repository":{"id":62570075,"uuid":"124402755","full_name":"un-def/i3blocks-mpris","owner":"un-def","description":"A persistent i3blocks blocklet for the MPRIS D-Bus interface (f.k.a. i3blocks-spotify-persist)","archived":false,"fork":false,"pushed_at":"2024-09-08T09:00:23.000Z","size":80,"stargazers_count":16,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-27T01:02:29.149Z","etag":null,"topics":["blocklet","i3blocks","i3blocks-spotify-persist","mpris","spotify"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/un-def.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"ko_fi":"un1def"}},"created_at":"2018-03-08T14:25:40.000Z","updated_at":"2024-09-08T09:00:26.000Z","dependencies_parsed_at":"2024-04-05T13:58:56.212Z","dependency_job_id":null,"html_url":"https://github.com/un-def/i3blocks-mpris","commit_stats":{"total_commits":31,"total_committers":2,"mean_commits":15.5,"dds":"0.032258064516129004","last_synced_commit":"1d5d2bdb42993c3520ce2a48971141e1e0c2fd37"},"previous_names":["un-def/i3blocks-spotify-persist"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/un-def%2Fi3blocks-mpris","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/un-def%2Fi3blocks-mpris/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/un-def%2Fi3blocks-mpris/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/un-def%2Fi3blocks-mpris/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/un-def","download_url":"https://codeload.github.com/un-def/i3blocks-mpris/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248689974,"owners_count":21146039,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blocklet","i3blocks","i3blocks-spotify-persist","mpris","spotify"],"created_at":"2024-10-14T20:05:54.286Z","updated_at":"2025-04-13T09:25:14.814Z","avatar_url":"https://github.com/un-def.png","language":"Python","funding_links":["https://ko-fi.com/un1def"],"categories":[],"sub_categories":[],"readme":"# 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 — `org.mpris.MediaPlayer2.\u003cplayer\u003e[.\u003cinstance\u003e]` — or its `\u003cplayer\u003e[.\u003cinstance\u003e]` 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} – {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]                                        | “lorem Ipsum DOLor” → “LOREM IPSUM DOLOR” |\n| `lower`      | [`str.lower`][python-docs-str-lower]                                        | “lorem Ipsum DOLor” → “lorem ipsum dolor” |\n| `capitalize` | [`str.capitalize`][python-docs-str-capitalize]                              | “lorem Ipsum DOLor” → “Lorem ipsum dolor” |\n| `title`      | [`str.title`][python-docs-str-title]                                        | “lorem Ipsum DOLor” → “Lorem Ipsum Dolor” |\n| `icon`       | converts a textual `status` to an icon, see the `status_icons` option below | “Paused” → “⏸”                           |\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 `.\u003cmax_length\u003e,\u003csuffix\u003e` 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:…\u003c10.9}`                 | `Toooooooo…`                           |\n| `Godzilla` / `Golderia`                | `{artist: ^10} - {title: ^10.4}`  | ` Godzilla  -    Gold   `              |\n| `Apparatus Superiority` / `Player Two` | `{artist:…\u003c16.15} - {title:\u003e15}`  | `Apparatus Super… -      Player Two`   |\n| `In Fire` / `Lan Connected`            | `{artist:.10,…} - {title:.10,…}`  | `In Fire - Lan Connec…`                |\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 `\u003c`, `\u003e`, `\u0026`) 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\": \"\u003cspan font_family='monospace' color='#ffa651' weight='bold'\u003e{status:icon} {status:upper}\u003c/span\u003e \u003cspan color='#72bf44' weight='bold'\u003e{artist}\u003c/span\u003e\u003cspan color='#ffa651'\u003e᛫\u003c/span\u003e\u003cspan color='#b2d235'\u003e{title}\u003c/span\u003e\",\n    \"markup_escape\": true,\n    \"status_icons\": {\n        \"Playing\": \"|\u003e\",\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` — show all command line arguments and exit\n  * `-c`, `--config` — 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fun-def%2Fi3blocks-mpris","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fun-def%2Fi3blocks-mpris","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fun-def%2Fi3blocks-mpris/lists"}