# ▶️ Add MPRIS integration to media players
`mpris_server` provides adapters to integrate [MPRIS](https://specifications.freedesktop.org/mpris-spec/2.2/) support in
your media player or device. By supporting MPRIS in your app, you will allow Linux users to control all aspects of
playback from the media controllers they already have installed.
Whereas [existing MPRIS libraries for Python](https://github.com/hugosenari/mpris2) implement clients for apps with
existing MPRIS support, `mpris_server` is a library used to implement MPRIS support in apps that don't already have it.
If you want to give your media player an MPRIS interface, then `mpris_server` is right for you.
Check out [`📺 cast_control`](https://github.com/alexdelorenzo/cast_control) for an app that uses `mpris_server`.
`mpris_server` is a fork of [Mopidy-MPRIS](https://github.com/mopidy/mopidy-mpris) that was extended and made into a
general purpose library.
## Features
Implements the following from the [MPRIS specification](https://specifications.freedesktop.org/mpris-spec/2.2/):
* [x] MediaPlayer2
* [x] MediaPlayer2.Player
* [x] MediaPlayer2.Playlist
* [x] MediaPlayer2.TrackList
The library also provides an event handler that emits `org.freedesktop.DBus.Properties.PropertiesChanged` in response to
changes in your media player. This allows for real-time updates from your media player to D-Bus.
## Installation
### Requirements
- Linux / *BSD / [macOS](https://github.com/zbentley/dbus-osx-examples)
- [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/)
- Python >= 3.7
- [PyGObject](https://pypi.org/project/PyGObject/)
- `requirements.txt`
#### Installing PyGObject
On Debian-derived distributions like Ubuntu, install `python3-gi` with `apt`. On Arch, you'll want to
install `python-gobject`.
On macOS, install [`pygobject3`](https://formulae.brew.sh/formula/pygobject3) via `brew`. Note that `mpris_server` on
macOS hasn't been tested, but is theoretically possible to use.
Use `pip` to install `PyGObject>=3.34.0` if there are no installation candidates available in your vendor's package
repositories.
### PyPI
`pip3 install mpris_server`
### GitHub
Clone the repo, run `pip3 install -r requirements.txt`, followed by `python3 setup.py install`.
## Usage
### Implement `adapters.MprisAdapter`
Subclass `adapters.MprisAdapter` and implement each method.
After subclassing, pass an instance to an instance of `server.Server`.
### Implement `events.EventAdapter`
Subclass `adapters.EventAdapter`. This interface has a good default implementation, only override its methods if your
app calls for it.
If you choose to re-implement its methods, call `emit_changes()` with the corresponding interface and a `List[str]`
of [properties](https://specifications.freedesktop.org/mpris-spec/2.2/Player_Interface.html) that changed.
Integrate the adapter with your application to emit changes in your media player that DBus needs to know about. For
example, if the user pauses the media player, be sure to call `EventAdapter.on_playpause()` in the app. DBus won't know
about the change otherwise.
### Create the Server and Publish
Create an instance of `server.Server`, pass it an instance of your `MprisAdapter`, and call `publish()` to publish your
media player via DBus.
```python3
mpris = Server('MyMediaPlayer', adapter=my_adapter)
mpris.publish()
```
Call `loop()` to enter the DBus event loop, or enter the DBus event loop elsewhere in your code.
```python3
mpris.loop()
```
Or:
```python3
from gi.repository import GLib
loop = GLib.MainLoop()
loop.run()
```
### Example
```python3
from mpris_server.adapters import MprisAdapter
from mpris_server.events import EventAdapter
from mpris_server.server import Server
from mpris_server import Metadata
from my_app import app # custom app you want to integrate
class MyAppAdapter(MprisAdapter):
# Make sure to implement all methods on MprisAdapter, not just metadata()
def metadata(self) -> Metadata:
...
# and so on
class MyAppEventHandler(EventAdapter):
# EventAdapter has good default implementations for its methods.
# Only override the default methods if it suits your app.
def on_app_event(self, event: str):
# trigger DBus updates based on events in your app
if event == 'pause':
self.on_playpause()
...
# and so on
# create mpris adapter and initialize mpris server
my_adapter = MyAppAdapter()
mpris = Server('MyApp', adapter=my_adapter)
# initialize app integration with mpris
event_handler = MyAppEventHandler(root=mpris.root, player=mpris.player)
app.register_event_handler(event_handler)
# publish and serve
mpris.loop()
```
## Support
Want to support this project and [other open-source projects](https://github.com/alexdelorenzo) like it?
<a href="https://www.buymeacoffee.com/alexdelorenzo" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-blue.png" alt="Buy Me A Coffee" height="60px" style="height: 60px !important;width: 217px !important;max-width:25%" ></a>
## License
`mpris_server` is released under the AGPLv3, see [`LICENSE`](/LICENSE). Message me if you'd like to use this project
with a different license.
Raw data
{
"_id": null,
"home_page": "https://github.com/alexdelorenzo/mpris_server",
"name": "mpris-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": null,
"author": "Alex DeLorenzo <alex@alexdelorenzo.dev>",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/82/f1/9397b8b697b7bb15f848dc9fd68cefa663a85e95f4a0c028fcb65e5e107a/mpris_server-0.9.6.tar.gz",
"platform": null,
"description": "# \u25b6\ufe0f Add MPRIS integration to media players\n\n`mpris_server` provides adapters to integrate [MPRIS](https://specifications.freedesktop.org/mpris-spec/2.2/) support in\nyour media player or device. By supporting MPRIS in your app, you will allow Linux users to control all aspects of\nplayback from the media controllers they already have installed.\n\nWhereas [existing MPRIS libraries for Python](https://github.com/hugosenari/mpris2) implement clients for apps with\nexisting MPRIS support, `mpris_server` is a library used to implement MPRIS support in apps that don't already have it.\nIf you want to give your media player an MPRIS interface, then `mpris_server` is right for you.\n\nCheck out [`\ud83d\udcfa cast_control`](https://github.com/alexdelorenzo/cast_control) for an app that uses `mpris_server`.\n\n`mpris_server` is a fork of [Mopidy-MPRIS](https://github.com/mopidy/mopidy-mpris) that was extended and made into a\ngeneral purpose library.\n\n## Features\n\nImplements the following from the [MPRIS specification](https://specifications.freedesktop.org/mpris-spec/2.2/):\n\n* [x] MediaPlayer2\n* [x] MediaPlayer2.Player\n* [x] MediaPlayer2.Playlist\n* [x] MediaPlayer2.TrackList\n\nThe library also provides an event handler that emits `org.freedesktop.DBus.Properties.PropertiesChanged` in response to\nchanges in your media player. This allows for real-time updates from your media player to D-Bus.\n\n## Installation\n\n### Requirements\n\n- Linux / *BSD / [macOS](https://github.com/zbentley/dbus-osx-examples)\n- [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/)\n- Python >= 3.7\n- [PyGObject](https://pypi.org/project/PyGObject/)\n- `requirements.txt`\n\n#### Installing PyGObject\n\nOn Debian-derived distributions like Ubuntu, install `python3-gi` with `apt`. On Arch, you'll want to\ninstall `python-gobject`.\n\nOn macOS, install [`pygobject3`](https://formulae.brew.sh/formula/pygobject3) via `brew`. Note that `mpris_server` on\nmacOS hasn't been tested, but is theoretically possible to use.\n\nUse `pip` to install `PyGObject>=3.34.0` if there are no installation candidates available in your vendor's package\nrepositories.\n\n### PyPI\n\n`pip3 install mpris_server`\n\n### GitHub\n\nClone the repo, run `pip3 install -r requirements.txt`, followed by `python3 setup.py install`.\n\n## Usage\n\n### Implement `adapters.MprisAdapter`\n\nSubclass `adapters.MprisAdapter` and implement each method.\n\nAfter subclassing, pass an instance to an instance of `server.Server`.\n\n### Implement `events.EventAdapter`\n\nSubclass `adapters.EventAdapter`. This interface has a good default implementation, only override its methods if your\napp calls for it.\n\nIf you choose to re-implement its methods, call `emit_changes()` with the corresponding interface and a `List[str]`\nof [properties](https://specifications.freedesktop.org/mpris-spec/2.2/Player_Interface.html) that changed.\n\nIntegrate the adapter with your application to emit changes in your media player that DBus needs to know about. For\nexample, if the user pauses the media player, be sure to call `EventAdapter.on_playpause()` in the app. DBus won't know\nabout the change otherwise.\n\n### Create the Server and Publish\n\nCreate an instance of `server.Server`, pass it an instance of your `MprisAdapter`, and call `publish()` to publish your\nmedia player via DBus.\n\n```python3\nmpris = Server('MyMediaPlayer', adapter=my_adapter)\nmpris.publish() \n```\n\nCall `loop()` to enter the DBus event loop, or enter the DBus event loop elsewhere in your code.\n\n```python3\nmpris.loop() \n```\n\nOr:\n\n```python3\nfrom gi.repository import GLib\n\n\nloop = GLib.MainLoop()\nloop.run()\n```\n\n### Example\n\n```python3\nfrom mpris_server.adapters import MprisAdapter\nfrom mpris_server.events import EventAdapter\nfrom mpris_server.server import Server\nfrom mpris_server import Metadata\n\nfrom my_app import app # custom app you want to integrate\n\n\nclass MyAppAdapter(MprisAdapter):\n # Make sure to implement all methods on MprisAdapter, not just metadata()\n def metadata(self) -> Metadata:\n ...\n # and so on\n\n\nclass MyAppEventHandler(EventAdapter):\n # EventAdapter has good default implementations for its methods.\n # Only override the default methods if it suits your app.\n\n def on_app_event(self, event: str):\n # trigger DBus updates based on events in your app\n if event == 'pause':\n self.on_playpause()\n ...\n # and so on\n\n\n# create mpris adapter and initialize mpris server\nmy_adapter = MyAppAdapter()\nmpris = Server('MyApp', adapter=my_adapter)\n\n# initialize app integration with mpris\nevent_handler = MyAppEventHandler(root=mpris.root, player=mpris.player)\napp.register_event_handler(event_handler)\n\n# publish and serve\nmpris.loop()\n```\n\n## Support\n\nWant to support this project and [other open-source projects](https://github.com/alexdelorenzo) like it?\n\n<a href=\"https://www.buymeacoffee.com/alexdelorenzo\" target=\"_blank\"><img src=\"https://cdn.buymeacoffee.com/buttons/v2/default-blue.png\" alt=\"Buy Me A Coffee\" height=\"60px\" style=\"height: 60px !important;width: 217px !important;max-width:25%\" ></a>\n\n## License\n\n`mpris_server` is released under the AGPLv3, see [`LICENSE`](/LICENSE). Message me if you'd like to use this project\nwith a different license.\n",
"bugtrack_url": null,
"license": "License :: OSI Approved :: LGPL-3.0-only",
"summary": "\u23ef\ufe0f Publish a MediaPlayer2 MPRIS device to D-Bus.",
"version": "0.9.6",
"project_urls": {
"Homepage": "https://github.com/alexdelorenzo/mpris_server"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ab7915590e73b935eb1a1bbc6adb5e2a3165d522b84b29d6c9b8ad74f56bf521",
"md5": "ea13eaa19c8a9d860f060535f3c476b8",
"sha256": "13e8ffaa3b6b907c743b6ba76e9a3dfe4c2274e0a8c99ca03f66d6073c39a7fe"
},
"downloads": -1,
"filename": "mpris_server-0.9.6-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "ea13eaa19c8a9d860f060535f3c476b8",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.12",
"size": 26529,
"upload_time": "2024-09-02T11:06:12",
"upload_time_iso_8601": "2024-09-02T11:06:12.874677Z",
"url": "https://files.pythonhosted.org/packages/ab/79/15590e73b935eb1a1bbc6adb5e2a3165d522b84b29d6c9b8ad74f56bf521/mpris_server-0.9.6-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "82f19397b8b697b7bb15f848dc9fd68cefa663a85e95f4a0c028fcb65e5e107a",
"md5": "0714e9dab35be27729797fd3b885c9d1",
"sha256": "4f465e0d089820084a47c6b0de2bf7aedc3373e4743d342e221ebe1e2e2b2074"
},
"downloads": -1,
"filename": "mpris_server-0.9.6.tar.gz",
"has_sig": false,
"md5_digest": "0714e9dab35be27729797fd3b885c9d1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 27722,
"upload_time": "2024-09-02T11:06:14",
"upload_time_iso_8601": "2024-09-02T11:06:14.514523Z",
"url": "https://files.pythonhosted.org/packages/82/f1/9397b8b697b7bb15f848dc9fd68cefa663a85e95f4a0c028fcb65e5e107a/mpris_server-0.9.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-02 11:06:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alexdelorenzo",
"github_project": "mpris_server",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "mpris-server"
}
JSON
