# SyncTV
[简体中文 ](./README.zh-CN.md )
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, 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:
```bash
docker compose -f docker-compose.dev.yml up -d
```
Production Compose requires explicit secrets:
```bash
./scripts/init-compose-env.sh
# Edit SYNCTV_BOOTSTRAP_ROOT_PASSWORD in .env.synctv before starting.
docker compose config
docker compose up -d
```
Validate configuration:
```bash
cargo run -p synctv --bin synctv -- config validate
```
Optional migration preflight. The server also runs embedded SQLx migrations automatically during startup:
```bash
cargo run -p synctv --bin synctv -- db migrate
```
Start locally:
```bash
cargo run -p synctv --bin synctv -- serve
```
## Documentation
The main documentation site lives in [`docs/` ](./docs ). It contains detailed configuration reference, deployment guides, operations runbooks, CLI reference, development guide, and OpenAPI access instructions.
```bash
cd docs
npm install
npm run dev
```
Build the static docs site:
```bash
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.
```bash
cd docs
SYNCTV_DOCS_SITE=https://example.com SYNCTV_DOCS_BASE=/synctv npm run build
```
Important entry points:
- [Quick Start ](./docs/src/content/docs/en/guides/quick-start.mdx )
- [Documentation Map ](./docs/src/content/docs/en/guides/documentation-map.mdx )
- [Architecture Overview ](./docs/src/content/docs/en/guides/architecture.mdx )
- [Authentication and Security Model ](./docs/src/content/docs/en/guides/security-model.mdx )
- [Administration Runbook ](./docs/src/content/docs/en/guides/administration.mdx )
- [Rooms, Permissions, and Preferences ](./docs/src/content/docs/en/guides/rooms-permissions.mdx )
- [Client Integration Guide ](./docs/src/content/docs/en/guides/client-integration.mdx )
- [How Configuration Works ](./docs/src/content/docs/en/configuration/how-configuration-works.mdx )
- [Full Configuration Example ](./docs/src/content/docs/en/configuration/full-example.mdx )
- [Configuration Index ](./docs/src/content/docs/en/reference/configuration-index.mdx )
- [Environment Variables ](./docs/src/content/docs/en/reference/environment-variables.mdx )
- [Runtime Settings Reference ](./docs/src/content/docs/en/reference/runtime-settings.mdx )
- [Docker Compose Deployment ](./docs/src/content/docs/en/deployment/docker-compose.mdx )
- [Helm Deployment ](./docs/src/content/docs/en/deployment/helm.mdx )
- [Production Checklist ](./docs/src/content/docs/en/deployment/production-checklist.mdx )
- [Backup and Restore ](./docs/src/content/docs/en/operations/backup-restore.mdx )
- [Upgrades and Migrations ](./docs/src/content/docs/en/operations/upgrades.mdx )
- [Data, Privacy, and Retention ](./docs/src/content/docs/en/operations/data-retention.mdx )
- [Observability Runbook ](./docs/src/content/docs/en/operations/observability.mdx )
- [Troubleshooting ](./docs/src/content/docs/en/operations/troubleshooting.mdx )
- [CLI Reference ](./docs/src/content/docs/en/reference/cli.mdx )
- [OpenAPI Access ](./docs/src/content/docs/en/reference/openapi.mdx )
- [gRPC Debugging ](./docs/src/content/docs/en/reference/grpc.mdx )
- [Development Guide ](./docs/src/content/docs/en/guides/development.mdx )
Repository process documents:
- [Security Policy ](./SECURITY.md )
- [Contributing Guide ](./CONTRIBUTING.md )
## Workspace Layout
- `synctv` : application binary and CLI.
- `synctv-core` : core business logic, configuration, services, and repositories.
- `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 ](./LICENSE ).
