Media Providers

What Providers Are

Media providers are SyncTV’s integration points for external media sources, including:

• Alist.
• Emby.
• Jellyfin.
• Bilibili.
• Remote provider instances.

media_providers only configures local built-in provider adapters in this SyncTV process. Each provider has explicit fields:

media_providers:
  alist:
    request_timeout_seconds: 30
    connect_timeout_seconds: 10
  bilibili:
    request_timeout_seconds: 30
    connect_timeout_seconds: 10
  emby:
    request_timeout_seconds: 30
    connect_timeout_seconds: 10

Remote provider instances are not configured in this YAML object. They are persisted through the management API/CLI and only store connection details that SyncTV needs to reach the remote provider, such as endpoint, tls, jwt_secret, custom_ca, timeout, insecure_tls, and providers. The remote provider’s own Alist, Emby, or Bilibili configuration belongs in the remote provider deployment.

Local Provider Timeout Fields

request_timeout_seconds default: 30.

This is the total timeout for one upstream HTTP request made by that provider.

connect_timeout_seconds default: 10.

This is the TCP connection timeout for that provider. Validation reports an unreasonable config if it is larger than the same provider’s request timeout.

Alist:

media_providers:
  alist:
    request_timeout_seconds: 30
    connect_timeout_seconds: 10

Emby:

media_providers:
  emby:
    request_timeout_seconds: 30
    connect_timeout_seconds: 10

Bilibili:

media_providers:
  bilibili:
    request_timeout_seconds: 30
    connect_timeout_seconds: 10

Header Ownership

The low-level proxy layer should not guess which raw client headers to forward. Providers decide which upstream request headers are required, for example:

• User-Agent
• Referer
• Range
• Provider-specific authentication headers

This keeps behavior predictable, avoids leaking arbitrary client headers upstream, and lets each provider match direct-play and proxy-play semantics.

Alist Notes

Alist may return URLs that are bound to a specific User-Agent. SyncTV should keep these aligned:

• Headers used by provider-originated requests.
• Headers returned to clients for direct playback.
• Headers used by proxy mode when requesting the upstream URL.

If a client cannot set required headers, use proxy mode instead of direct mode.

Bilibili Notes

Bilibili is sensitive to request headers, especially:

• User-Agent
• Referer
• Cookie or authentication headers
• Range requests

If direct mode works but proxy mode fails, or the reverse, first compare the headers returned to clients with the headers used by proxy upstream requests.

Credential Encryption

If provider credentials are stored, production should configure:

security:
  credential_encryption_key_file: "/run/secrets/credential_encryption_key"

Without a stable credential encryption key, creating or updating encrypted provider credentials may fail, and previously encrypted credentials may become unreadable if the key is lost.