SyncTV

简体中文

SyncTV is a Rust implementation of a real-time synchronized video watching platform with media provider integration, livestreaming, HTTP/gRPC APIs, and Kubernetes-ready horizontal scaling.

Highlights

• Synchronized room playback with real-time state updates.
• Media providers for Bilibili, Twitch, YouTube, Douyin, TikTok, Huya, Douyu, AcFun, CCTV, Alist, Cloudreve, Emby/Jellyfin, FNOS, QNAP, Synology, Nextcloud, Seafile, TrueNAS, direct URLs, and livestream sources.
• RTMP push/pull, HLS, and HTTP-FLV livestream support.
• HTTP REST, public gRPC, WebSocket, management gRPC, metrics, RTMP, and STUN runtime surfaces.
• PostgreSQL-backed durable storage with optional Redis shared state, cache, rate limiting, and cluster coordination.
• Docker Compose and Helm deployment templates.
• Built-in management CLI and optional OpenAPI/Swagger UI.
• Astro Starlight documentation site with English and Simplified Chinese content.

Quick Start

Development environment from a full repository checkout:

# Starts PostgreSQL and Redis, then runs SyncTV locally with development settings.
make dev-serve

# Starts SyncTV in the background with the same development settings.
make dev-start
make dev-stop

# Starts optional media/auth/storage dependencies too.
make dev-stack

# Runs real CLI/curl provider smoke tests through the Makefile dev startup path.
make dev-smoke

Production Compose can run from the repository root or from a directory containing docker-compose.yml, .env.postgres.example, .env.redis.example, .env.synctv.example, and scripts/init-compose-env.sh. It requires explicit secrets for PostgreSQL, Redis, and application auth/encryption:

# Requires Docker Compose, openssl, and python3.
./scripts/init-compose-env.sh

# Edit SYNCTV_BOOTSTRAP_ROOT_PASSWORD in .env.synctv before starting.
docker compose config
docker compose up -d

Validate configuration:

cargo +nightly run -p synctv --bin synctv -- config validate

Optional migration preflight. The server also runs embedded SQLx migrations automatically during startup:

cargo +nightly run -p synctv --bin synctv -- db migrate

Start locally:

cargo +nightly run -p synctv --bin synctv -- serve

Documentation

The main documentation site lives in docs/. It contains detailed configuration reference, deployment guides, operations runbooks, CLI reference, development guide, and OpenAPI access instructions.

cd docs
npm install
npm run dev

Build the static docs site:

cd docs
npm run build

If the generated site is deployed below a subpath, set SYNCTV_DOCS_BASE at build time. Set SYNCTV_DOCS_SITE to the public origin used for canonical URLs and sitemaps.

cd docs
SYNCTV_DOCS_SITE=https://example.com SYNCTV_DOCS_BASE=/synctv npm run build

Important entry points:

• Quick Start
• Documentation Map
• Architecture Overview
• Authentication and Security Model
• Administration Runbook
• Rooms, Permissions, and Preferences
• Provider User Guide
• Provider Development Guide
• Client Integration Guide
• How Configuration Works
• Full Configuration Example
• Configuration Index
• Environment Variables
• Runtime Settings Reference
• Docker Compose Deployment
• Helm Deployment
• Production Checklist
• Backup and Restore
• Upgrades and Migrations
• Data, Privacy, and Retention
• Observability Runbook
• Troubleshooting
• CLI Reference
• OpenAPI Access
• gRPC Debugging
• Development Guide

Repository process documents:

• Security Policy
• Contributing Guide

Workspace Layout

• synctv: application binary and CLI.
• synctv-core: core business logic, configuration, services, and repositories.
• synctv-core/testing: reusable integration-test fixtures and service helpers.
• synctv-api: HTTP/gRPC API layer.
• synctv-livestream: RTMP/HLS/HTTP-FLV livestream support.
• synctv-cluster: cluster coordination.
• synctv-proxy: media proxy and slice cache.
• synctv-proto: protobuf definitions.
• synctv-media-providers: provider integration support.
• synctv-management: management client/control-plane support.
• synctv-common: shared utilities.
• synctv-xiu: consolidated livestreaming components.
• helm/synctv: Kubernetes Helm chart.
• docs: Astro Starlight documentation site.

License

MIT. See LICENSE.