synctv/README.md

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 including Bilibili, Alist, Emby-compatible servers (Emby/Jellyfin), and direct URLs.
• 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:

# Uses built-in local-only development settings.
docker compose -f docker-compose.dev.yml up -d

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 run -p synctv --bin synctv -- config validate

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

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

Start locally:

cargo 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
• 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.