mirror of https://github.com/synctv-org/synctv
docs: reorganize server documentation (#28)
* docs: reorganize server documentation * docs: tighten visual design and writingpull/370/head
zijiren
2 months ago
committed by
GitHub
parent
e9f32205c3
commit
3f1e00b9d2
@ -1,43 +0,0 @@
|
||||
---
|
||||
title: SyncTV 概念
|
||||
description: 了解房间、媒体源、播放模型、权限和运行边界，再进入具体任务页。
|
||||
---
|
||||
|
||||
import { LinkCard, CardGrid } from '@astrojs/starlight/components';
|
||||
|
||||
概念页解释 SyncTV 的产品模型。它们不替代操作指南，也不重复配置字段；当你需要判断一个功能属于哪里、由谁控制、失败时先看哪一层时，从这里开始。
|
||||
|
||||
<CardGrid>
|
||||
<LinkCard
|
||||
title="房间"
|
||||
href="./rooms/"
|
||||
description="房间如何组织成员、播放列表、聊天、直播和设置。"
|
||||
/>
|
||||
<LinkCard
|
||||
title="媒体源"
|
||||
href="./media-providers/"
|
||||
description="Provider、直链、远程 Provider、直播入口和播放结果的职责边界。"
|
||||
/>
|
||||
<LinkCard
|
||||
title="播放模型"
|
||||
href="./playback-model/"
|
||||
description="当前播放状态、播放信息、Realtime、直连、代理和 Range seek。"
|
||||
/>
|
||||
<LinkCard
|
||||
title="播放后台任务"
|
||||
href="./playback-background-workers/"
|
||||
description="时长探测、自动切换和播放资源生命周期任务的本节点 active room 边界。"
|
||||
/>
|
||||
<LinkCard
|
||||
title="权限模型"
|
||||
href="./permissions/"
|
||||
description="全局角色、房间角色、成员覆盖、房间设置和用户偏好的关系。"
|
||||
/>
|
||||
<LinkCard
|
||||
title="运行边界"
|
||||
href="./runtime-boundaries/"
|
||||
description="PostgreSQL、Redis、secret、管理面、metrics、媒体代理和非目标。"
|
||||
/>
|
||||
</CardGrid>
|
||||
|
||||
读完概念后，按当前目标进入 [使用 SyncTV](../use/)、[管理 SyncTV](../admin/)、[安装与升级](../install/choose-path/) 或 [开发与集成](../develop/client-integration/)。维护共享行为时同时阅读 [实现契约](../develop/implementation-contracts/)。
|
||||
@ -1,37 +0,0 @@
|
||||
---
|
||||
title: 房间
|
||||
description: 房间如何组织成员、播放列表、聊天、直播入口、权限和当前播放状态。
|
||||
---
|
||||
|
||||
房间是 SyncTV 的核心工作空间。一次观影、一组成员、一份播放列表、一套权限和当前播放状态都挂在房间上。用户进入房间后看到的按钮、媒体、聊天和管理入口，取决于房间设置和自己在房间里的角色。
|
||||
|
||||
## 房间包含什么
|
||||
|
||||
| 内容 | 用途 |
|
||||
| --- | --- |
|
||||
| 成员 | 房间创建者、管理员、成员和游客 |
|
||||
| 播放列表 | 房间内可播放的媒体、子列表和排序 |
|
||||
| 当前播放 | 当前媒体、播放进度、暂停状态、播放速度和版本 |
|
||||
| 聊天 | 房间内消息，受发送权限和房间开关控制 |
|
||||
| 加入规则 | 是否公开、是否需要密码、是否需要审核、成员上限 |
|
||||
| 权限 | 角色默认权限和成员级覆盖 |
|
||||
| 直播入口 | RTMP/直播推流和播放会话 |
|
||||
|
||||
## 谁能管理房间
|
||||
|
||||
全局管理员和房间管理员是两套概念。全局 `root` 或 `admin` 可以通过管理入口维护实例，但不代表普通房间内的所有操作都应该绕过房间权限。房间内的长期职责应优先通过房间角色表达，临时例外再使用成员权限覆盖。
|
||||
|
||||
## 常见房间状态
|
||||
|
||||
| 状态 | 用户体验 | 管理动作 |
|
||||
| --- | --- | --- |
|
||||
| 公开可加入 | 用户打开房间后直接进入 | 控制默认权限和成员上限 |
|
||||
| 需要密码 | 用户输入房间密码后进入 | 定期更换密码，避免泄露 |
|
||||
| 需要审核 | 用户提交申请，等待批准 | 处理申请并写清拒绝原因 |
|
||||
| 暂停使用 | 用户无法继续加入或操作 | 封禁房间或关闭相关入口 |
|
||||
|
||||
## 下一步
|
||||
|
||||
- 普通用户创建或加入房间：读 [创建和加入房间](../../use/rooms/)。
|
||||
- 管理成员和房间设置：读 [房间与成员管理](../../admin/rooms-members/)。
|
||||
- 调整权限：读 [权限模型](../permissions/) 和 [房间、权限与用户偏好](../../use/rooms-permissions/)。
|
||||
@ -1,93 +0,0 @@
|
||||
---
|
||||
title: 文档写作规范
|
||||
description: SyncTV 文档的信息架构、页面类型、措辞、链接、术语和中英文同步规则。
|
||||
---
|
||||
|
||||
SyncTV 文档按读者任务组织。写文档前先确定读者是谁、读者要完成什么、完成后如何验证。不要把概念解释、操作步骤、字段参考和排障矩阵塞进同一页。
|
||||
|
||||
## 页面类型
|
||||
|
||||
| 类型 | 用途 | 写法 |
|
||||
| --- | --- | --- |
|
||||
| Task | 帮读者完成一个具体动作 | 先给前置条件，再给步骤，最后给验证和失败处理 |
|
||||
| Concept | 解释产品模型或系统边界 | 说明对象、关系、责任边界和下一步，不放完整字段表 |
|
||||
| Reference | 查字段、命令、指标、错误码 | 保持结构稳定、可搜索，不承担教学 |
|
||||
| Troubleshooting | 按现象定位问题 | 用“现象、先检查、交给谁/下一步”组织 |
|
||||
| Runbook | 管理员或运维执行流程 | 明确影响范围、操作顺序、回滚和验证 |
|
||||
|
||||
## 页面开头
|
||||
|
||||
首段直接回答“这页帮你做什么”。不要写泛泛的背景介绍。
|
||||
|
||||
推荐：
|
||||
|
||||
```md
|
||||
这页说明如何创建房间、设置加入规则，并用普通成员账号验证房间可以正常进入。
|
||||
```
|
||||
|
||||
避免：
|
||||
|
||||
```md
|
||||
本章节将全面介绍 SyncTV 房间相关能力和复杂边界。
|
||||
```
|
||||
|
||||
## 标题
|
||||
|
||||
- Task 页标题使用动作：`创建和加入房间`、`添加媒体`。
|
||||
- Concept 页标题使用名词：`播放模型`、`权限模型`。
|
||||
- Reference 页标题使用对象：`Runtime settings 参考`、`Metrics Catalog`。
|
||||
- 标题不写“完整指南”“全面说明”“最佳实践”这类空泛词。
|
||||
|
||||
## 措辞
|
||||
|
||||
优先使用短句和主动表达。能写具体动作时，不写抽象评价。
|
||||
|
||||
| 少用 | 改成 |
|
||||
| --- | --- |
|
||||
| 通常应该先确认 | 先检查 |
|
||||
| 相关页面 | 下一步、参考、继续排查 |
|
||||
| 语义 | 含义、影响、规则 |
|
||||
| 边界 | 责任、范围、限制 |
|
||||
| 生产规则 | 上线前检查、操作规则 |
|
||||
|
||||
这些词不是禁用词。配置、安全和架构页可以使用它们，但不能作为固定模板反复出现。
|
||||
|
||||
## 链接
|
||||
|
||||
- 链接放在读者需要下一步的位置。
|
||||
- Task 页结尾使用“下一步”，不要机械堆“相关页面”。
|
||||
- Reference 页可以保留参考链接，但每个链接要有明确用途。
|
||||
- 不使用旧路径 `deployment/`、`guides/`。
|
||||
- 不使用脆弱锚点链接指向长页内部标题；优先链接到独立页面。
|
||||
|
||||
## 术语
|
||||
|
||||
| 术语 | 中文写法 | 英文写法 |
|
||||
| --- | --- | --- |
|
||||
| Provider | Provider 或媒体源 Provider | Provider |
|
||||
| Realtime | Realtime 或实时连接 | Realtime |
|
||||
| runtime settings | runtime settings 或运行设置 | runtime settings |
|
||||
| management gRPC | management gRPC 或管理控制面 | management gRPC |
|
||||
| proxy slice cache | proxy slice cache | proxy slice cache |
|
||||
|
||||
首次出现时解释含义，之后保持同一页面内一致。不要把同一概念在同一页里写成多套名字。
|
||||
|
||||
## 中英文同步
|
||||
|
||||
每个中文页面必须有英文镜像，路径在 `en/` 下保持一致。英文页面按英文产品文档习惯重写，不逐句直译中文：
|
||||
|
||||
- 英文用短句。
|
||||
- 标题用动词或清晰名词。
|
||||
- 少用 abstract nouns。
|
||||
- 中文能保留的产品名，英文仍保留产品名。
|
||||
|
||||
## 检查
|
||||
|
||||
提交文档前运行：
|
||||
|
||||
```bash
|
||||
cd docs
|
||||
npm run validate
|
||||
```
|
||||
|
||||
校验会检查内部链接、Starlight 图标、旧路径、旧标题、未完成标记和英文镜像。模板化收尾会作为 warning 输出，逐步清理。
|
||||
@ -1,36 +1,31 @@
|
||||
---
|
||||
title: Administer SyncTV
|
||||
description: Manage users, rooms, members, reviews, Providers, livestreaming, runtime settings, and maintenance tasks.
|
||||
description: Manage users, rooms, permissions, Providers, runtime settings, and maintenance tasks.
|
||||
---
|
||||
|
||||
import { LinkCard, CardGrid, Aside } from '@astrojs/starlight/components';
|
||||
import { Aside } from '@astrojs/starlight/components';
|
||||
|
||||
Administration docs are organized by managed object. Choose the object first, then read the impact, operation order, and validation steps.
|
||||
Administration commands call management gRPC through `synctv admin`. Confirm the management endpoint and authentication method before applying changes.
|
||||
|
||||
<Aside type="caution">
|
||||
management gRPC, metrics, and internal debugging endpoints are not public management surfaces. Prefer Unix sockets, private networks, VPNs, bastions, or Kubernetes exec. TCP management must set `management.auth_token`.
|
||||
Expose management gRPC, metrics, and internal debugging endpoints only through Unix sockets, private networks, VPNs, bastions, or Kubernetes exec. TCP management must set `management.auth_token`.
|
||||
</Aside>
|
||||
|
||||
<CardGrid>
|
||||
<LinkCard title="User Management" href="./users/" description="Create users, ban and unban, change global roles, and inspect account security state." />
|
||||
<LinkCard title="Room and Member Management" href="./rooms-members/" description="Manage room lifecycle, members, settings, playback controls, and live entries." />
|
||||
<LinkCard title="Reviews and Moderation" href="./reviews-moderation/" description="Handle registration, room creation, join reviews, and moderation actions." />
|
||||
<LinkCard title="Provider Management" href="./providers/" description="Create, enable, disable, update, reconnect, and delete Provider instances." />
|
||||
<LinkCard title="Runtime Settings" href="./runtime-settings/" description="Hot-update registration, room creation, proxy policy, CORS, and retention policy." />
|
||||
<LinkCard title="Maintenance Tasks" href="./maintenance/" description="Inspect system state, clear streams, evict slice cache, and validate after maintenance." />
|
||||
<LinkCard title="Authentication and Security Model" href="./authentication-security/" description="Understand sign-in methods, 2FA, token context, Provider headers, and management boundaries." />
|
||||
</CardGrid>
|
||||
|
||||
## Managed Objects
|
||||
|
||||
| Object | Common actions | Check first |
|
||||
| --- | --- | --- |
|
||||
| Users | Create, ban, unban, change role, inspect preferences | Global role, effective status, 2FA state |
|
||||
| Rooms | Create, delete, transfer, ban, update settings | Creator, join rules, member limit, default permissions |
|
||||
| Members | Add, kick, change role, change permissions | Whether role or member override is the right tool |
|
||||
| Reviews | Approve or reject registration, room creation, room join | Applicant, target room, rejection reason |
|
||||
| Providers | Create, enable, disable, update, reconnect, delete | Credential ownership, proxy policy, remaining references |
|
||||
| Runtime settings | Change registration, CORS, proxy policy, retention | Whether the value is runtime policy, not startup configuration |
|
||||
| System and cache | Inspect status, clear streams, evict slice cache | Whether the action affects online playback or cache hit rate |
|
||||
|
||||
Command flags are in [CLI Reference](../reference/cli/). Runtime boundaries are covered in [Runtime Boundaries](../concepts/runtime-boundaries/).
|
||||
## Accounts and Access
|
||||
|
||||
- [Users](./users/): create users, ban accounts, assign global roles, and inspect account security state.
|
||||
- [Roles and Permissions](./permissions/): global roles, room roles, permission evaluation, and member overrides.
|
||||
- [Authentication and Security](./authentication-security/): sign-in methods, 2FA, tokens, and authentication boundaries.
|
||||
|
||||
## Rooms and Content
|
||||
|
||||
- [Rooms and Members](./rooms-members/): room lifecycle, members, playback controls, and livestream entries.
|
||||
- [Reviews and Moderation](./reviews-moderation/): registration, room creation, join reviews, and bans.
|
||||
- [Providers](./providers/): create, enable, disable, update, reconnect, and delete Provider instances.
|
||||
|
||||
## Service Policy and Maintenance
|
||||
|
||||
- [Runtime Settings](./runtime-settings/): hot-update registration, proxy, CORS, chat, and room policies.
|
||||
- [Maintenance Tasks](./maintenance/): inspect state, clear streams, evict caches, and verify results.
|
||||
|
||||
The [CLI Reference](../reference/cli/) lists every flag. [Deployment and Runtime Boundaries](../operations/deployment-boundaries/) covers production dependencies and management-plane requirements.
|
||||
|
||||
@ -1,19 +0,0 @@
|
||||
---
|
||||
title: SyncTV Concepts
|
||||
description: Understand rooms, media sources, playback, permissions, and runtime boundaries before using task guides.
|
||||
---
|
||||
|
||||
import { LinkCard, CardGrid } from '@astrojs/starlight/components';
|
||||
|
||||
Concept pages explain the product model. Use them when you need to know where a capability belongs, who controls it, and which layer to inspect when it fails.
|
||||
|
||||
<CardGrid>
|
||||
<LinkCard title="Rooms" href="./rooms/" description="How rooms organize members, playlists, chat, livestreaming, and settings." />
|
||||
<LinkCard title="Media Sources" href="./media-providers/" description="Provider, direct URL, remote Provider, livestream, and playback result boundaries." />
|
||||
<LinkCard title="Playback Model" href="./playback-model/" description="Playback state, playback info, Realtime, direct URLs, proxying, and Range seek." />
|
||||
<LinkCard title="Playback Background Workers" href="./playback-background-workers/" description="Node-local active room boundaries for duration probing, auto-advance, and playback resource lifecycle work." />
|
||||
<LinkCard title="Permissions Model" href="./permissions/" description="Global roles, room roles, member overrides, room settings, and preferences." />
|
||||
<LinkCard title="Runtime Boundaries" href="./runtime-boundaries/" description="PostgreSQL, Redis, secrets, management endpoints, metrics, proxying, and non-goals." />
|
||||
</CardGrid>
|
||||
|
||||
After the concepts, continue with [Use SyncTV](../use/), [Administer SyncTV](../admin/), [Install and Upgrade](../install/choose-path/), or [Develop with SyncTV](../develop/client-integration/). Maintainers changing shared behavior should also read [Implementation Contracts](../develop/implementation-contracts/).
|
||||
@ -1,80 +0,0 @@
|
||||
---
|
||||
title: Media Sources
|
||||
description: Provider, direct URL, remote Provider, livestream, and playback result responsibilities in SyncTV.
|
||||
---
|
||||
|
||||
SyncTV does not store media files. It resolves external media into playback results, then lets clients play directly or through the SyncTV proxy. The resolving layer is called a Provider.
|
||||
|
||||
## What Providers Do
|
||||
|
||||
| Capability | Meaning |
|
||||
| --- | --- |
|
||||
| Browse and search | List media from video platforms, live platforms, Alist, Cloudreve, Emby/Jellyfin, NAS systems, or remote services |
|
||||
| Resolve playback | Return playback URLs, proxy URLs, headers, subtitles, variants, or metadata |
|
||||
| Manage credentials | Store tokens, cookies, API keys, or account credentials for upstream services |
|
||||
| Expose behavior | Tell clients whether direct play, proxying, Range, livestreaming, or backend features are available |
|
||||
|
||||
A Provider returns a playback decision, not only a URL. Clients should use the headers and proxy mode returned by the Provider instead of inventing `User-Agent`, `Referer`, Cookie, or Range rules.
|
||||
|
||||
A playback result can return upstream and proxy modes together, such as `direct`/`proxy_direct`, `dash`/`proxy_dash`, HLS quality modes, and their proxy siblings. Each Provider performs signing and mode selection during `generate_playback` because Bilibili DASH, Alist HLS, Emby/Jellyfin transcoding, RTMP, and live proxy all have different URLs, headers, manifests, subtitles, and resource lifecycles.
|
||||
|
||||
`generate_playback` is the Provider playback decision boundary. Providers create direct/proxy modes, `default_mode`, headers, signed proxy URLs, manifest/subtitle rewriting, danmaku, thumbnails, and lifecycle metadata there. Shared helpers only perform mechanical `proxy_*` sibling URL generation; each Provider chooses when to use them, which mode is default, and which headers are exposed.
|
||||
|
||||
Provider cache stores `VersionedPlayback`: the raw `PlaybackResult`, proxy
|
||||
lookup `version`, and expiry. It supports cache hits and provider-proxy URL
|
||||
lookup; the signed response shape still comes from the Provider rewrite
|
||||
callback. Cache hits and fresh responses must expose the same usable modes,
|
||||
resolver actions, manifest/segment routes, and auxiliary URLs.
|
||||
|
||||
When adding or refactoring a Provider, keep signing timing, URL expiry, default mode, proxy siblings, manifest/segment rewriting, and live resource lifecycle inside that Provider's `generate_playback` and proxy resolver. Shared code should express mechanical steps that are genuinely common across Providers.
|
||||
|
||||
HTTP, gRPC, and management APIs treat `PlaybackResult` as the source of truth. They translate transport parameters and encode responses while Provider policy stays in the core provider layer.
|
||||
|
||||
## Playback Content Contract
|
||||
|
||||
| Provider | Required coverage |
|
||||
| --- | --- |
|
||||
| Direct URL | upstream mode, `proxy_*` sibling, proxy default for sources with headers, HLS manifest segment rewriting, Range. |
|
||||
| Alist | direct/transcode modes, `proxy_*` siblings, thumbnail, subtitle, HLS segment, stream proxy resolver. |
|
||||
| Emby/Jellyfin | upstream/transcode modes, proxy siblings, allowed upstream token headers, direct stream, HLS/transcode, subtitle proxy. |
|
||||
| Bilibili | anonymous playback, DASH/MPD proxy default, proxy manifest segments, subtitles, danmaku, thumbnails, cache metadata, CDN headers. |
|
||||
| RTMP | publish key, stream info, HLS playlist/segment, FLV, provider-proxy URL, idle cleanup. |
|
||||
| live proxy | external RTMP/HTTP-FLV pull, HLS/FLV provider-proxy URL, publisher registration, idle cleanup unregister. |
|
||||
| Video platforms | Native quality/CDN choices, subtitles, danmaku or chat, covers, short-lived URL refresh, and account feeds. |
|
||||
| NAS/private cloud | File/media-library paths, previews, Range, native transcode/remux, playback progress, and favorite state. |
|
||||
|
||||
Every URL returned to clients needs a real request test. When adding a mode, add the resolver, cache hit/expiry handling, URL expiry handling, and manual E2E coverage at the same time.
|
||||
|
||||
## Common Sources
|
||||
|
||||
| Source | Good for | Watch out for |
|
||||
| --- | --- | --- |
|
||||
| Direct URL | A stable URL already reachable by clients | Browser header restrictions |
|
||||
| Alist | Cloud drive and file browsing | Upstream auth, directory permissions, Range support |
|
||||
| Emby/Jellyfin | Existing media libraries | Transcoding, subtitles, bitrate, upstream user permissions |
|
||||
| Bilibili | Platform video resolving | Cookie, Referer, UA, and upstream policy changes |
|
||||
| Twitch/YouTube/Douyin/TikTok | Live, video, channel, and account feeds | OAuth scopes, Cookies, region, and short-lived playback URLs |
|
||||
| Huya/Douyu/AcFun/CCTV | Public live and video resolution | Upstream page and signing protocol changes |
|
||||
| Cloudreve | Private-cloud files and folders | Servers can use page or cursor pagination |
|
||||
| FNOS/QNAP/Synology | NAS files and native media libraries | Firmware, media-service, and transcoding capability differences |
|
||||
| Nextcloud/Seafile/TrueNAS | Private-cloud files, favorites, and search | App passwords, library unlock, and storage-path permissions |
|
||||
| Remote Provider | Isolating media resolving into another service | Auth, network, and version compatibility |
|
||||
| RTMP/live | Room livestreaming | Multi-replica HLS backend or publisher-node proxy |
|
||||
|
||||
## Security Boundary
|
||||
|
||||
Provider credentials are sensitive. Configure `security.credential_encryption_key` in production, and keep tokens, cookies, and API keys out of logs, shell history, and public configuration.
|
||||
|
||||
## End-to-End Verification Boundary
|
||||
|
||||
After changing Provider, proxy, signing, manifest, subtitle, RTMP, or live proxy behavior, verify with a built `synctv` binary, the `synctv` CLI, and `curl`. Cover Direct URL, Alist, Emby, Jellyfin, Bilibili anonymous playback, RTMP, live proxy, HLS, FLV, Range, cache miss/hit paths, URL expiry, and cleanup.
|
||||
|
||||
The verification target is the full `PlaybackResult`: every mode, URL, manifest, indexed segment, subtitle, danmaku, thumbnail, and proxy sibling should be requested. Add CLI coverage before accepting a provider workflow that can only be exercised through direct database writes or ad hoc internal calls.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Add media by source: [Add Media](../../use/media-sources/).
|
||||
- Understand direct/proxy playback: [Playback Model](../playback-model/).
|
||||
- Configure Provider behavior: [Media Providers](../../configuration/media-providers/).
|
||||
- Use each Provider: [Provider User Guide](../../use/provider-guide/).
|
||||
- Develop Providers: [Provider Development Guide](../../develop/provider-development/).
|
||||
@ -1,34 +0,0 @@
|
||||
---
|
||||
title: Permissions Model
|
||||
description: How global roles, room roles, member overrides, room settings, and user preferences determine allowed actions.
|
||||
---
|
||||
|
||||
SyncTV permissions have platform scope and room scope. Platform roles decide who can administer the instance. Room roles and member overrides decide what a user can do in one room.
|
||||
|
||||
## Permission Sources
|
||||
|
||||
| Source | Scope | Examples |
|
||||
| --- | --- | --- |
|
||||
| Global role | Whole instance | `root`, `admin`, `user` |
|
||||
| Room role | One room | `creator`, `admin`, `member`, `guest` |
|
||||
| Member override | One user in one room | Temporary playback control, mute, media restriction |
|
||||
| Room setting | One room | Guest access, chat enabled, review required |
|
||||
| User preference | One user | 2FA, notification preference, default Provider |
|
||||
|
||||
## Management Principles
|
||||
|
||||
| Situation | Prefer |
|
||||
| --- | --- |
|
||||
| Long-term responsibility change | Change room role or role defaults |
|
||||
| Temporary exception | Use a member override |
|
||||
| Restrict everyone from chatting | Change the room chat setting |
|
||||
| Restrict one member from chatting | Remove that member's `send_chat_messages` |
|
||||
| Grant platform administration | Change the global role |
|
||||
|
||||
A platform `admin` is not automatically a room `admin` in every room. A room `admin` cannot manage platform users, Providers, or runtime settings.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Full permission names and evaluation rules: [Rooms, Permissions, and Preferences](../../use/rooms-permissions/).
|
||||
- Member management: [Room and Member Management](../../admin/rooms-members/).
|
||||
- Authentication and 2FA: [Authentication and Security Model](../../admin/authentication-security/).
|
||||
@ -1,58 +0,0 @@
|
||||
---
|
||||
title: Playback Model
|
||||
description: How playback state, playback info, Realtime, direct URLs, proxying, Range seek, and livestreaming fit together.
|
||||
---
|
||||
|
||||
Synchronized watching is driven by server-side room state. A client should not treat its local player state as the source of truth. It follows room playback state and submits control actions only when the user has permission.
|
||||
|
||||
## Two Kinds of State
|
||||
|
||||
| State | Owner | Used for |
|
||||
| --- | --- | --- |
|
||||
| Current playback state | SyncTV server | Current media, play/pause, position, speed, and version |
|
||||
| Playback info | Provider and SyncTV | Playback URL, proxy URL, headers, subtitles, variants, and expiry |
|
||||
|
||||
Current playback state answers “what is the room watching and where is it?”. A playback info answers “how should this client play that media now?”.
|
||||
|
||||
## Realtime Flow
|
||||
|
||||
Room WebSocket connections carry playback controls, chat, WebRTC signaling, and resource observation events. After reconnecting, clients should fetch key resources again instead of assuming old subscriptions are still active.
|
||||
|
||||
1. Enter a room.
|
||||
2. Fetch current playback state and a playback info.
|
||||
3. Connect Realtime.
|
||||
4. Receive play, pause, seek, or media-change events.
|
||||
5. Refresh the playback info when the media URL expires, Provider credentials change, or room resources change.
|
||||
|
||||
## Direct and Proxy Playback
|
||||
|
||||
| Mode | Good for | Risk |
|
||||
| --- | --- | --- |
|
||||
| Direct | Clients can reach the upstream URL and set required headers | Browsers may block required headers |
|
||||
| SyncTV proxy | Hide upstream credentials, normalize headers, handle Range, or cross client limits | SyncTV carries egress bandwidth and proxy latency |
|
||||
|
||||
Providers explicitly return the headers to use. The proxy does not forward arbitrary client headers to upstream services.
|
||||
|
||||
One playback result can contain direct modes and `proxy_*` modes at the same time. Each Provider decides these modes, the default mode, header exposure, and signed proxy URLs while generating playback info. Shared helpers only generate standard proxy sibling URLs; they do not replace provider-owned playback decisions.
|
||||
|
||||
HTTP and gRPC are transport entry points. They parse paths, query parameters, JSON/protobuf, headers, and streaming bodies, then call `synctv-api/src/impls`. Permissions, playback state, Provider calls, caching, fanout, duration merging, and resource lifecycle handling live in `impls` and core services so both transports share one behavior path.
|
||||
|
||||
## Range and Cache
|
||||
|
||||
Seeking usually depends on HTTP Range. When upstream supports Range, proxy slice cache can cache fixed byte slices. If upstream does not support Range, SyncTV bypasses slice cache and does not write full-file cache entries.
|
||||
|
||||
## Playback Background Workers
|
||||
|
||||
Duration probing and playback auto-advance are driven by local active rooms. A room enters a node's playback background scan set only while the current process has a Realtime connection for that room.
|
||||
|
||||
These workers run on every node so background work follows the real connection lifecycle. When several cluster nodes host the same room, the database provides concurrency safety: duration probes claim work, and auto-advance uses playback state transactions with optimistic versions.
|
||||
|
||||
The worker input set comes from `ConnectionRuntime::active_room_ids()`. Presence hot-room statistics serve room lists, admin views, and metrics. Playback lifecycle workers use the node-local realtime connection set, while database locks, `SKIP LOCKED`, and playback-state version writes converge duplicate cross-node attempts.
|
||||
|
||||
Dynamic playlist background work also stays bound to the current target. Repository queries keep both `room_id = ANY(active_room_ids)` and the current `room_playback_progress.target_hash` join so probing, caching, and auto-advance operate on the item the room is currently playing.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- User playback issues: [Synchronized Playback](../../use/synchronized-playback/) and [User Troubleshooting](../../use/troubleshooting/).
|
||||
- Client implementation: [Client Integration Guide](../../develop/client-integration/).
|
||||
- Proxy cache configuration: [Proxy Slice Cache](../../configuration/proxy-slice-cache/).
|
||||
@ -1,37 +0,0 @@
|
||||
---
|
||||
title: Rooms
|
||||
description: How rooms organize members, playlists, chat, livestreaming, permissions, and current playback.
|
||||
---
|
||||
|
||||
A room is the main workspace in SyncTV. One watching session, a set of members, a playlist, permissions, and current playback state all belong to a room. The controls a user sees depend on room settings and that user's room role.
|
||||
|
||||
## What a Room Contains
|
||||
|
||||
| Item | Purpose |
|
||||
| --- | --- |
|
||||
| Members | Creator, room admins, members, and guests |
|
||||
| Playlist | Media items, child lists, and order |
|
||||
| Current playback | Current media, position, pause state, speed, and version |
|
||||
| Chat | Room messages controlled by permissions and room switches |
|
||||
| Join rules | Visibility, password, review requirement, and member limit |
|
||||
| Permissions | Role defaults and member-level overrides |
|
||||
| Livestream entry | RTMP/live sessions for the room |
|
||||
|
||||
## Who Manages a Room
|
||||
|
||||
Platform administrators and room administrators are different roles. A global `root` or `admin` can maintain the instance, but long-term room responsibility should still be represented through room roles. Use member overrides for exceptions.
|
||||
|
||||
## Common Room States
|
||||
|
||||
| State | User experience | Administration action |
|
||||
| --- | --- | --- |
|
||||
| Open to join | Users can enter from the list or invite | Control default permissions and member limits |
|
||||
| Password required | Users must enter the room password | Rotate leaked passwords |
|
||||
| Review required | Users wait for approval | Approve or reject with a clear reason |
|
||||
| Suspended | Users cannot continue joining or operating | Ban the room or close entry points |
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Users creating or joining rooms: [Create and Join Rooms](../../use/rooms/).
|
||||
- Managing members and settings: [Room and Member Management](../../admin/rooms-members/).
|
||||
- Permission details: [Permissions Model](../permissions/) and [Rooms, Permissions, and Preferences](../../use/rooms-permissions/).
|
||||
@ -1,93 +0,0 @@
|
||||
---
|
||||
title: Documentation Style Guide
|
||||
description: SyncTV documentation rules for information architecture, page types, wording, links, terminology, and locale mirrors.
|
||||
---
|
||||
|
||||
SyncTV docs are organized by reader task. Before writing, decide who the reader is, what they need to finish, and how they can verify the result. Do not mix concepts, step-by-step procedures, field references, and troubleshooting matrices in one page.
|
||||
|
||||
## Page Types
|
||||
|
||||
| Type | Purpose | Write it as |
|
||||
| --- | --- | --- |
|
||||
| Task | Help a reader complete one action | Prerequisites, steps, validation, failure handling |
|
||||
| Concept | Explain a product model or system responsibility | Objects, relationships, responsibilities, and next steps |
|
||||
| Reference | Look up fields, commands, metrics, or errors | Stable, searchable structure; no teaching burden |
|
||||
| Troubleshooting | Diagnose by symptom | Symptom, check first, owner, next step |
|
||||
| Runbook | Admin or operator procedure | Impact, operation order, rollback, validation |
|
||||
|
||||
## Opening Paragraph
|
||||
|
||||
Start by saying what the page helps the reader do. Avoid generic background.
|
||||
|
||||
Use:
|
||||
|
||||
```md
|
||||
This page explains how to create a room, configure join rules, and verify access with a normal member account.
|
||||
```
|
||||
|
||||
Avoid:
|
||||
|
||||
```md
|
||||
This section provides a comprehensive overview of room capabilities and complex boundaries.
|
||||
```
|
||||
|
||||
## Titles
|
||||
|
||||
- Task pages use actions: `Create and Join Rooms`, `Add Media`.
|
||||
- Concept pages use nouns: `Playback Model`, `Permissions Model`.
|
||||
- Reference pages name the object: `Runtime Settings Reference`, `Metrics Catalog`.
|
||||
- Do not use vague labels such as “complete guide” or “best practices”.
|
||||
|
||||
## Wording
|
||||
|
||||
Prefer short sentences and concrete actions.
|
||||
|
||||
| Avoid overusing | Prefer |
|
||||
| --- | --- |
|
||||
| should normally confirm | check |
|
||||
| Related Pages | Next steps, Reference, Continue troubleshooting |
|
||||
| semantics | meaning, impact, rule |
|
||||
| boundary | responsibility, scope, limitation |
|
||||
| production rules | before production, operation rules |
|
||||
|
||||
These words are not banned. Configuration, security, and architecture pages may need them. Do not use them as a page template.
|
||||
|
||||
## Links
|
||||
|
||||
- Put links where the reader needs the next step.
|
||||
- Task pages should end with “Next steps”, not a generic link pile.
|
||||
- Reference pages can keep reference links, but each link should have a clear purpose.
|
||||
- Do not use old `deployment/` or `guides/` routes.
|
||||
- Avoid fragile anchor links into long pages; prefer links to dedicated pages.
|
||||
|
||||
## Terminology
|
||||
|
||||
| Concept | Chinese | English |
|
||||
| --- | --- | --- |
|
||||
| Provider | Provider or 媒体源 Provider | Provider |
|
||||
| Realtime | Realtime or 实时连接 | Realtime |
|
||||
| runtime settings | runtime settings or 运行设置 | runtime settings |
|
||||
| management gRPC | management gRPC or 管理控制面 | management gRPC |
|
||||
| proxy slice cache | proxy slice cache | proxy slice cache |
|
||||
|
||||
Define a term on first use, then keep the same name in that page.
|
||||
|
||||
## Locale Mirrors
|
||||
|
||||
Every Chinese page must have an English mirror under `en/` with the same path. English pages should be rewritten for English product docs, not translated sentence by sentence.
|
||||
|
||||
- Use short sentences.
|
||||
- Use action titles or clear nouns.
|
||||
- Avoid abstract nouns when a concrete action works.
|
||||
- Keep product names stable across locales.
|
||||
|
||||
## Validation
|
||||
|
||||
Run before submitting docs:
|
||||
|
||||
```bash
|
||||
cd docs
|
||||
npm run validate
|
||||
```
|
||||
|
||||
Validation checks internal links, Starlight icons, removed routes, retired titles, unfinished-work markers, and English mirrors. Generic related-page endings are reported as warnings and should be cleaned up over time.
|
||||
@ -1,106 +1,55 @@
|
||||
---
|
||||
title: SyncTV Documentation
|
||||
description: Usage, administration, installation, configuration, operations, and client integration documentation for SyncTV.
|
||||
template: splash
|
||||
hero:
|
||||
tagline: A self-hosted synchronized watching app organized around rooms, playback, chat, media sources, and members.
|
||||
actions:
|
||||
- text: Use SyncTV
|
||||
link: use/
|
||||
icon: rocket
|
||||
variant: primary
|
||||
- text: Install SyncTV
|
||||
link: install/choose-path/
|
||||
icon: approve-check-circle
|
||||
- text: Build a Client
|
||||
link: develop/client-integration/
|
||||
icon: document
|
||||
title: SyncTV Server
|
||||
description: Deploy, configure, and operate SyncTV Server.
|
||||
tableOfContents: false
|
||||
---
|
||||
|
||||
import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
|
||||
import LocaleChoiceTracker from '../../../components/LocaleChoiceTracker.astro';
|
||||
|
||||
<LocaleChoiceTracker />
|
||||
|
||||
<img src="/screenshots/room-macos.png" alt="SyncTV synchronized room playback" />
|
||||
|
||||
Rooms are the daily entry point in SyncTV. Users watch, chat, and switch playlists in rooms. Room administrators manage members and permissions. Platform administrators maintain accounts, reviews, Providers, livestreaming, and runtime policy.
|
||||
|
||||
These docs are organized by task. Start with “Use SyncTV” for the product experience, “Administer SyncTV” for instance management, “Install and Upgrade” for deployment, and “Develop with SyncTV” for client integration.
|
||||
|
||||
Download the native client from [SyncTV App releases](https://github.com/synctv-org/synctv-app/releases/latest).
|
||||
|
||||
## Choose a Path
|
||||
|
||||
<CardGrid>
|
||||
<LinkCard
|
||||
title="Use SyncTV"
|
||||
href="use/"
|
||||
description="Sign in, join rooms, synchronize playback, chat, add media, and manage personal settings."
|
||||
/>
|
||||
<LinkCard
|
||||
title="Administer an Instance"
|
||||
href="admin/"
|
||||
description="Manage users, rooms, reviews, providers, livestreaming, runtime settings, and maintenance tasks."
|
||||
/>
|
||||
<LinkCard
|
||||
title="Install or Upgrade"
|
||||
href="install/choose-path/"
|
||||
description="Choose Compose, source runs, or Helm/Kubernetes and complete production checks."
|
||||
/>
|
||||
<LinkCard
|
||||
title="Build a Client"
|
||||
href="develop/client-integration/"
|
||||
description="Use OpenAPI, gRPC, WebSocket Realtime, tickets, playback info, and errors."
|
||||
/>
|
||||
</CardGrid>
|
||||
|
||||
## Common Tasks
|
||||
|
||||
| Goal | Page |
|
||||
| --- | --- |
|
||||
| Sign in and protect an account | [Sign In and Account Security](use/accounts-security/) |
|
||||
| Create or join a room | [Create and Join Rooms](use/rooms/) |
|
||||
| Fix playback drift or failure | [Synchronized Playback](use/synchronized-playback/) and [User Troubleshooting](use/troubleshooting/) |
|
||||
| Add media | [Add Media](use/media-sources/) |
|
||||
| Manage users, rooms, and reviews | [Administer SyncTV](admin/) |
|
||||
| Start a self-hosted instance | [Quick Start](install/quick-start/) |
|
||||
| Build a client | [Client Integration Guide](develop/client-integration/) |
|
||||
| Join the discussion or see contributors | [Discussion and Contributors](overview/community/) |
|
||||
|
||||
## Understand SyncTV
|
||||
|
||||
<CardGrid>
|
||||
<Card title="Rooms" icon="puzzle">
|
||||
Members, playlists, chat, permissions, and current playback state are organized around rooms. See [Rooms](concepts/rooms/).
|
||||
</Card>
|
||||
<Card title="Synchronized Playback" icon="youtube">
|
||||
The server owns room playback state. Clients follow play, pause, seek, and media changes through Realtime. See [Playback Model](concepts/playback-model/).
|
||||
</Card>
|
||||
<Card title="Media Sources" icon="cloud-download">
|
||||
Providers turn Alist, Emby/Jellyfin, Bilibili, direct URLs, remote services, or live inputs into playable results. See [Media Sources](concepts/media-providers/).
|
||||
</Card>
|
||||
<Card title="Permissions" icon="seti:lock">
|
||||
Global roles, room roles, member overrides, and room settings decide what each person can do. See [Permissions Model](concepts/permissions/).
|
||||
</Card>
|
||||
</CardGrid>
|
||||
|
||||
## Before Production
|
||||
|
||||
<CardGrid>
|
||||
<Card title="Production Checklist" icon="approve-check-circle">
|
||||
Confirm TLS, secrets, PostgreSQL, Redis, backups, metrics, management access, and restore practice.
|
||||
</Card>
|
||||
<Card title="Runtime Boundaries" icon="setting">
|
||||
Understand PostgreSQL, Redis, secrets, management endpoints, media proxying, and non-goals.
|
||||
</Card>
|
||||
<Card title="Configuration Entry" icon="document">
|
||||
Configuration files, environment variables, runtime settings, and CLI overrides have different scopes.
|
||||
</Card>
|
||||
</CardGrid>
|
||||
|
||||
For deployment paths, see [Choose a Deployment Path](install/choose-path/). For runtime dependencies and non-goals, see [Runtime Boundaries](concepts/runtime-boundaries/). For all configuration fields, see [Configuration Index](reference/configuration-index/).
|
||||
|
||||
## License
|
||||
|
||||
SyncTV is licensed under the MIT License. See the repository `LICENSE` file for the full terms.
|
||||
<p class="docs-home-lead">
|
||||
Use Docker Compose on a single host or Helm in an existing Kubernetes cluster. Then configure public access, durable secrets, backups, and monitoring.
|
||||
</p>
|
||||
|
||||
<div class="docs-directory">
|
||||
<section>
|
||||
<h2>Deploy</h2>
|
||||
<ul class="docs-link-list">
|
||||
<li><a href="install/quick-start/"><strong>Install with Docker Compose</strong><span>Server, NAS, or virtual machine</span></a></li>
|
||||
<li><a href="install/helm/"><strong>Install with Helm</strong><span>Kubernetes, Ingress, and multiple replicas</span></a></li>
|
||||
<li><a href="operations/upgrades/"><strong>Upgrade an installation</strong><span>Backup, migrate, and roll back</span></a></li>
|
||||
<li><a href="install/production-checklist/"><strong>Production checklist</strong><span>TLS, secrets, data, and monitoring</span></a></li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<h2>Configure</h2>
|
||||
<ul class="docs-link-list">
|
||||
<li><a href="configuration/how-configuration-works/"><strong>Loading and precedence</strong><span>YAML, environment variables, and secret files</span></a></li>
|
||||
<li><a href="configuration/full-example/"><strong>Configuration examples</strong><span>Minimal production config and full field template</span></a></li>
|
||||
<li><a href="configuration/security/"><strong>Security and secrets</strong><span>JWT, OPAQUE, CORS, and credential encryption</span></a></li>
|
||||
<li><a href="reference/configuration-index/"><strong>Configuration fields</strong><span>Types, defaults, and restart requirements</span></a></li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<h2>Administer and operate</h2>
|
||||
<ul class="docs-link-list">
|
||||
<li><a href="admin/"><strong>Administer SyncTV</strong><span>Users, rooms, permissions, and Providers</span></a></li>
|
||||
<li><a href="operations/observability/"><strong>Monitoring and runbooks</strong><span>Health, metrics, logs, and alerts</span></a></li>
|
||||
<li><a href="operations/backup-restore/"><strong>Backup and restore</strong><span>PostgreSQL, secrets, and recovery drills</span></a></li>
|
||||
<li><a href="operations/troubleshooting/"><strong>Troubleshoot</strong><span>Errors, status codes, and runtime signals</span></a></li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<h2>Develop and reference</h2>
|
||||
<ul class="docs-link-list">
|
||||
<li><a href="develop/local-development/"><strong>Local development</strong><span>Dependencies, databases, tests, and code generation</span></a></li>
|
||||
<li><a href="reference/cli/"><strong>CLI</strong><span>Service control and administration commands</span></a></li>
|
||||
<li><a href="reference/openapi/"><strong>OpenAPI</strong><span>HTTP API specification and client generation</span></a></li>
|
||||
<li><a href="reference/grpc/"><strong>gRPC</strong><span>Public API, management API, and reflection</span></a></li>
|
||||
</ul>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
@ -1,75 +1,32 @@
|
||||
---
|
||||
title: Choose a Deployment Path
|
||||
description: Choose between single-node production Compose, local evaluation, source runs, and Helm/Kubernetes.
|
||||
title: Choose a Deployment
|
||||
description: Compare the infrastructure and operating requirements of Docker Compose and Helm.
|
||||
---
|
||||
|
||||
import { Aside, Steps } from '@astrojs/starlight/components';
|
||||
import Diagram from '../../../../components/Diagram.astro';
|
||||
import deploymentPathDark from '../../../../assets/diagrams/deployment-path-dark.svg';
|
||||
import deploymentPathLight from '../../../../assets/diagrams/deployment-path-light.svg';
|
||||
Docker Compose covers most self-hosted installations. Helm is for platforms that already run Kubernetes, Ingress, and centralized secret management.
|
||||
|
||||
## Paths
|
||||
<table class="deployment-matrix">
|
||||
<thead><tr><th>Requirement</th><th>Docker Compose</th><th>Helm</th></tr></thead>
|
||||
<tbody>
|
||||
<tr><td>Environment</td><td>One Linux server, NAS, or virtual machine</td><td>Existing Kubernetes cluster</td></tr>
|
||||
<tr><td>SyncTV replicas</td><td>One</td><td>One or more</td></tr>
|
||||
<tr><td>PostgreSQL / Redis</td><td>Started by Compose</td><td>In-cluster or managed services</td></tr>
|
||||
<tr><td>TLS entry point</td><td>Existing reverse proxy</td><td>Ingress Controller</td></tr>
|
||||
<tr><td>Secrets</td><td>Local env files</td><td>Kubernetes Secret or an external secret system</td></tr>
|
||||
<tr><td>Installation</td><td><a href="../quick-start/">Docker Compose</a></td><td><a href="../helm/">Helm</a></td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
Use **single-node production Compose** for a long-running instance on one machine. Switch paths only for source changes, temporary local evaluation, or an existing Kubernetes platform.
|
||||
Use the [local development environment](../../develop/local-development/) for source changes. Its Compose file starts development dependencies only.
|
||||
|
||||
<Diagram
|
||||
light={deploymentPathLight}
|
||||
dark={deploymentPathDark}
|
||||
alt="SyncTV deployment path decision diagram choosing single-node production Compose, local evaluation, source run, or Helm based on long-running service, source work, and Kubernetes multi-replica needs."
|
||||
caption="Decide the operating goal first, then open the matching deployment guide."
|
||||
/>
|
||||
## Production Requirements
|
||||
|
||||
## Decision Table
|
||||
Complete these items before serving production traffic:
|
||||
|
||||
| Path | Best for | Startup style | Production fit | Next page |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Single-node production Compose | Self-hosters, small teams, one server | Prebuilt image + `.env.postgres` + `.env.redis` + `.env.synctv` | Default production path | [Quick Start](../../install/quick-start/) |
|
||||
| Local evaluation | Temporary UI or feature preview | `docker-compose.dev.yml` | Not for public or long-running use | [Development Environment](../../develop/local-development/) |
|
||||
| Source run | Developers, API debugging, code changes | Container dependencies + local `cargo +nightly run` | Not a deployment path | [Development Guide](../../develop/local-development/) |
|
||||
| Helm/Kubernetes | Multi-replica or platform teams | Helm values + Kubernetes Secret/PVC/Ingress | Production capable, higher complexity | [Helm Deployment](../helm/) |
|
||||
- Persistent PostgreSQL data and tested backups.
|
||||
- Durable JWT, OPAQUE, and credential-encryption secrets.
|
||||
- HTTPS on public entry points.
|
||||
- Shared PostgreSQL, Redis, and cluster secrets for multiple replicas.
|
||||
- A backup and migration check before upgrades.
|
||||
|
||||
## Single-Node Production Compose
|
||||
|
||||
Choose it if any of these are true:
|
||||
|
||||
- You have one server, NAS, or VM.
|
||||
- You want the shortest path to a long-running SyncTV instance.
|
||||
- You do not want to start with Kubernetes, Ingress controllers, PVCs, or Secret operators.
|
||||
- You can manage PostgreSQL backups and a few long-lived secrets.
|
||||
|
||||
Success signals:
|
||||
|
||||
- `.env.postgres`, `.env.redis`, and `.env.synctv` are persisted and backed up.
|
||||
- `make compose-config` passes.
|
||||
- `/health/ready` returns 200.
|
||||
- The root user can log in.
|
||||
- PostgreSQL has a backup plan.
|
||||
|
||||
Execution path:
|
||||
|
||||
1. [Quick Start](../../install/quick-start/): download Compose files, generate env files, set the root password, and start the service.
|
||||
2. [Docker Compose Deployment](../docker-compose/): review production Compose, development Compose, volumes, and ports.
|
||||
3. [Production Checklist](../production-checklist/): verify TLS, secrets, backups, metrics, alerts, and upgrade strategy.
|
||||
|
||||
## Exception Paths
|
||||
|
||||
| Scenario | Path | Boundary |
|
||||
| --- | --- | --- |
|
||||
| Temporary evaluation | Local evaluation | Fast startup with generated local env files; keep it off the public internet and do not run it long term. |
|
||||
| Source changes | Source run | PostgreSQL and Redis can come from development Compose while SyncTV runs from the local Rust toolchain. |
|
||||
| Existing Kubernetes platform | Helm | Decide HTTP/gRPC Ingress, Secret, PVC, metrics, Redis, HLS storage, and rolling updates first. |
|
||||
| Multi-replica realtime | Helm or self-managed multi-replica | All replicas must share PostgreSQL, Redis, `redis.key_prefix`, and `cluster.secret`. |
|
||||
|
||||
## Decision Rules
|
||||
|
||||
<Steps>
|
||||
1. If it faces users, do not use development Compose.
|
||||
2. If it runs long term, back up PostgreSQL and production secrets.
|
||||
3. If it runs multiple replicas, share PostgreSQL, Redis, `redis.key_prefix`, and `cluster.secret`.
|
||||
4. If HLS runs across replicas, choose publisher-node proxying, `shared_file`, or OSS explicitly.
|
||||
5. If the management plane uses TCP, configure a token and keep it away from normal public entrypoints.
|
||||
</Steps>
|
||||
|
||||
<Aside type="tip">
|
||||
When unsure, choose single-node production Compose. It is the smallest production loop and can still be migrated to Helm or another orchestrator later.
|
||||
</Aside>
|
||||
The [Production Checklist](../production-checklist/) contains the full set of checks. Follow [Upgrades and Migrations](../../operations/upgrades/) for an existing installation.
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Runtime Boundaries
|
||||
description: PostgreSQL, Redis, secrets, management endpoints, metrics, media proxying, and SyncTV non-goals.
|
||||
title: Deployment and Runtime Boundaries
|
||||
description: PostgreSQL, Redis, secrets, management endpoints, metrics, media proxying, and production deployment boundaries.
|
||||
---
|
||||
|
||||
SyncTV is an application service. It is not a database, object store, media library, CDN, or public management platform. Confirm these boundaries before production deployment.
|
||||
@ -1,142 +0,0 @@
|
||||
---
|
||||
title: Common Workflows
|
||||
description: Task-oriented SyncTV workflows for users, room administrators, platform administrators, developers, and operators.
|
||||
---
|
||||
|
||||
import { Aside, Steps, TabItem, Tabs } from '@astrojs/starlight/components';
|
||||
|
||||
## Choose the Goal
|
||||
|
||||
Start from the goal you are handling. These workflows keep the operating order; field, API, and configuration details live in the linked topic pages.
|
||||
|
||||
<Aside type="tip">
|
||||
After the first production deployment, use the launch validation workflow. For support cases, start with the user troubleshooting workflow.
|
||||
</Aside>
|
||||
|
||||
## User Workflows
|
||||
|
||||
<Tabs syncKey="user-workflows-en">
|
||||
<TabItem label="Start watching" icon="youtube">
|
||||
<Steps>
|
||||
1. Sign in and confirm email, 2FA, or OAuth2 status.
|
||||
2. Create a room or open an existing room entry point.
|
||||
3. Submit a password or join review if the room requires it.
|
||||
4. Add media or choose an existing playlist item.
|
||||
5. Start playback if you have permission, otherwise wait for a room administrator.
|
||||
6. If playback fails, refresh the playback info and check whether proxy playback is required.
|
||||
</Steps>
|
||||
</TabItem>
|
||||
<TabItem label="Enable 2FA" icon="seti:lock">
|
||||
<Steps>
|
||||
1. Make sure at least two local factors are available: password, passkey, verified email.
|
||||
2. Bind a passkey or verify email.
|
||||
3. Enable 2FA.
|
||||
4. Sign out and sign in once to verify the second factor.
|
||||
5. Do not remove factors until at least two local methods remain.
|
||||
</Steps>
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Room Administrator Workflows
|
||||
|
||||
### Create a Controlled Room
|
||||
|
||||
<Steps>
|
||||
1. Create a room with a clear name and description.
|
||||
2. Set a room password if needed.
|
||||
3. Enable `requireApproval` for semi-public rooms.
|
||||
4. Set `maxMembers` according to service and upstream Provider capacity.
|
||||
5. Review member and guest default permissions.
|
||||
6. Join once with a normal account to validate the path.
|
||||
</Steps>
|
||||
|
||||
### Handle Member Issues
|
||||
|
||||
| Goal | Action | Note |
|
||||
| --- | --- | --- |
|
||||
| Temporary mute | Remove `send_chat_messages` from the member | Lower impact than disabling chat room-wide |
|
||||
| Grant playback control | Add `control_playback_state` | Add `navigate_playback` for media switching |
|
||||
| Remove disruptive member | Kick the member or platform-ban the user | Room ban is not a platform ban |
|
||||
| Long-term responsibility | Adjust role or defaults | Avoid large stacks of personal overrides |
|
||||
|
||||
See [Permissions Model](../../concepts/permissions/) and [Rooms, Permissions, and Preferences](../../use/rooms-permissions/) for details.
|
||||
|
||||
## Platform Administrator Workflows
|
||||
|
||||
### Launch Validation
|
||||
|
||||
<Steps>
|
||||
1. Follow the [Production Checklist](../../install/production-checklist/) for secrets, database, Redis, TLS, and backups.
|
||||
2. Run `synctv config validate --strict`.
|
||||
3. Check `/health/ready`.
|
||||
4. Sign in as root, create a normal user, and create a test room.
|
||||
5. Validate WebSocket, chat, playback control, Provider browse, and proxy playback.
|
||||
6. Enable metrics and confirm scraping.
|
||||
7. Perform a PostgreSQL and secret restore drill.
|
||||
</Steps>
|
||||
|
||||
### Add a Media Provider
|
||||
|
||||
<Steps>
|
||||
1. Decide between a local Provider and a remote Provider instance.
|
||||
2. Configure or create the Provider instance and ensure credential encryption is configured.
|
||||
3. Test login, browse, search, and playback with an administrator.
|
||||
4. Test both direct and proxy playback.
|
||||
5. For Range-capable upstreams, verify seek and slice cache behavior.
|
||||
6. Give users a clear default Provider or usage guidance.
|
||||
</Steps>
|
||||
|
||||
See [Add Media](../../use/media-sources/).
|
||||
|
||||
## Developer Workflows
|
||||
|
||||
### Bring Up a Client
|
||||
|
||||
<Steps>
|
||||
1. Read [Client Integration Guide](../../develop/client-integration/) for HTTP, gRPC, and WebSocket boundaries.
|
||||
2. Start the service with OpenAPI and export `/api-docs/openapi.json`.
|
||||
3. Generate an SDK or write minimal requests.
|
||||
4. Implement login and refresh token handling.
|
||||
5. Create a WebSocket ticket and connect to `/ws/rooms/{roomId}`.
|
||||
6. Use [Realtime API](../../develop/realtime-api/) to observe playback state, playback info, room settings, and members.
|
||||
7. Handle `status`, `code`, `requestId`, and `Retry-After` using [Errors](../../reference/errors/).
|
||||
</Steps>
|
||||
|
||||
### Add or Change an API
|
||||
|
||||
<Steps>
|
||||
1. Choose HTTP/OpenAPI, gRPC, or Realtime.
|
||||
2. Update proto or handler while keeping errors and permissions consistent.
|
||||
3. Add tests and update OpenAPI or protobuf documentation.
|
||||
4. Update [SDK and API Examples](../../develop/sdk-and-api-examples/), [Realtime API](../../develop/realtime-api/), or [gRPC Debugging](../../reference/grpc/).
|
||||
5. If protocol behavior changes, update [API and Protobuf Evolution](../../reference/api-versioning/).
|
||||
</Steps>
|
||||
|
||||
## Operator Workflows
|
||||
|
||||
### Capacity or Performance Issue
|
||||
|
||||
<Steps>
|
||||
1. Inspect HTTP, WebSocket, database, cache, Provider, livestream, and cluster metrics.
|
||||
2. Use [Capacity Planning](../../operations/capacity-planning/) to identify connection, database, Redis, Provider, bandwidth, or storage bottlenecks.
|
||||
3. Reduce upstream pressure with Redis, slice cache, member limits, and connection limits.
|
||||
4. In multi-replica mode, confirm shared PostgreSQL, Redis, and consistent secrets.
|
||||
5. Record version, deployment shape, key metrics, and logs before using [Troubleshooting](../../operations/troubleshooting/).
|
||||
</Steps>
|
||||
|
||||
### Rotate Secrets
|
||||
|
||||
<Steps>
|
||||
1. Read [Security Hardening and Rotation](../../operations/security-hardening-and-rotation/).
|
||||
2. Separate directly rotatable tokens from JWT, OPAQUE setup secret, and credential encryption key.
|
||||
3. Back up old secrets.
|
||||
4. Validate login, Provider decryption, WebSocket, OAuth2, and WebAuthn in a test environment.
|
||||
5. Deploy during a quiet window and watch error rates.
|
||||
</Steps>
|
||||
|
||||
## Continue Reading
|
||||
|
||||
- [Use SyncTV](../../use/)
|
||||
- [Administer SyncTV](../../admin/)
|
||||
- [SDK and API Examples](../../develop/sdk-and-api-examples/)
|
||||
- [Observability Runbook](../../operations/observability/)
|
||||
@ -1,20 +0,0 @@
|
||||
---
|
||||
title: Discussion and Contributors
|
||||
description: Join the SyncTV discussion and see contributors across the server and app projects.
|
||||
---
|
||||
|
||||
This page links to the public SyncTV discussion and recognizes contributors across the server and app projects.
|
||||
|
||||
## Join the Discussion
|
||||
|
||||
Join the [SyncTV Telegram discussion](https://t.me/synctv) to talk about deployment, operations, playback, media providers, client development, and product ideas.
|
||||
|
||||
Messages in the public group are visible to other members. Remove passwords, tokens, cookies, private URLs, and personal data before sharing logs, screenshots, or configuration.
|
||||
|
||||
## Contributors
|
||||
|
||||
This contributor image combines the `synctv-org/synctv` server and `synctv-org/synctv-app` client repositories.
|
||||
|
||||
|
||||
|
||||
Submit code through the Pull Request workflow in the relevant repository: [SyncTV Server](https://github.com/synctv-org/synctv) or [SyncTV App](https://github.com/synctv-org/synctv-app).
|
||||
@ -1,88 +0,0 @@
|
||||
---
|
||||
title: Documentation Map
|
||||
description: Role-based and product-task entry points for SyncTV documentation.
|
||||
---
|
||||
|
||||
import { LinkCard, CardGrid } from '@astrojs/starlight/components';
|
||||
|
||||
## Start by Role
|
||||
|
||||
<CardGrid>
|
||||
<LinkCard
|
||||
title="Users"
|
||||
href="../../use/"
|
||||
description="Sign in, create or join rooms, synchronize playback, chat, add media, and manage personal settings."
|
||||
/>
|
||||
<LinkCard
|
||||
title="Administrators"
|
||||
href="../../admin/"
|
||||
description="Manage users, rooms, members, reviews, Providers, runtime settings, and maintenance."
|
||||
/>
|
||||
<LinkCard
|
||||
title="Deployers"
|
||||
href="../../install/choose-path/"
|
||||
description="Choose single-node Compose, source runs, or Helm/Kubernetes and complete launch checks."
|
||||
/>
|
||||
<LinkCard
|
||||
title="Client Developers"
|
||||
href="../../develop/client-integration/"
|
||||
description="Use authentication, HTTP/gRPC, WebSocket Realtime, playback info, Provider APIs, and errors."
|
||||
/>
|
||||
<LinkCard
|
||||
title="Operators"
|
||||
href="../../operations/troubleshooting/"
|
||||
description="Validate config, observe health, plan capacity, back up, upgrade, rotate secrets, and handle incidents."
|
||||
/>
|
||||
<LinkCard
|
||||
title="Reference Lookup"
|
||||
href="../../reference/configuration-index/"
|
||||
description="Look up configuration fields, environment variables, CLI commands, runtime settings, metrics, errors, and limits."
|
||||
/>
|
||||
</CardGrid>
|
||||
|
||||
## Product Tasks
|
||||
|
||||
| Task | Start | Next pages |
|
||||
| --- | --- | --- |
|
||||
| Sign in and secure an account | [Sign In and Account Security](../../use/accounts-security/) | [Authentication and Security Model](../../admin/authentication-security/), [WebAuthn and Passkeys](../../configuration/webauthn/) |
|
||||
| Create or join rooms | [Create and Join Rooms](../../use/rooms/) | [Rooms](../../concepts/rooms/), [Rooms, Permissions, and Preferences](../../use/rooms-permissions/) |
|
||||
| Configure room permissions | [Permissions Model](../../concepts/permissions/) | [Room and Member Management](../../admin/rooms-members/) |
|
||||
| Add and play media | [Add Media](../../use/media-sources/) | [Provider User Guide](../../use/provider-guide/), [Playback Model](../../concepts/playback-model/) |
|
||||
| Enable livestreaming | [Add Media](../../use/media-sources/) | [Livestream Configuration](../../configuration/livestream/) |
|
||||
| Integrate a client | [Client Integration Guide](../../develop/client-integration/) | [SDK and API Examples](../../develop/sdk-and-api-examples/), [Realtime API](../../develop/realtime-api/) |
|
||||
| Change shared implementation behavior | [Implementation Contracts](../../develop/implementation-contracts/) | [Cache Consistency Development Guide](../../develop/cache-consistency/), [Playback Background Workers](../../concepts/playback-background-workers/) |
|
||||
| Add or extend a Provider | [Provider Development Guide](../../develop/provider-development/) | [Implementation Contracts](../../develop/implementation-contracts/), [OpenAPI](../../reference/openapi/), [gRPC](../../reference/grpc/) |
|
||||
| Support user issues | [User Troubleshooting](../../use/troubleshooting/) | [Troubleshooting](../../operations/troubleshooting/) |
|
||||
|
||||
## Install and Maintain
|
||||
|
||||
| Goal | Start | Next pages |
|
||||
| --- | --- | --- |
|
||||
| Self-host one node | [Quick Start](../../install/quick-start/) | [Docker Compose Deployment](../../install/docker-compose/), [Production Checklist](../../install/production-checklist/) |
|
||||
| Deploy on Kubernetes | [Helm Deployment](../../install/helm/) | [Cluster Configuration](../../configuration/cluster/), [Observability Runbook](../../operations/observability/) |
|
||||
| Change configuration | [How Configuration Works](../../configuration/how-configuration-works/) | [Configuration Index](../../reference/configuration-index/), [Environment Variables](../../reference/environment-variables/) |
|
||||
| Back up and restore | [Backup and Restore](../../operations/backup-restore/) | [Data, Privacy, and Retention](../../operations/data-retention/) |
|
||||
| Upgrade or release | [Upgrades and Migrations](../../operations/upgrades/) | [Release Process](../../operations/release/) |
|
||||
| Handle incidents | [Troubleshooting](../../operations/troubleshooting/) | [Metrics Catalog](../../reference/metrics-catalog/), [Capacity Planning](../../operations/capacity-planning/) |
|
||||
|
||||
## Configuration Topics
|
||||
|
||||
1. [How Configuration Works](../../configuration/how-configuration-works/)
|
||||
2. [Security and Secrets](../../configuration/security/)
|
||||
3. [Database and Redis](../../configuration/database-and-redis/)
|
||||
4. [Server Listener and Runtime Paths](../../configuration/server-and-runtime/)
|
||||
5. Continue with WebAuthn, email/OAuth2, providers, livestreaming, metrics, and cluster pages as features are enabled.
|
||||
|
||||
## Reference Lookup
|
||||
|
||||
| Reference | Use |
|
||||
| --- | --- |
|
||||
| [Configuration Index](../../reference/configuration-index/) | Static configuration fields |
|
||||
| [Environment Variables](../../reference/environment-variables/) | Environment variable to config field mapping |
|
||||
| [Runtime Settings](../../reference/runtime-settings/) | Hot-reloadable database settings |
|
||||
| [CLI Reference](../../reference/cli/) | Management commands |
|
||||
| [OpenAPI](../../reference/openapi/) | HTTP API JSON and Swagger UI |
|
||||
| [gRPC](../../reference/grpc/) | gRPC debugging entrypoint |
|
||||
| [Metrics Catalog](../../reference/metrics-catalog/) | Prometheus metric names and labels |
|
||||
| [Errors](../../reference/errors/) | HTTP, gRPC, Realtime, and Provider errors |
|
||||
| [Limitations and Non-goals](../../reference/limitations/) | Current design boundaries and non-goals |
|
||||
@ -1,49 +0,0 @@
|
||||
---
|
||||
title: Sign In and Account Security
|
||||
description: How users sign in to SyncTV and safely use passwords, OPAQUE, passkeys, email, OAuth2, and 2FA.
|
||||
---
|
||||
|
||||
import { Aside, Steps } from '@astrojs/starlight/components';
|
||||
|
||||
SyncTV can enable several sign-in methods. The methods shown in the UI depend on administrator configuration.
|
||||
|
||||
## Sign-In Methods
|
||||
|
||||
| Method | Requires | Good for |
|
||||
| --- | --- | --- |
|
||||
| OPAQUE password login | Local password | Public client local password login without storing direct password-verifier equivalents |
|
||||
| Direct password login | Username or email and password | Restricted environments where an OPAQUE client is unavailable while the server still stores and verifies OPAQUE credentials |
|
||||
| Passkey/WebAuthn | Browser, OS account, or security key | Passwordless sign-in or second factor |
|
||||
| Email code | A reachable verified email address | Sign-in, verification, recovery, or MFA |
|
||||
| OAuth2/OIDC | Third-party account | GitHub, Google, Logto, or generic OIDC |
|
||||
|
||||
## Before Enabling 2FA
|
||||
|
||||
Make sure you have at least two local verification methods: local password, passkey/WebAuthn, or verified email. OAuth2 does not count as a local 2FA factor.
|
||||
|
||||
<Aside type="caution">
|
||||
Do not keep only one passkey and remove password or verified email. Device loss, browser profile damage, or passkey sync issues can block account recovery.
|
||||
</Aside>
|
||||
|
||||
## When a Second Factor Is Required
|
||||
|
||||
<Steps>
|
||||
1. Complete the first factor: OPAQUE password login, direct password login, passkey, email sign-in, or OAuth2.
|
||||
2. If SyncTV asks for 2FA, choose one of the available second factors.
|
||||
3. Complete email code or passkey/WebAuthn.
|
||||
4. After signing in, confirm that at least two local verification methods remain available.
|
||||
</Steps>
|
||||
|
||||
Public client local password login prefers OPAQUE. Direct password login serves restricted environments where the OPAQUE exchange is unavailable; the server immediately creates or verifies OPAQUE credentials from the submitted password.
|
||||
|
||||
## Account Issues
|
||||
|
||||
| Symptom | Check first |
|
||||
| --- | --- |
|
||||
| Password login fails | Username, password, account ban, 2FA requirement |
|
||||
| Email code does not arrive | Address, spam folder, verified email, SMTP availability |
|
||||
| OAuth2 callback does not sign in | Registration review, existing binding, callback URL |
|
||||
| Passkey is unavailable | Browser, OS account, security key, current domain |
|
||||
| 2FA blocks access | Whether two local verification methods still exist |
|
||||
|
||||
When reporting a problem, include time, username, sign-in method, error text, and `requestId`. Do not send passwords, tokens, cookies, OAuth2 codes, or verification codes.
|
||||
@ -1,24 +0,0 @@
|
||||
---
|
||||
title: Chat
|
||||
description: How users use room chat and identify mute, disabled chat, or Realtime problems.
|
||||
---
|
||||
|
||||
Chat is a room realtime feature. Sending messages depends on room settings and the user's `send_chat_messages` permission.
|
||||
|
||||
## Common States
|
||||
|
||||
| Symptom | Possible cause | What to do |
|
||||
| --- | --- | --- |
|
||||
| Can read but not send | Chat disabled, muted, or missing `send_chat_messages` | Contact a room administrator |
|
||||
| Others do not see a sent message | Realtime disconnected, rate limited, or room state issue | Re-enter the room and record the time |
|
||||
| Only you miss new messages | Browser network, proxy, or WebSocket issue | Refresh or change network |
|
||||
| Everyone misses messages | Server Realtime, Ingress, or cluster event issue | Ask an administrator to inspect runtime state |
|
||||
|
||||
## Good Practices
|
||||
|
||||
- To quiet the whole room, ask a room administrator to disable chat.
|
||||
- To restrict one user, use member permissions instead of changing room defaults.
|
||||
- Do not send passwords, tokens, cookies, Provider credentials, or OAuth2 codes in chat.
|
||||
- When reporting problems, provide room ID, time, a summary of the message, and error text.
|
||||
|
||||
Protocol details are covered in [Realtime API](../../develop/realtime-api/).
|
||||
@ -1,31 +0,0 @@
|
||||
---
|
||||
title: Use SyncTV
|
||||
description: User documentation for signing in, joining rooms, synchronized playback, chatting, adding media, notifications, and troubleshooting.
|
||||
---
|
||||
|
||||
import { LinkCard, CardGrid } from '@astrojs/starlight/components';
|
||||
|
||||
To start a synchronized playback session, begin with “Create and Join Rooms”. Account, playback, chat, media, notifications, and troubleshooting each have their own page.
|
||||
|
||||
<CardGrid>
|
||||
<LinkCard title="Sign In and Account Security" href="./accounts-security/" description="Use password, OPAQUE, passkeys, email, OAuth2, and 2FA safely." />
|
||||
<LinkCard title="Create and Join Rooms" href="./rooms/" description="Join public rooms, enter passwords, submit reviews, create rooms, and understand join failures." />
|
||||
<LinkCard title="Synchronized Playback" href="./synchronized-playback/" description="Follow room playback state, use playback controls, handle seek, media changes, and drift." />
|
||||
<LinkCard title="Chat" href="./chat/" description="Use room chat and understand mute, disabled chat, and Realtime issues." />
|
||||
<LinkCard title="Add Media" href="./media-sources/" description="Add direct URLs, Alist, Emby/Jellyfin, Bilibili, remote Providers, and live entries." />
|
||||
<LinkCard title="Notifications and Preferences" href="./preferences-notifications/" description="Manage notification preferences, default Provider, linked login methods, and security preferences." />
|
||||
<LinkCard title="User Troubleshooting" href="./troubleshooting/" description="Diagnose account, room, playback, chat, media, and notification issues by symptom." />
|
||||
</CardGrid>
|
||||
|
||||
## Core Objects
|
||||
|
||||
| Object | Where users see it | Common symptoms |
|
||||
| --- | --- | --- |
|
||||
| Account | Sign-in, personal settings, notifications, security checks | Login failure, unavailable 2FA, unverified email |
|
||||
| Room | Room list, room entry points, playback page | Cannot join, password required, waiting for review |
|
||||
| Playlist | Media queue inside a room | Media missing, cannot add, order changed |
|
||||
| Current playback | Player and sync state | Out of sync, switch failed, URL expired |
|
||||
| Chat | Room sidebar | Cannot send, messages not syncing, chat disabled |
|
||||
| Provider | Media source and playback origin | Expired credentials, unsupported direct headers, slow proxy |
|
||||
|
||||
For the product model, see [Rooms](../concepts/rooms/), [Playback Model](../concepts/playback-model/), and [Permissions Model](../concepts/permissions/).
|
||||
@ -1,137 +0,0 @@
|
||||
---
|
||||
title: Add Media
|
||||
description: Add direct URLs, Alist, Emby/Jellyfin, Bilibili, RTMP livestreaming, and remote Provider media.
|
||||
---
|
||||
|
||||
import { Aside, Steps, TabItem, Tabs } from '@astrojs/starlight/components';
|
||||
|
||||
See the [Provider User Guide](../provider-guide/) for binding, preview, dynamic-playlist, and advanced playback capabilities across video platforms, media servers, and NAS systems.
|
||||
|
||||
## Choose a Source
|
||||
|
||||
Provider is the adapter layer that turns external media into SyncTV playback results. Before integrating, answer:
|
||||
|
||||
| Question | Why it matters |
|
||||
| --- | --- |
|
||||
| Can the client access the media directly? | Decides direct play versus proxy |
|
||||
| Does the upstream require special headers or cookies? | Decides whether browsers can direct play |
|
||||
| Are credentials user-owned or instance-owned? | Decides user binding, Provider instance, and encryption |
|
||||
|
||||
Built-in Providers cover video and live platforms, media servers, file services, NAS systems, direct URLs, and livestream sources. A remote Provider instance is stored in the database and connects SyncTV to a separate Provider service.
|
||||
|
||||
## Before Adding Media
|
||||
|
||||
<Steps>
|
||||
1. Configure `security.credential_encryption_key` or `_file`.
|
||||
2. Confirm local Provider timeouts: `media_providers.<type>.request_timeout_seconds` and `connect_timeout_seconds`.
|
||||
3. Create a remote Provider instance through management APIs or CLI if needed.
|
||||
4. Test login, browse, search, parse, and playback with an administrator.
|
||||
5. Test direct playback, proxy playback, and Range seek.
|
||||
6. Watch Provider error rate, proxy errors, slice cache hits, and upstream status.
|
||||
</Steps>
|
||||
|
||||
<Aside type="caution">
|
||||
Do not put Provider tokens, cookies, passwords, or API keys in client logs, URL queries, or media `sourceConfig`. Credentials should be resolved by the server-side Provider credential layer.
|
||||
</Aside>
|
||||
|
||||
## Source Recipes
|
||||
|
||||
<Tabs syncKey="provider-recipes-en">
|
||||
<TabItem label="Alist" icon="seti:folder">
|
||||
**Use for**: mounted drives, directories, file browse, and search.
|
||||
|
||||
**Focus**:
|
||||
|
||||
- Login, list directories, search, choose a file, and add it to a playlist.
|
||||
- Upstream URLs may require a specific `User-Agent`.
|
||||
- If the browser cannot set required headers, use proxy playback.
|
||||
- Large directories should use pagination, search, and caching.
|
||||
|
||||
**Validate**: listing works, search works, either direct or proxy playback works, and seek does not produce continuous 4xx/5xx.
|
||||
</TabItem>
|
||||
<TabItem label="Emby/Jellyfin" icon="puzzle">
|
||||
**Use for**: existing media libraries, shows, subtitles, and transcoding.
|
||||
|
||||
**Focus**:
|
||||
|
||||
- Playback results may include multiple modes, subtitles, and metadata.
|
||||
- Clients should use `default_mode` and `PlaybackClientProfile`.
|
||||
- Unsupported codecs or containers should request transcoding or a compatible result.
|
||||
- Server URL, account, and TLS policy must be managed explicitly.
|
||||
|
||||
**Validate**: library listing, playback URLs, subtitles, and direct/transcode modes work with client capabilities.
|
||||
</TabItem>
|
||||
<TabItem label="Bilibili" icon="youtube">
|
||||
**Use for**: parsing Bilibili videos with QR or SMS credentials.
|
||||
|
||||
**Focus**:
|
||||
|
||||
- Sensitive to `Referer`, `User-Agent`, cookies, and Range.
|
||||
- Direct and proxy headers must match Provider output.
|
||||
- Expired credentials should ask the user to log in again.
|
||||
- Upstream rate limits or CDN changes may look like temporary Provider failures.
|
||||
|
||||
**Validate**: parse succeeds, proxy requests include required headers, seek works, and credential expiry is understandable.
|
||||
</TabItem>
|
||||
<TabItem label="Direct URL" icon="external">
|
||||
**Use for**: stable URLs, public object storage links, or internal media addresses.
|
||||
|
||||
**Focus**:
|
||||
|
||||
- Direct play only works when the client can access the URL.
|
||||
- If the URL is server-network-only, use proxy.
|
||||
- Prefer upstreams that support Range.
|
||||
- Signed URLs require playback info refresh before expiry.
|
||||
|
||||
**Validate**: the client can GET/Range the URL, or SyncTV proxy can access it.
|
||||
</TabItem>
|
||||
<TabItem label="RTMP/Live" icon="youtube">
|
||||
**Use for**: room livestream publishing and HLS/FLV playback.
|
||||
|
||||
**Focus**:
|
||||
|
||||
- RTMP is a publish entry, not a normal VOD Provider.
|
||||
- The member needs `manage_live_streams` permission to manage live streams and create publish keys.
|
||||
- Multi-replica deployments need a clear HLS backend: publisher-node proxy, `shared_file`, or OSS.
|
||||
- Live paths depend more on ports, storage, and connection drain.
|
||||
|
||||
**Validate**: publish key creation, RTMP publish, HLS/FLV playback, and no random 404s in multi-replica mode.
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Local and Remote Providers
|
||||
|
||||
| Mode | Configuration | Use case |
|
||||
| --- | --- | --- |
|
||||
| Local built-in Provider | `media_providers` YAML timeouts | SyncTV directly accesses upstream Providers |
|
||||
| Provider instance | Management API/CLI, stored in database | Multiple instances, credentials, or remote services |
|
||||
| Remote Provider | Instance `endpoint`, `tls`, `jwt_secret`, etc. | Separate Provider capability or network boundary |
|
||||
|
||||
Configuration needed by the remote Provider to access upstream media belongs to that remote service, not the SyncTV `media_providers` object.
|
||||
|
||||
## Credentials and Security
|
||||
|
||||
- Use `security.credential_encryption_key_file`.
|
||||
- Make credential ownership explicit: user, instance, or remote Provider service.
|
||||
- Never write cookies, tokens, API keys, or passwords into `sourceConfig`, URL query, logs, or screenshots.
|
||||
- Before rotation, confirm whether credentials are referenced by playlists, provider credentials, or remote instances.
|
||||
|
||||
See [Security Hardening and Rotation](../../operations/security-hardening-and-rotation/).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Check first |
|
||||
| --- | --- |
|
||||
| Browse works but playback fails | Playback URL, headers, proxy mode, upstream Range |
|
||||
| Direct works but proxy fails | Headers sent to proxy and whether upstream blocks server IP |
|
||||
| Proxy works but direct fails | Browser header restrictions, CORS, client network |
|
||||
| Bilibili intermittent 403 | Cookie, Referer, User-Agent, CDN behavior |
|
||||
| Multi-replica live 404 | Publisher node, HLS backend, shared storage, OSS |
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Media Sources](../../concepts/media-providers/)
|
||||
- [Playback Model](../../concepts/playback-model/)
|
||||
- [Media Providers](../../configuration/media-providers/)
|
||||
- [Proxy Slice Cache](../../configuration/proxy-slice-cache/)
|
||||
- [Livestream Configuration](../../configuration/livestream/)
|
||||
@ -1,32 +0,0 @@
|
||||
---
|
||||
title: Notifications and Preferences
|
||||
description: Manage notification preferences, linked login methods, and security preferences.
|
||||
---
|
||||
|
||||
Personal settings affect only the current user. Administrators configure platform capabilities such as SMTP, OAuth2 providers, Provider instances, and registration policy. User preferences decide how you use those capabilities.
|
||||
|
||||
## Common Settings
|
||||
|
||||
| Setting | Affects |
|
||||
| --- | --- |
|
||||
| Notification preferences | Room invitations, room events, system announcements, in-app and email delivery |
|
||||
| Linked methods | Password, passkey/WebAuthn, email, OAuth2 bindings |
|
||||
| 2FA | Whether local sign-in requires a second factor |
|
||||
| Email status | Verification, recovery, and MFA email availability |
|
||||
|
||||
Provider instance bindings are stored on provider credentials created during provider login, not in user preferences.
|
||||
|
||||
## Missing Notifications
|
||||
|
||||
| Symptom | Check first |
|
||||
| --- | --- |
|
||||
| No email | Verified address, notification preference, spam folder |
|
||||
| No in-app notification | Disabled category or already-read notification |
|
||||
| One category missing | Whether that room or system event actually happened |
|
||||
| Nobody receives email | Administrator should check SMTP configuration and delivery logs |
|
||||
|
||||
## Security Preferences
|
||||
|
||||
Before changing login methods, make sure you can complete the next sign-in. After enabling 2FA, do not remove local methods until only one remains. OAuth2 can be convenient, but it does not count as a local 2FA factor.
|
||||
|
||||
For account details, see [Sign In and Account Security](../accounts-security/).
|
||||
@ -1,163 +0,0 @@
|
||||
---
|
||||
title: Provider User Guide
|
||||
description: Bind accounts, preview resources, create dynamic playlists, and use video, media-server, and NAS Providers.
|
||||
---
|
||||
|
||||
import { Aside, Steps } from '@astrojs/starlight/components';
|
||||
|
||||
SyncTV Providers convert external platforms, media servers, and NAS resources into playable media. The App consumes typed source configs, covers, thumbnails, subtitles, danmaku, quality modes, and proxy URLs returned by each Provider.
|
||||
|
||||
## Common Workflow
|
||||
|
||||
<Steps>
|
||||
|
||||
1. Open **Platform Bindings** in the App account center and select a Provider and Provider instance.
|
||||
2. Sign in, scan a code, or provide the Cookie, token, or API key required by that Provider.
|
||||
3. Open the room media library, choose Add Media, and select the Provider.
|
||||
4. Enter a URL or resource ID, or use discovery features such as categories, search, favorites, history, or folder browsing.
|
||||
5. Preview the source. Every result carries a typed media or playlist source config that can be submitted directly.
|
||||
6. Add one media item, select part of the preview, or create a dynamic playlist.
|
||||
7. During playback, choose an available quality, direct mode, or proxy mode from the Provider result.
|
||||
|
||||
</Steps>
|
||||
|
||||
A `Provider instance` identifies where resolution runs. The default instance runs inside the SyncTV server; administrators can also configure remote instances. Credentials, saved sources, and playback requests retain that instance binding.
|
||||
|
||||
`Use room owner credential` binds the source to the room owner's Provider credential. It is useful for personal favorites, history, followed lists, and private libraries. The personal mode uses the requesting user's credential.
|
||||
|
||||
## Capability Matrix
|
||||
|
||||
| Provider | Binding | Single media | Dynamic playlists and browsing | Playback features |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Bilibili | QR code or SMS | Videos, multi-part videos, PGC episodes, live rooms | Popular, recommendations, UP videos, favorites, collections, series, watch later, history, follows, PGC timeline/index, live home/follows/areas | DASH, qualities, subtitles, danmaku, covers, part thumbnails |
|
||||
| Twitch | OAuth access token; Followed Live requires `user:read:follows` | Live, VOD, Clip | Channel Videos/Highlights/Uploads/Clips, followed live, category live, live search | HLS qualities, chapters, storyboard, chat, schedule |
|
||||
| YouTube | Public access is anonymous; optional Visitor Data, PO Token, Cookie | Videos, Shorts, live | Playlists, channel Videos/Shorts/Live, search, trending, subscriptions, liked videos, watch later | Progressive/adaptive formats, subtitles, storyboard, covers |
|
||||
| Douyin | Optional Cookie | Video, live | User posts | Bitrates, covers, live chat |
|
||||
| TikTok | Optional Cookie | Video, live | User posts | Formats, subtitles, covers, slideshow audio |
|
||||
| Huya | Public resolution | Live, video | URL and room entry | HLS/FLV, CDN, qualities, live chat |
|
||||
| Douyu | Public resolution | Live | Room number, alias, or URL | HLS/FLV, CDN, qualities, codecs, live chat |
|
||||
| AcFun | Public resolution | Video, bangumi, live | URL or resource ID | Qualities, tags, VOD/live danmaku, covers |
|
||||
| CCTV | Public resolution | Known columns, programs, and embeds | URL or resource ID | HLS/MP4, chapters, metadata, covers |
|
||||
| Emby/Jellyfin | Server, username, password or API key | Movies, episodes, videos | Continue Watching, Next Up, recent, favorite media/people, playlists, collections, genres | Direct stream, server transcode, subtitles, covers, progress reporting |
|
||||
| Alist | Endpoint, username, password, optional OTP | Files | Folders and search | Thumbnails, subtitles, direct/transcode, Range |
|
||||
| Cloudreve | Endpoint, email, password | Files | Folders and search with page/cursor negotiation | Signed playback URLs, covers/thumbnails, Range |
|
||||
| FNOS | Main endpoint, username, password, optional 2FA; WebDAV/media discovery | Files and native media items | Files, media library, favorites, history | File previews, posters, native transcode, favorite/watched/progress state |
|
||||
| QNAP QTS / QuTS hero | Endpoint, username, password | Files | File Station folders and search | Thumbnails, pre-transcoded heights, realtime transcode capability, Range |
|
||||
| Synology DSM | Endpoint, username, password, optional OTP | File Station files and Video Station items | Files, movies, TV, episodes, home videos, recordings | Thumbnails, posters, tracks, subtitles, remux, progress |
|
||||
| Nextcloud | Endpoint plus app password, or Login Flow | Files | Folders, favorites, search | Preview API, BlurHash, dimensions/duration, Range |
|
||||
| Seafile | Endpoint, username, password; encrypted-library unlock | Files | Library folders, starred, search | Thumbnails, download links, encrypted libraries, Range |
|
||||
| TrueNAS | Endpoint and API key | Files | Folders and search under `/mnt` | File metadata, ACL/ZFS attributes, Range |
|
||||
| Direct URL | None | HTTP(S) files, HLS, and related sources | Fixed source | Custom headers, Range, HLS segment proxy |
|
||||
| RTMP / Live Proxy | Room permission or admin configuration | Push and external RTMP/HTTP-FLV | Live source | SyncTV HLS/FLV and lifecycle management |
|
||||
|
||||
## Video Platforms
|
||||
|
||||
### Bilibili
|
||||
|
||||
Bindings unlock favorites, watch later, history, followed live rooms, and followed PGC. Public videos, PGC, and live rooms can also be resolved anonymously.
|
||||
|
||||
The App offers two workflows:
|
||||
|
||||
- **URL parsing** accepts video, PGC season/episode, live room, UP space, favorite folder, collection, series, and live-area URLs. The backend returns typed candidates. Multi-part videos support selected-part addition and complete dynamic playlists.
|
||||
- **Discovery** exposes popular, recommended, UP videos, favorite folders, history, followed PGC, live home, followed live, live areas, PGC timeline, and PGC index.
|
||||
|
||||
The PGC timeline supports anime, cinema, and guochuang across a zero-to-seven-day window in each direction. Preview keeps published, upcoming, and delayed entries; published entries carry their real episode ID and CID. The PGC index supports category, order, direction, completion status, area, year, and style filters. Selecting a season opens its full episode preview.
|
||||
|
||||
Dynamic playlists preserve upstream pagination. History uses Bilibili's native cursor, while popular, UP, favorites, seasons, and indexes use their own page or cursor contracts. Sequential, repeat-one, repeat-all, and shuffle playback advance with typed targets.
|
||||
|
||||
### Twitch
|
||||
|
||||
Bind an OAuth access token. SyncTV stores the Twitch user ID, client ID, and scopes. Followed Live requires `user:read:follows`; the App checks capabilities for the selected instance.
|
||||
|
||||
Media URLs support live channels, VODs, and Clips. Channel playlists support Videos, Highlights, Uploads, and Clips. Discovery includes Followed Live, Top Categories, Category Live, live-channel search, and Broadcaster Schedule.
|
||||
|
||||
### YouTube
|
||||
|
||||
Public videos work anonymously. Visitor Data and PO Token improve requests that need browser context. Subscriptions, Liked Videos, and Watch Later require a Cookie. Cookie material stays in server-side credential storage and upstream requests.
|
||||
|
||||
Video inputs accept IDs and `watch`, `youtu.be`, `shorts`, or `live` URLs. Playlists accept URLs or IDs. Channels accept `UC...` IDs and `/channel/UC...` URLs, with separate Videos, Shorts, and Live dynamic playlists.
|
||||
|
||||
Preview lists support selected-item addition and whole-source dynamic playlist creation. Personal feeds are enabled according to the selected Provider instance's Cookie capability. Shared mode uses the room owner's binding.
|
||||
|
||||
### Douyin and TikTok
|
||||
|
||||
Each Provider has independent resource and API models. Video and live URLs return platform metadata and playback variants. User profiles resolve to stable user identifiers for user-post dynamic playlists. Cookie bindings provide login, region, and risk-control context where required.
|
||||
|
||||
### Huya, Douyu, AcFun, and CCTV
|
||||
|
||||
- Huya resolves live rooms and videos with qualities, CDN choices, HLS/FLV, and chat capability.
|
||||
- Douyu accepts numeric room IDs, aliases, and URLs, and exposes codecs, qualities, and CDN choices.
|
||||
- AcFun supports videos, bangumi, and live, with distinct VOD and live danmaku protocols.
|
||||
- CCTV resolves known column, program, and embed pages and returns native streams, chapters, and metadata.
|
||||
|
||||
## Media Servers and File Services
|
||||
|
||||
### Emby and Jellyfin
|
||||
|
||||
Both use the `emby` Provider. Bind the server root URL, target username, and password, or use an API key. The upstream user's permissions control library visibility, transcoding, and subtitles.
|
||||
|
||||
Dynamic sources include Continue Watching, Next Up, Recently Added, Favorite Media, Favorite People, Person Items, server playlists, collections, genres, and genre items. Folder preview entries carry typed playlist source configs for continued browsing.
|
||||
|
||||
Playback start, progress, pause, and stop events are reported upstream. SyncTV requests playback information for the current client profile and exposes available direct and transcode modes. Negotiated playback sessions are scoped to a room. Stop, lease reaping, and server shutdown terminate the room's active encodings.
|
||||
|
||||
### Alist and Cloudreve
|
||||
|
||||
Alist supports folder browsing, search, thumbnails, subtitles, direct streams, and upstream transcodes. Directory passwords live in source configs; account passwords live in encrypted credentials.
|
||||
|
||||
Cloudreve supports browsing, search, signed playback URLs, and thumbnails. Page-based servers use page requests. Cursor-based servers use opaque cursors for dynamic playlists. The response pagination oneof is the authoritative mode.
|
||||
|
||||
## NAS and Private Cloud
|
||||
|
||||
### FNOS
|
||||
|
||||
FNOS login supports a main endpoint, optional WebDAV/media endpoints, 2FA, and trusted-device state. Discovery reports whether the native media service is available.
|
||||
|
||||
The App provides separate **Files** and **Media Library** workflows. Files use file thumbnails and download/Range. Media Library uses posters, metadata, favorites, history, watched state, progress, and native transcode. Saved sources use distinct `File` and `LibraryItem` variants. Native transcode sessions receive `media.quit` on profile replacement, playback stop, lease reaping, and server shutdown. The background reaper retries transient cleanup failures.
|
||||
|
||||
### QNAP
|
||||
|
||||
QNAP uses File Station for browsing and search. Capability discovery reports the device's realtime transcode, hardware transcode, QTranscode, Multimedia Codec, and HD Station flags for binding diagnostics. Playback exposes original files and completed pre-transcoded files. File items advertise the available pre-transcoded heights.
|
||||
|
||||
### Synology
|
||||
|
||||
Synology login supports OTP. File Station handles normal files; Video Station handles movies, shows, episodes, home videos, and recordings. Video items carry posters, tracks, subtitles, and playable file identity, and playback progress is reported to DSM. SyncTV tracks every Video Station `stream_id` and calls DSM `close` on playback stop, lease reaping, and server shutdown.
|
||||
|
||||
### Nextcloud
|
||||
|
||||
Use an app password or the official Login Flow. Entries preserve file ID, ETag, MIME type, owner, favorite state, Preview capability, BlurHash, dimensions, and duration. Covers use the Nextcloud Preview API through signed SyncTV routes.
|
||||
|
||||
### Seafile
|
||||
|
||||
Select a library after login. Encrypted libraries prompt for a separate unlock password. Dynamic sources support folders, starred items, and repository search; files retain object ID and thumbnail capability.
|
||||
|
||||
### TrueNAS
|
||||
|
||||
Bind with an API key. Browsing is scoped to storage mounts under `/mnt`. Folder and search results preserve real path, mount ID, permissions, ACLs, extended attributes, and ZFS attributes.
|
||||
|
||||
## Page and Cursor Pagination
|
||||
|
||||
Dynamic responses use an explicit pagination oneof:
|
||||
|
||||
- `page` serves upstreams with random page access.
|
||||
- `cursor` serves native continuations such as Cloudreve, Bilibili history, Twitch, and YouTube.
|
||||
|
||||
The App sends the next page number for page responses and returns `next_cursor` for cursor responses. Cursors are opaque values that clients store and return unchanged.
|
||||
|
||||
Sequential autoplay continues scanning pages until it finds the current target and next playable item. Shuffle uses a bounded sample to keep large folders under control.
|
||||
|
||||
## Credentials and Security
|
||||
|
||||
<Aside type="caution" title="Production requirement">
|
||||
Configure a stable `security.credential_encryption_key_file` and serve SyncTV over TLS. Submit Cookies, passwords, tokens, and API keys only to a trusted SyncTV deployment.
|
||||
</Aside>
|
||||
|
||||
Credentials are scoped by user, Provider, server ID, and Provider instance. The same upstream host can be bound independently through several instances. Migrate media and dynamic playlists that reference a binding before deleting it.
|
||||
|
||||
## Troubleshooting Order
|
||||
|
||||
1. Confirm that the selected Provider instance matches the binding.
|
||||
2. Refresh account state and scopes/capabilities in Platform Bindings.
|
||||
3. Preview again and identify whether the failure happens during listing, parsing, playback generation, or proxy transport.
|
||||
4. Inspect server ID, resource ID, pagination mode, and credential-sharing choice in the source config.
|
||||
5. Select a `proxy_*` mode for header-bound, DASH, or HLS sources that need server transport.
|
||||
6. Continue with [Provider Configuration](../../configuration/media-providers/), [Playback and Proxy](../playback-and-proxy/), and [User Troubleshooting](../troubleshooting/).
|
||||
@ -1,61 +0,0 @@
|
||||
---
|
||||
title: Create and Join Rooms
|
||||
description: How users join public rooms, enter passwords, submit reviews, create rooms, and understand room roles.
|
||||
---
|
||||
|
||||
import { Aside, Steps, TabItem, Tabs } from '@astrojs/starlight/components';
|
||||
|
||||
A room is where a group watches and chats together. Whether you can enter depends on visibility, password, review, guest access, member limit, and ban state.
|
||||
|
||||
## Join a Room
|
||||
|
||||
<Tabs syncKey="join-room-user-en">
|
||||
<TabItem label="Open room" icon="rocket">
|
||||
<Steps>
|
||||
1. Open the room from the room list or an existing room entry point.
|
||||
2. If no password or review is required, join directly.
|
||||
3. After joining, your role decides which chat, playlist, and playback controls are available.
|
||||
</Steps>
|
||||
</TabItem>
|
||||
<TabItem label="Password" icon="seti:lock">
|
||||
<Steps>
|
||||
1. Enter the room password.
|
||||
2. If review is also required, wait for a room administrator.
|
||||
3. Avoid repeated failed submissions because they may trigger rate limits or audit logs.
|
||||
</Steps>
|
||||
</TabItem>
|
||||
<TabItem label="Review" icon="approve-check-circle">
|
||||
<Steps>
|
||||
1. Submit a join request.
|
||||
2. Wait for a room administrator or creator.
|
||||
3. If rejected, confirm room rules before trying again.
|
||||
</Steps>
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
<Aside type="note">
|
||||
Different buttons for creators, room admins, members, and guests are usually permission behavior, not a UI error.
|
||||
</Aside>
|
||||
|
||||
## Create a Room
|
||||
|
||||
If ordinary users can create rooms:
|
||||
|
||||
1. Use a clear name and description.
|
||||
2. Decide whether the room needs a password.
|
||||
3. Enable join review for semi-public rooms.
|
||||
4. Set a member limit that fits the service and upstream media source.
|
||||
5. Check default permissions for guests and members.
|
||||
6. Join once with a normal member account.
|
||||
|
||||
## Cannot Join
|
||||
|
||||
| Symptom | Possible cause | What to do |
|
||||
| --- | --- | --- |
|
||||
| Password rejected | Password changed or mistyped | Ask the room administrator |
|
||||
| Waiting for review | Join review is enabled | Wait or contact a room administrator |
|
||||
| Permission denied | Not signed in, guest access disabled, or room ban | Sign in or contact a room administrator |
|
||||
| Room is full | `maxMembers` reached | Wait or ask for a higher limit |
|
||||
| Room missing | Hidden, deleted, or banned | Confirm the room entry point or contact an administrator |
|
||||
|
||||
For room and role boundaries, see [Rooms](../../concepts/rooms/) and [Permissions Model](../../concepts/permissions/).
|
||||
@ -1,34 +0,0 @@
|
||||
---
|
||||
title: Synchronized Playback
|
||||
description: How users follow room playback, use playback controls, handle seek, switch media, and diagnose drift.
|
||||
---
|
||||
|
||||
The SyncTV server owns room playback state. A client fetches the current state and playback info, then receives changes through Realtime.
|
||||
|
||||
## What Happens in a Room
|
||||
|
||||
| Behavior | Meaning |
|
||||
| --- | --- |
|
||||
| Play or pause | A permitted user changes state for room members |
|
||||
| Seek | The room jumps to a new playback time |
|
||||
| Switch media | Clients fetch a new playback info |
|
||||
| Change speed | A permitted user changes shared playback speed |
|
||||
| Reconnect | The client should refresh key state after network loss |
|
||||
|
||||
Users without playback permissions follow the room state. If controls are missing, check the room role and member permissions.
|
||||
|
||||
## Playback Failure
|
||||
|
||||
| Symptom | Try first | If it continues, collect |
|
||||
| --- | --- | --- |
|
||||
| Playback drift | Refresh or re-enter the room | Room ID, time, whether only you are affected |
|
||||
| Media switch fails | Retry or refresh playlist | Media ID, error text, HTTP status |
|
||||
| Playback URL expired | Fetch fresh playback info or re-enter | Provider name, expiry message, requestId |
|
||||
| Seek hangs | Wait for buffering, check Range/proxy | Upstream status and proxy mode |
|
||||
| Multiple users fail | Ask an admin to inspect WebSocket, Ingress, or Provider | Time range, room ID, affected users |
|
||||
|
||||
## Direct or Proxy
|
||||
|
||||
Browsers cannot set some upstream headers. If a Provider requires headers the client cannot set, use SyncTV proxy playback. Proxy playback uses SyncTV egress bandwidth but can normalize headers and hide upstream credentials.
|
||||
|
||||
For the full model, see [Playback Model](../../concepts/playback-model/). Client implementers should read [Client Integration Guide](../../develop/client-integration/).
|
||||
@ -1,31 +0,0 @@
|
||||
---
|
||||
title: User Troubleshooting
|
||||
description: Diagnose sign-in, room, playback, chat, media, and notification issues by symptom.
|
||||
---
|
||||
|
||||
Start with the symptom, then decide whether to contact a room administrator or platform administrator. Do not send passwords, tokens, cookies, Provider credentials, OAuth2 codes, or verification codes.
|
||||
|
||||
## Quick Diagnosis
|
||||
|
||||
| Problem | Check first | Owner |
|
||||
| --- | --- | --- |
|
||||
| Sign-in fails | Username, password, email verification, 2FA, account ban | Platform administrator |
|
||||
| OAuth2 did not sign in | Registration review, third-party account binding | Platform administrator |
|
||||
| Cannot join room | Password, review state, room ban, member limit | Room administrator |
|
||||
| Cannot control playback | `control_playback_state`, `navigate_playback` | Room administrator |
|
||||
| Cannot play media | Provider credentials, direct headers, proxy path, upstream Range | Room or platform administrator |
|
||||
| WebSocket keeps disconnecting | Network, browser proxy, reverse proxy timeout, connection limits | Platform administrator |
|
||||
| Cannot chat | `send_chat_messages`, room chat switch, mute state | Room administrator |
|
||||
| No notifications | Preferences, verified email, SMTP availability | Platform administrator |
|
||||
|
||||
## Include in Reports
|
||||
|
||||
| Information | Example |
|
||||
| --- | --- |
|
||||
| Time | 2026-05-10 21:30 Asia/Shanghai |
|
||||
| Room or media | Room ID, media name, media ID |
|
||||
| Action | Sign in, join room, click play, send message, add media |
|
||||
| Error | UI message, HTTP status, `requestId` |
|
||||
| Scope | Only you, or several members at the same time |
|
||||
|
||||
For playback issues, also include direct/proxy mode, whether you were seeking, and whether it started after a media switch. Operators use [Troubleshooting](../../operations/troubleshooting/) for production diagnosis.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue