# Linux desktop agent to allow MPRIS multimedia control from Home Assistant
This package contains the agent that Home Assistant connects to in order
to govern multimedia playback.
## What is this program for?
This program lets your computer's media players (compatible with the MPRIS
standard) be remotely controlled by any compatible client (most common being
[Home Assistant](https://home-assistant.io/)), when you are logged into your
computer's desktop session. Headless operation should also be supported
(although it is not regularly exercised) so long as the program runs in a
D-Bus session shared by other MPRIS-compatible media players as well.
A small graphical utility that lets you turn this program on or off is
shipped with this package as well.
## Supported media players
In general, all media players compliant with the MPRIS specification should
work to varying degrees of compatibility. That said, here is a list of
media players known to work, and their supported features:
* VLC
* Play / pause / stop.
* Playback rate change.
* Next / previous track.
* Seek.
* Support uses polling for seek position because VLC does not correctly
implement the `Seeked` D-Bus signals.
* Google Chrome / Chromium
* Play / pause / stop.
* Next / previous track.
* Seek.
* Totem (GNOME Videos)
* Play / pause / stop.
* Next / previous track.
* Seek.
* Support uses polling because Totem does not correctly implement the
`Seeked` or the `PropertiesChanged` D-Bus signals.
* Amarok
* Play / pause / stop.
* Next / previous track.
* Seek.
* Spotifyd
* Nothing works — it hangs when its MPRIS interface is queried.
* MPD
* Requires the [mpd-mpris](https://github.com/natsukagami/mpd-mpris) service
If you test another media player, report your test results (along with any
errors you find, and logs from this program) to the project's
[issue tracker](https://github.com/Rudd-O/hassmpris_agent/issues).
## Setup
The general process is:
1. Install GTK+ 4 and libnotify on your system.
2. Then install / upgrade this package. If upgrading,
log out then log back in after installation.
3. Finally, run the settings program to turn the agent on,
or (if upgrading) to verify that the agent is running.
See the options below for instructions on various systems.
### Install from PyPI
Ensure GTK+ 4 and libnotify are installed on your system by using your
system package manager.
Then use `pip install --user -U hassmpris_agent`. Find the
`hassmpris-settings` and `hassmpris-agent` programs in your
`~/.local/bin` directory.
*Never install anything using `pip` to your system Python
library directory. It can cause problems for you down the road.*
### Install as an RPM package
Pre-built packages for various Fedora releases are available at
https://repo.rudd-o.com/ . These take care of installing all the required
dependencies properly.
Find the `hassmpris-settings` and `hassmpris-agent` programs
in your system `$PATH` (generally `/usr/bin`).
### Run the agent
#### Within your graphical desktop session (as usual)
Run the program `hassmpris-settings` to start the settings program. If this
program is not readily available, run `python3 -m hassmpris_agent.settings`
instead.
A window will pop up, with a slider to turn the agent on. Slide the slider
to the *on* position to start the agent. From then on, the agent will auto
start every time you log in.
#### Manually (e.g. in a headless scenario)
Run the program `hassmpris-agent`. This program must be run **after**
the session has a successfully-executed D-Bus session daemon, otherwise
the D-Bus client within the program will attempt to auto-launch D-Bus
and this will not work without an X11 or Wayland graphical session.
The program should work without issue in a headless session, providing
remote access to any media players sharing the same D-Bus session with
the agent. If it does not, please file an issue in this project's
Github repository.
### Firewall rules
On the system running the agent, don't forget to open the requisite firewall
ports, to allow Home Assistant to connect to your agent:
* TCP port 40051
* TCP port 40052
### Pair with Home Assistant
Once the agent is running you can connect to your computer from Home Assistant.
Add the MPRIS integration in your Home Assistant instance, optionally
specifying the address of your machine where this agent is running. Then
follow the instructions onscreen in both your agent machine and your Home
Assistant interface to complete the pairing process.
## Troubleshooting and help
The [client utility available here](https://github.com/Rudd-O/hassmpris_client)
will help you debug issues by allowing you to connect to the agent from your
machine or another machine.
If the agent is giving you trouble or not working as it's meant to, you may want
to look at your system logs. E.g. if running the agent under your desktop
session, look at the log files for the session using `journalctl` or under the
file `~/.xsession-errors`. You should make a copy of any traceback of interest.
### Found a bug or a traceback?
Please report it in the [project's issue tracker](https://github.com/Rudd-O/hassmpris_agent/issues).
## Technical information
The MPRIS desktop agent is composed of two different servers:
* An authentication server (listening on TCP port 40052).
* An MPRIS gRPC server (listening on TCP port 40051).
### The authentication server
The authentication server doles out credentials for clients that
want to connect to the MPRIS gRPC server. It follows [the CAKES
scheme documented in that project](https://github.com/Rudd-O/cakes)
and implemented in the
[reference HASS MPRIS client](https://github.com/Rudd-O/hassmpris-client).
### The MPRIS gRPC server
The MPRIS gRPC server provides an event-based interface to properly-
authenticated clients, relaying status information as it happens
to them via a bidirectional gRPC channel, and accepting commands
for the media players running locally via that gRPC channel.
This server implements a gRPC interface formalized in package
[hassmpris](https://github.com/Rudd-O/hassmpris)
([direct link to protobuf](https://github.com/Rudd-O/hassmpris/blob/master/src/hassmpris/proto/mpris.proto)).
The protobuf interface documents what commands and properties are
supported at any point in time, and the README.md file of that project
contains useful information as well.
### Interface between gRPC and desktop media players in the agent
Bound to the gRPC server is a D-Bus interface listener that monitors
media players and relays that information back to the gRPC server
for broadcast to remote clients, as well as accepting command requests
from the gRPC client and effecting those commands onto the media
players of the system where this program runs.
In addition to providing a command and event interface for MPRIS
media players, the D-Bus interface listener also provides façades
for certain media players that are not necessarily fully compliant
with the MPRIS specification.
Raw data
{
"_id": null,
"home_page": "https://github.com/Rudd-O/hassmpris",
"name": "hassmpris-agent",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Manuel Amador (Rudd-O)",
"author_email": "rudd-o@rudd-o.com",
"download_url": "https://files.pythonhosted.org/packages/c0/0f/84cfb67a4550b9ec0c44ec93f8b1e465ecfcba3e3219b13b0839d9b8ed42/hassmpris_agent-0.0.40.tar.gz",
"platform": null,
"description": "# Linux desktop agent to allow MPRIS multimedia control from Home Assistant\n\nThis package contains the agent that Home Assistant connects to in order\nto govern multimedia playback.\n\n## What is this program for?\n\nThis program lets your computer's media players (compatible with the MPRIS\nstandard) be remotely controlled by any compatible client (most common being\n[Home Assistant](https://home-assistant.io/)), when you are logged into your\ncomputer's desktop session. Headless operation should also be supported\n(although it is not regularly exercised) so long as the program runs in a\nD-Bus session shared by other MPRIS-compatible media players as well.\n\nA small graphical utility that lets you turn this program on or off is\nshipped with this package as well.\n\n## Supported media players\n\nIn general, all media players compliant with the MPRIS specification should\nwork to varying degrees of compatibility. That said, here is a list of\nmedia players known to work, and their supported features:\n\n* VLC\n * Play / pause / stop.\n * Playback rate change.\n * Next / previous track.\n * Seek.\n * Support uses polling for seek position because VLC does not correctly\n implement the `Seeked` D-Bus signals.\n* Google Chrome / Chromium\n * Play / pause / stop.\n * Next / previous track.\n * Seek.\n* Totem (GNOME Videos)\n * Play / pause / stop.\n * Next / previous track.\n * Seek.\n * Support uses polling because Totem does not correctly implement the\n `Seeked` or the `PropertiesChanged` D-Bus signals.\n* Amarok\n * Play / pause / stop.\n * Next / previous track.\n * Seek.\n* Spotifyd\n * Nothing works \u2014 it hangs when its MPRIS interface is queried.\n* MPD\n * Requires the [mpd-mpris](https://github.com/natsukagami/mpd-mpris) service\n\nIf you test another media player, report your test results (along with any\nerrors you find, and logs from this program) to the project's\n[issue tracker](https://github.com/Rudd-O/hassmpris_agent/issues).\n\n## Setup\n\nThe general process is:\n\n1. Install GTK+ 4 and libnotify on your system.\n2. Then install / upgrade this package. If upgrading,\n log out then log back in after installation.\n3. Finally, run the settings program to turn the agent on,\n or (if upgrading) to verify that the agent is running.\n\nSee the options below for instructions on various systems.\n\n### Install from PyPI\n\nEnsure GTK+ 4 and libnotify are installed on your system by using your\nsystem package manager.\n\nThen use `pip install --user -U hassmpris_agent`. Find the\n`hassmpris-settings` and `hassmpris-agent` programs in your\n`~/.local/bin` directory.\n\n*Never install anything using `pip` to your system Python\nlibrary directory. It can cause problems for you down the road.*\n\n### Install as an RPM package\n\nPre-built packages for various Fedora releases are available at\nhttps://repo.rudd-o.com/ . These take care of installing all the required\ndependencies properly.\n\nFind the `hassmpris-settings` and `hassmpris-agent` programs\nin your system `$PATH` (generally `/usr/bin`).\n\n### Run the agent\n\n#### Within your graphical desktop session (as usual)\n\nRun the program `hassmpris-settings` to start the settings program. If this\nprogram is not readily available, run `python3 -m hassmpris_agent.settings`\ninstead.\n\nA window will pop up, with a slider to turn the agent on. Slide the slider\nto the *on* position to start the agent. From then on, the agent will auto\nstart every time you log in.\n\n#### Manually (e.g. in a headless scenario)\n\nRun the program `hassmpris-agent`. This program must be run **after**\nthe session has a successfully-executed D-Bus session daemon, otherwise\nthe D-Bus client within the program will attempt to auto-launch D-Bus\nand this will not work without an X11 or Wayland graphical session.\n\nThe program should work without issue in a headless session, providing\nremote access to any media players sharing the same D-Bus session with\nthe agent. If it does not, please file an issue in this project's\nGithub repository.\n\n### Firewall rules\n\nOn the system running the agent, don't forget to open the requisite firewall\nports, to allow Home Assistant to connect to your agent:\n\n* TCP port 40051\n* TCP port 40052\n\n### Pair with Home Assistant\n\nOnce the agent is running you can connect to your computer from Home Assistant.\nAdd the MPRIS integration in your Home Assistant instance, optionally\nspecifying the address of your machine where this agent is running. Then\nfollow the instructions onscreen in both your agent machine and your Home\nAssistant interface to complete the pairing process.\n\n## Troubleshooting and help\n\nThe [client utility available here](https://github.com/Rudd-O/hassmpris_client)\nwill help you debug issues by allowing you to connect to the agent from your\nmachine or another machine.\n\nIf the agent is giving you trouble or not working as it's meant to, you may want\nto look at your system logs. E.g. if running the agent under your desktop\nsession, look at the log files for the session using `journalctl` or under the\nfile `~/.xsession-errors`. You should make a copy of any traceback of interest.\n\n### Found a bug or a traceback?\n\nPlease report it in the [project's issue tracker](https://github.com/Rudd-O/hassmpris_agent/issues).\n\n## Technical information\n\nThe MPRIS desktop agent is composed of two different servers:\n\n* An authentication server (listening on TCP port 40052).\n* An MPRIS gRPC server (listening on TCP port 40051).\n\n### The authentication server\n\nThe authentication server doles out credentials for clients that\nwant to connect to the MPRIS gRPC server. It follows [the CAKES\nscheme documented in that project](https://github.com/Rudd-O/cakes)\nand implemented in the\n[reference HASS MPRIS client](https://github.com/Rudd-O/hassmpris-client).\n\n### The MPRIS gRPC server\n\nThe MPRIS gRPC server provides an event-based interface to properly-\nauthenticated clients, relaying status information as it happens\nto them via a bidirectional gRPC channel, and accepting commands\nfor the media players running locally via that gRPC channel.\n\nThis server implements a gRPC interface formalized in package\n[hassmpris](https://github.com/Rudd-O/hassmpris)\n([direct link to protobuf](https://github.com/Rudd-O/hassmpris/blob/master/src/hassmpris/proto/mpris.proto)).\nThe protobuf interface documents what commands and properties are\nsupported at any point in time, and the README.md file of that project\ncontains useful information as well.\n\n### Interface between gRPC and desktop media players in the agent\n\nBound to the gRPC server is a D-Bus interface listener that monitors\nmedia players and relays that information back to the gRPC server\nfor broadcast to remote clients, as well as accepting command requests\nfrom the gRPC client and effecting those commands onto the media\nplayers of the system where this program runs.\n\nIn addition to providing a command and event interface for MPRIS\nmedia players, the D-Bus interface listener also provides fa\u00e7ades\nfor certain media players that are not necessarily fully compliant\nwith the MPRIS specification.\n",
"bugtrack_url": null,
"license": null,
"summary": "Linux desktop agent to allow MPRIS multimedia control from Home Assistant",
"version": "0.0.40",
"project_urls": {
"Homepage": "https://github.com/Rudd-O/hassmpris"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c00f84cfb67a4550b9ec0c44ec93f8b1e465ecfcba3e3219b13b0839d9b8ed42",
"md5": "91664f6c3fee88bbc2eebdfc703db799",
"sha256": "186eac9613b964b78839c33e4d2d3b3197e48aefcc73fc134d5174d6ba9f38ba"
},
"downloads": -1,
"filename": "hassmpris_agent-0.0.40.tar.gz",
"has_sig": false,
"md5_digest": "91664f6c3fee88bbc2eebdfc703db799",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 31239,
"upload_time": "2024-10-08T15:02:39",
"upload_time_iso_8601": "2024-10-08T15:02:39.052206Z",
"url": "https://files.pythonhosted.org/packages/c0/0f/84cfb67a4550b9ec0c44ec93f8b1e465ecfcba3e3219b13b0839d9b8ed42/hassmpris_agent-0.0.40.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-08 15:02:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Rudd-O",
"github_project": "hassmpris",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "hassmpris-agent"
}
JSON
