This project allows you to remotely control some multimedia functionalities of your desktop/laptop, through the MQTT protocol.
You will be able to control the volume, mute/unmute, play/pause and skip forward/backward your content (Netflix, Prime Video, Disney+, Spotify and many more) comfortably from your sofa.
To be clear, this is just a client that exposes some of your pc's functionalities via MQTT, you will still need a remote control or something similar to send the commands. I myself integrated it with Home Assistant and use it with a Osram Smart+ Mini Switch.
At this point you may be wondering "Why not buy a PC remote control directly?". Well, you might be right but consider this:
- many of them suck with Linux
- have way more functionalities than you might need, and the ones you need may not work well
- they are not as customizable
- last but not least, it's not as fun as building a custom remote control! 🤓
There are three main parties involved:
- a device compatible with MQTT able to send commands (e.g. a remote control)
- your pc, in which this project runs (from now on aka the client)
- an MQTT broker, used to connect the two
The broker, which might be running either locally on your pc or somewhere else, handles two topics: a control topic and a status topic. The MQTT compatible remote control sends commands to the control topic, these are received by the client that is subscribed to it, executed, and the results are sent back to the broker via the status topic, which can be subsequently consumed.
This is clearly a simplification of the overall functioning of the system. In a real case scenario it is very unlikely that a remote control will be able to send commands directly to an MQTT broker.
In my case, I use a Zigbee remote integrated with Home Assistant. Home Assistant based on the button pressed, publish a message to the control topic. This is received by the client, executed, and the result is sent back to the status topic, where Home Assistant consumes it and keeps a status dashboard up-to-date.
- Clone the repository
- Create and activate a virtual environment (optional)
- Install the project dependencies:
make install
This project requires pyalsaaudio, and you might need to install some dependencies on you OS before to install it. Check out the doc. On Debian (and Ubuntu), install libasound2-dev.
- Set up the project configuration parameters:
Name | Type | Optional | Default | Examples | Description |
---|---|---|---|---|---|
MQTT_BROKER_ADDR | str | No | '127.0.0.1' | The MQTT Broker address | |
MQTT_BROKER_PORT | str, int | No | '1883' 1883 |
The MQTT Broker port | |
MQTT_BROKER_USER | str | Yes | None | 'user' | The MQTT Broker user, if broker requires auth |
MQTT_BROKER_PWD | str | Yes | None | 'password' | The MQTT Broker password, if broker requires auth |
MQTT_CONTROL_TOPIC | str | No | 'desktop/control' | The MQTT control topic, used to receive commands | |
MQTT_STATUS_TOPIC | str | No | 'desktop/status' | The MQTT status topic, used to send status updates | |
VOLUME_STEP | int | Yes | 10 | 20 | How much to increase / decrease the volume (%) |
STATUS_UPDATE_DELAY | int | Yes | None | 30 | How much seconds between automatic status updates |
DEBUG | bool | Yes | False | True False |
Whether to activate debug mode or not |
You can set the mandatory configuration parameters by either creating an .env
file in the
project's root directory:
MQTT_BROKER_ADDR='127.0.0.1'
MQTT_BROKER_PORT='1883'
MQTT_BROKER_USER='mqtt_user'
MQTT_BROKER_PWD='mqtt_password'
MQTT_CONTROL_TOPIC='desktop/control'
MQTT_STATUS_TOPIC='desktop/status'
or by manually configuring the module config.py.
Inside the project's root directory:
make install
Install the project dependencies.
make test
Run tests.
make docker
Run a Docker Mosquitto
instance, binding port 1883:1883
.
make run
Run the project and start the MQTT client.
make doc
Generate the project documentation.
make show-doc
Start a pdoc server on http://localhost:8080
to browse the documentation.
Below are examples of commands you can publish to MQTT_CONTROL_TOPIC
,
in JSON format:
{"volume": 100}
Sets the volume to 100%.
{"volumeCtrl": "+"}
{"volumeCtrl": "-"}
Increases and decreases the volume by VOLUME_STEP
.
{"mute": true}
{"mute": false}
Mute and unmute.
{"toggle": "mute"}
{"toggle": "pause"}
Toggle mute/unmute and play/pause.
{"ctrl": ">>"}
{"ctrl": "<<"}
Skip forward/backward.
Toggle play/pause and skip forward/backward requires the focus to be on the target window. These commands work by taking advantage of the platform's keyboard shortcuts:
Space bar
play/pauseArrow right/left
skip forward/backward
Make sure the application you want to control supports these shortcuts!