Playback and Proxy Model
Boundary
Section titled “Boundary”Playback issues often sit between the client, SyncTV, Provider, and upstream media server. Providers explicitly return playback information and upstream headers, clients follow that result, and the proxy does not guess client headers.
Playback Flow
Section titled “Playback Flow”- The client requests the current room playback or a playback for a media item.
- SyncTV uses room state, media, user, Provider credentials, and client profile to build
Playback. - The Provider returns one or more
PlaybackInfoentries with URL, format, headers, subtitles, expiry, and metadata. - The client chooses direct URL, proxy URL, transcode variant, HLS, FLV, or subtitle URL.
- When URL expiry, media switch, credential change, or client capability changes, the client requests fresh playback info.
Direct and Proxy Playback
Section titled “Direct and Proxy Playback”| Mode | Best for | Risk |
|---|---|---|
| Direct | Client can access upstream and set headers | Browser header limits, CORS, upstream exposure |
| SyncTV proxy | Upstream is server-only or requires server-controlled headers | SyncTV carries bandwidth and latency |
| Provider variants | Multiple qualities, codecs, subtitles, or transcoding | Client must choose by capability |
| HLS/FLV live | RTMP publish to playback | Multi-replica deployments need HLS backend or publisher proxy |
Client Selection Strategy
Section titled “Client Selection Strategy”| Client condition | Handling |
|---|---|
Browser cannot set Referer or custom headers | Prefer proxy URL |
| Native client can set headers and access upstream | Direct URL can be used |
| Mobile client lacks codec/container support | Declare capabilities in PlaybackClientProfile |
URL has expires_at | Request fresh playback info before expiry |
| Subtitle has separate headers | Use subtitle-specific headers or proxy subtitle URL |
Range and Slice Cache
Section titled “Range and Slice Cache”Seeking usually depends on HTTP Range:
Range: bytes=1048576-2097151Proxy slice cache boundaries:
- Caches only Range slices.
- Does not cache full response bodies.
- Bypasses upstreams that do not support Range.
- File backend can survive process restarts, but has no cross-process index or distributed lock.
- Shared storage in multi-replica mode is possible, but this is not a strongly consistent distributed cache.
See Proxy Slice Cache.
Playback Info and Realtime
Section titled “Playback Info and Realtime”New clients observe playback resources over Realtime:
playbackState: current position, state, and version.playback: playback URLs, headers, subtitles, and expiry.
On reconnect, fetch playbackState and observe playback with the current playbackClientProfile. Playback info is player-ready data for the current source and expires with its URLs.
See Realtime API.
WebRTC and Livestreaming
Section titled “WebRTC and Livestreaming”| Capability | Boundary |
|---|---|
| WebRTC | Room realtime audio/video or signaling; depends on ICE/STUN/TURN and use_webrtc |
| RTMP publish | Publisher entry, usually used by streamer or room admin |
| HTTP-FLV | Low-latency live playback, sensitive to long connections and slow clients |
| HLS | Playlist/segment files; multi-replica requires local proxy, shared file, or OSS backend |
WebRTC configuration is in WebRTC Configuration. Livestreaming is in Livestream Configuration.
Troubleshooting Matrix
Section titled “Troubleshooting Matrix”| Symptom | Likely layer | Check |
|---|---|---|
| Player gets 403 immediately | Provider credential or header | Provider headers and upstream status |
| Seek fails | Range or slice cache | Accept-Ranges, Content-Range, proxy logs |
| Browser only fails | CORS or header restrictions | Use proxy and inspect browser Network |
| Proxy only fails | Server-to-upstream network or headers | DNS, server network, proxy headers |
| Multi-replica live randomly fails | HLS storage model | Publisher node, shared storage, OSS, gRPC proxy |
| URL stops working later | expires_at | Observe or fetch a new playback |