Playback and Proxy

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

1. The client requests the current room playback or a playback for a media item.
2. SyncTV uses room state, media, user, Provider credentials, and client profile to build Playback.
3. The Provider returns one or more PlaybackInfo entries with URL, format, headers, subtitles, expiry, and metadata.
4. The client chooses direct URL, proxy URL, transcode variant, HLS, FLV, or subtitle URL.
5. When URL expiry, media switch, credential change, or client capability changes, the client requests fresh playback info.

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

Note

SyncTV proxy uses only headers explicitly provided by the Provider. It does not automatically forward browser cookies, Authorization, or arbitrary request headers upstream.

Alist playback URLs may be bound to a specific User-Agent. Bilibili commonly depends on User-Agent, Referer, cookies, and Range. When direct and proxy playback behave differently, compare the headers returned to the client with those sent upstream by the proxy. Browser clients that cannot set the required headers should select the proxy URL.

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

Seeking usually depends on HTTP Range:

Range: bytes=1048576-2097151

Proxy 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

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 Protocol.

P2P Media Delivery

Native clients can enable P2P media delivery dynamically from playback sync settings. Eligible on-demand PlaybackMedia entries contain p2p_delivery. The client obtains media pieces from viewers in the same room and resource swarm over WebRTC DataChannels, with the original HTTP URL retained as the fallback path.

Item	Behavior
Resource scope	Providers create room-isolated swarms for static on-demand resources; live playback omits p2p_delivery
Media formats	The client uses the selected PlaybackMedia.format to handle progressive files, HLS, and DASH
Direct and proxy	Both modes share a swarm when the Provider confirms byte equivalence
Permission	Room members or guests need use_p2p_media
Runtime toggle	Disabling P2P leaves the swarm, closes P2P connections, and continues playback over HTTP
Local cache	Select 64, 128, 256, 512, or 1024 MiB; the default is 128 MiB. Recently used pieces remain reusable across playback sessions and expire after ten minutes without access

Player diagnostics report connected peers, aggregate download and upload rates, HTTP download, P2P download and upload, transferred bytes, cache size, and cache hit rate. Playback requests automatically use the HTTP origin when peers, ICE connectivity, or piece transfers are temporarily unavailable.

Caution

Swarm tickets isolate rooms, actors, and resources. The current transfer protocol allows a peer to return arbitrary media bytes and is intended for rooms whose members trust each other.

WebRTC and Livestreaming

Capability	Boundary
WebRTC	Independent voice-chat and P2P-media sessions using ICE/STUN/TURN and their respective use_voice_chat and use_p2p_media permissions
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 S3 backend

WebRTC configuration is in WebRTC Configuration. Livestreaming is in Livestream Configuration.

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, S3, gRPC proxy
URL stops working later	expires_at	Observe or fetch a new playback