sync_replay_project/README.md

watch-together

Watch a video with friends, in sync, with the quality of a real mpv player. Paste a Jellyfin link, any direct video link, or pick a file on your own disk; everyone's play, pause and seek stay together.

Why not Jellyfin SyncPlay: it runs in the browser and its sync is poor. This is a desktop app that drives mpv.

Name: watch-together is a placeholder and the final name is undecided (sync-relay is the working name). It appears in file names and the update manifest until that is settled.

• Desktop only (Linux now, Windows planned), always mpv. No web clients.
• No transcoding. Everyone plays the original file.
• Friends trust model: no accounts, no roles. A blank password means an open server.

How it fits together: docs/HOW-IT-WORKS.md.

Install and update

Download the latest watch-together-<version>-linux-x64.tar.gz from the Releases page of this repo, extract it, run watch_together.

Update from the app: when a newer version exists, an update indicator appears on Home and opens the update card. "Update and restart" downloads, verifies, applies in place and restarts; the install folder must be writable by you. Settings has Check now and an auto-check toggle. From a terminal: watch_together --upgrade or update.sh (shipped in the tarball). A release with a newer protocol is a required update: everyone on a server must run the same protocol version, and a mismatch is refused with a message telling you to update.

Host from the app

Home, Host card. Pick a port, an optional password (blank = anyone can join), and optionally a video: a link or a file path. Your name and avatar come from your profile. The app starts a server inside itself and joins it. Friends need to reach your machine: open the TCP port on your router (or use a LAN or VPN address). Friends open nothing.

If you pick a local file, the server streams it to everyone from your disk. Nothing is uploaded or stored anywhere.

Dedicated server

Being reworked: today the server is started by the app (host) and the standalone server is a dev tool. The planned dedicated server is a separate binary built from packages/server. See docs/ROADMAP.md.

Join

Home, Join card. Enter the host's address, port, and the password if there is one. Your name and avatar come from your profile (Home chip or Settings). Servers you got into appear as up to 6 Recent chips on Home: one click rejoins.

Settings

Profile, hardware decoding (auto, off or custom; the env var SYNC_RELAY_HWDEC overrides it; applies on the next join or Reload video), updates, and the keyboard shortcuts (read-only). Integrations (Jellyfin) and shaders show "coming soon". About shows the version.

Keys in a session: Space = ready / unready, Tab = side panel (people, log, chat, change video), Left/Right = seek 10 s, F = fullscreen, Esc = close panel or ask to leave, Ctrl+R = reload video.

Ports

What	Default	Notes
Sync WebSocket and /health	TCP 8080	plain ws://, no TLS
Local file streaming	same port	path /m/..., needs a session token

Only the host needs the port reachable.

Jellyfin

Pasting a Jellyfin direct-play link works today like any link. Proper Jellyfin support (per-person login, watched status, library browsing) is planned: see docs/ROADMAP.md.

Video quality and shaders

Planned: Anime4K and other mpv shaders as a per-viewer setting. See docs/ROADMAP.md.

Troubleshooting

• "host offline - check address and port": wrong address, or the port is not open.
• "wrong server password": password mismatch.
• "host runs a different version": update the app on both sides.
• Picture frozen but sound fine: Ctrl+R reloads the video; the app also does it automatically.
• Everyone waits at "waiting for X": X has not buffered 4 seconds yet or has not pressed Space.
• No Windows build yet.

For contributors: docs/DEVELOPMENT.md, docs/ARCHITECTURE.md, docs/PROTOCOL.md.