init

README.md

@@ -0,0 +1,103 @@
+# SyncTV
+
+SyncTV is a no-account synchronized watching app. The first version keeps the server thin: room state, WebSocket signaling, Redis-backed temporary state, and optional streaming proxy when the room owner enables it.
+
+## Quick Start
+
+```bash
+docker compose up --build
+```
+
+Server:
+
+- HTTP: `http://yuyun-us1.stormrain.cn:8088`
+- WebSocket: `ws://yuyun-us1.stormrain.cn:8088/ws?roomCode=<CODE>&deviceId=<DEVICE_ID>`
+- Health: `GET /health`
+
+## Local Server
+
+```bash
+cd server
+$env:SYNCTV_CONFIG="../config/server.local.json"
+go run ./cmd/synctv-server
+```
+
+Create a local config with Redis pointing at your local Redis instance.
+
+## HTTP API
+
+- `GET /health`
+- `POST /api/rooms`
+- `GET /api/rooms/{code}?deviceId={deviceId}`
+- `POST /api/rooms/{code}/source` with `X-Device-Id`
+- `GET /api/rooms/{code}/stream` for proxy mode playback
+
+## WebSocket
+
+Connect:
+
+```text
+ws://yuyun-us1.stormrain.cn:8088/ws?roomCode=A7K29Q&deviceId=dev_xxx
+```
+
+Client events:
+
+- `setSource`
+- `play`
+- `pause`
+- `seek`
+- `syncProgress`
+- `syncToLive`
+- `heartbeat`
+
+Server events:
+
+- `roomSnapshot`
+- `sourceChanged`
+- `playbackChanged`
+- `presenceChanged`
+- `heartbeatAck`
+- `error`
+
+## Clients
+
+The product is split by platform.
+
+### Windows
+
+Windows source lives in `windows_py_client`.
+
+Required tools:
+
+- Python 3.11+
+- VLC 64-bit runtime
+
+Run:
+
+```powershell
+cd windows_py_client
+python -m venv .venv
+.\.venv\Scripts\pip install -r requirements.txt
+.\.venv\Scripts\python synctv_client\main.py
+```
+
+Build exe:
+
+```powershell
+.\build_exe.ps1
+```
+
+The Windows client uses PySide6 + python-vlc.
+
+### App
+
+HBuilder/uni-app source lives in `hbuilder_app`.
+
+Open `hbuilder_app` in HBuilderX and run/build as an App project.
+
+Playback direction:
+
+- Development fallback: built-in `<video>`.
+- Production target: `nativeplugins/SyncTV-VLC`, a uni-app native plugin wrapping VLC.
+
+HBuilder cannot directly call VLC from Vue/JavaScript. It needs a native plugin bridge. The JS facade is already defined in `hbuilder_app/common/player.js`.