init

2026-08-11 10:55:02 +02:00
commit d1a98c5da2
17 changed files with 2033 additions and 0 deletions
@@ -0,0 +1,88 @@
+# syncplay
+
+`syncplay` is a small Odin program that relays play, pause, and seek actions
+between a few trusted mpv users. One executable provides both the TCP relay
+server and the macOS client.
+
+## Requirements
+
+- Odin 2026-07 or newer
+- macOS for client mode
+- macOS or Linux for server mode
+- mpv installed on every client
+- The same media file (including the same cut) on every client
+
+## Build and test
+
+```sh
+odin check .
+odin test .
+odin build . -out:syncplay
+```
+
+## Run
+
+Start one relay server:
+
+```sh
+./syncplay server --host 0.0.0.0 --port 9000
+```
+
+Then each viewer starts a client with their local copy of the movie:
+
+```sh
+./syncplay client \
+  --host server.example.test \
+  --port 9000 \
+  /path/to/movie.mkv
+```
+
+The macOS defaults can be overridden:
+
+```sh
+./syncplay client \
+  --host server.example.test \
+  --port 9000 \
+  --mpv /custom/path/to/mpv \
+  --socket /tmp/custom-mpv-socket \
+  /path/to/movie.mkv
+```
+
+The client starts at `00:00:00` in the paused state. Closing mpv closes the
+client. Interrupting the client terminates the mpv process it launched. If the
+server connection is lost after startup, mpv continues normally and the client
+logs that synchronization has stopped.
+
+## Protocol
+
+The trusted-network protocol is newline-delimited JSON over TCP:
+
+```json
+{"version":1,"type":"welcome","client_id":1}
+{"version":1,"type":"pause","paused":true}
+{"version":1,"type":"pause","paused":false}
+{"version":1,"type":"seek","position":3723.125}
+```
+
+Messages are limited to 4096 bytes. The server validates and re-encodes every
+message, preserves processing order, and broadcasts it to every connection
+except its sender. It assigns each connection a numeric client ID and adds the
+triggering ID to relayed events. Server and client terminals log play, pause,
+and seek actions with that ID; the triggering client is marked with `(you)` in
+its own terminal.
+
+Remote seeks are applied using an acknowledged mpv IPC transaction: seek event
+delivery is disabled for this IPC connection, an exact absolute seek is sent,
+and event delivery is restored even if the seek fails. This prevents a remote
+seek from being mistaken for a new local seek and sent back indefinitely.
+
+## Prototype limitations
+
+- One global session; no rooms or late-join state snapshot
+- No authentication, encryption, or Internet-facing security
+- No automatic reconnection
+- No media identity checking
+- No clock synchronization or drift correction
+- mpv can report internally generated operations as seek events
+- A local seek made during the brief remote-seek suppression transaction may
+  not be relayed because mpv events do not identify their origin