Add Media
Choose a Source
Section titled “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 Provider types include alist, bilibili, emby, direct-url, rtmp, and live-proxy. A remote Provider instance is stored in the database and connects SyncTV to a separate Provider service; it is not the media_providers YAML object.
Before Adding Media
Section titled “Before Adding Media”- Configure
security.credential_encryption_keyor_file. - Confirm local Provider timeouts:
media_providers.<type>.request_timeout_secondsandconnect_timeout_seconds. - Create a remote Provider instance through management APIs or CLI if needed.
- Test login, browse, search, parse, and playback with an administrator.
- Test direct playback, proxy playback, and Range seek.
- Watch Provider error rate, proxy errors, slice cache hits, and upstream status.
Source Recipes
Section titled “Source Recipes”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.
Use for: existing media libraries, shows, subtitles, and transcoding.
Focus:
- Playback results may include multiple modes, subtitles, and metadata.
- Clients should use
default_modeandPlaybackClientProfile. - 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.
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.
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.
Use for: room livestream publishing and HLS/FLV playback.
Focus:
- RTMP is a publish entry, not a normal VOD Provider.
- The member needs
live_controlpermission 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.
Local and Remote Providers
Section titled “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
Section titled “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.
Troubleshooting
Section titled “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 |