Update README with instructions on how to setup a secure remote connection to your mpv instance

README.md

@@ -32,29 +32,53 @@ Restart Home Assistant and enjoy!
 
 #### Remote mpv
 
-It is also possible to connect to a remove mpv instance over the network. First, ensure that `socat` is installed, and
-create a script that runs socat to expose the mpv socket on a network port (2352 in the following example). It is
-important that this script has the extension `.run`, and is executable (run `chmod +x socat.run`):
+It is also possible to connect to a remote mpv instance over the network. For security reasons, it's strongly recommended to use SSH tunneling to create an encrypted connection rather than exposing the socket directly over the network. Directly exposing the mpv control socket is a security risk, as it would allow anybody with access to the port to execute arbitrary commands via mpv's `run` command.
+
+First, ensure that `socat` is installed, and create a script that:
+1. Uses socat to bridge the mpv Unix socket to a localhost-only port on your machine
+2. Creates an SSH reverse tunnel to securely forward that port to your Home Assistant server
+
+The script must have the `.run` extension and be executable (run `chmod +x secure-mpv-tunnel.run`):
 ```sh
-#!/bin/sh
-exec socat TCP-LISTEN:2352,fork UNIX-CONNECT:/path/to/mpv-socket
+#!/bin/bash
+# Replace these values with your actual settings
+MPV_SOCKET="/path/to/mpv-socket"
+LOCAL_PORT="2352"
+HA_HOST="homeassistant.local"  # Your Home Assistant machine
+HA_USER="user"                 # SSH user on your Home Assistant machine
+
+# Exit if port already in use (script likely already running)
+if nc -z 127.0.0.1 ${LOCAL_PORT} 2>/dev/null; then
+  echo "Port ${LOCAL_PORT} already in use, assuming secure-mpv-tunnel script is already running"
+  exit 0
+fi
+
+# Create localhost-only TCP listener that connects to mpv socket
+socat TCP-LISTEN:${LOCAL_PORT},bind=127.0.0.1,reuseaddr,fork UNIX-CONNECT:${MPV_SOCKET} &
+
+# Create secure SSH tunnel
+ssh -N -R ${LOCAL_PORT}:localhost:${LOCAL_PORT} ${HA_USER}@${HA_HOST}
 ```
 
-Start mpv with using the `--script` option to have it run the script on startup:
+> **Note:** This method requires SSH access to your Home Assistant instance. If using the popular [Home Assistant SSH addon](https://github.com/hassio-addons/addon-ssh), you'll need to enable `allow_remote_port_forwarding: true` in its configuration for the reverse tunnel to work.
+
+Start mpv with the `--script` option to run the script on startup:
 ```sh
-mpv --input-ipc-server=/path/to/mpv-socket --script=/path/to/socat.run
+mpv --input-ipc-server=/path/to/mpv-socket --script=/path/to/secure-mpv-tunnel.run
 ```
 
-Finaly, configure the integration to connect over the network:
+Finally, configure the integration to connect to the local end of the tunnel:
 ```yaml
 media_player:
   - platform: mpv
     name: "MPV Player"
     server:
-      host: 192.168.1.100
+      host: localhost
       port: 2352
 ```
 
+This approach ensures all communication between Home Assistant and mpv is encrypted through SSH, preventing unauthorized access to your mpv instance.
+
 #### Other useful mpv options
 
 You can additionally use the `--idle` mpv option to have it remain alive if no media is playing.