sync-mpv/README.md

# sync-mpv
`sync-mpv` synchronizes video playback between `mpv` clients running
on multiple computers.

Rationale: If multiple computers are playing the same stream at the same time,
and are not synchronized, the audio will sound like an echo (or worse).

Use case: Live streaming OBS Studio output to multiple computers across a LAN.

# Install
Install thusly.

Using Debian Stable (12/Bookworm).

Install thine dependencies:
```
sudo apt update
sudo apt install git mpv python3-pip python3-virtualenv
```

Clone repo:
```
git clone https://spacecruft.org/deepcrayon/sync-mpv
cd sync-mpv/
```

Set up Python to taste, such as:
```
virtualenv env
source env/bin/activate
pip install --upgrade pip setuptools wheel
```

Install Python dependencies:
```
pip install -r requirements.txt
```


# Usage
## Server
Run the server on a machine all the clients can reach.
This can be the same server that hosts the video stream,
or a completely different machine for any arbitrary URL.

```
$ ./sync_mpv_server.py -h
usage: sync_mpv_server.py [-h] [-i IP] [-p PORT] [-u URL]

mpv synchronization server

options:
  -h, --help            show this help message and exit
  -i IP, --ip IP        Server IP address (default 0.0.0.0)
  -p PORT, --port PORT  Server network port (default 51984)
  -u URL, --url URL     URL to play
```

On first run, it will prompt you for password, which will be saved for
future runs.
The server password is stored in *plaintext* here:
`~/.config/sync-mpv/serverpassword.conf`.


## Client
The client runs on the machine that will run `mpv`, which it spawns.

```
$ ./sync_mpv_client.py -h
usage: sync_mpv_client.py [-h] [-i IP] [-p PORT]

mpv synchronization client

options:
  -h, --help            show this help message and exit
  -i IP, --ip IP        Server IP address
  -p PORT, --port PORT  Server Port
```

It will prompt you for a IP address. Enter the IP address of the
server. By default it will connect on `TCP/51984`, which will need
to be open on the firewall that is surely running.
It will prompt for a username, which can be whatever.
It will prompt for a password, which is the main one set in the server.
This will all be stored in the configuration file
`~/.config/sync-mpv/sync-mpv.conf`
The password is stored in *plaintext*.


# Notes
There are two main scripts in the application.
One is the server, the other is the client.
The server runs on one machine.
The client runs on as many machines as you want, including the server.
The server listens on an IP address and port for TCP connections.
The server doesn't do any video processing, the load is near zero.
The server just coordinates connections and synchronization.
When a new client connects, the other clients may pause for a moment,
which sucks.
The server has the URL to play.
The client connects, gets the URL, starts playback and synchronization.
There are usernames and a single shared password.
The password is supposedly secure across the network with some
Python AES library, but I doubt it.
This thing actually appears to work, wow.


# Development
To "develop", install the requirements:

```
pip install -r requirements-dev.txt
```

Then run `black` on the Python files for nice formatting:

```
black *.py
```


# Upstream
## sync-mpv
This present repo is an updated fork of this repo:

* https://github.com/mdnghtman/sync-mpv

See `README-upstream.md` for upstream's README.

## mpv
* Ideally this would be in `mpv`, but they haven't implement it yet, afaict:
https://github.com/mpv-player/mpv/issues/1272

## mplayer
* "Older" `mplayer` has this ability with options like `-udp-master`, but it
doesn't support SRT and recent codecs.


# Similar Projects
There are many different similar projects, namely have two+ machines
play the same video at the same time. I tried many of them, but they
didn't work for my use case. For instance:

* The application was for file playback, not "realtime" streaming.
* Used for synchronization "far" across the Internet, so acceptable
delays are in the 1-5 second range. That is far too much latency,
it is ideally 20ms or below.
* Not maintained.
* Too much overhead (e.g. QT).
* Audio only. Something like JACK doing streaming video would be ideal.


# Copyright
Unofficial project, not related to mdnghtman or mpv.

Upstream sources under their respective copyrights.


# License
Apache 2.0.

*Copyright © 2023, Jeff Moe.*