Proxy Streaming

How the Proxy Works

Every video segment, HLS playlist, and subtitle file is fetched and delivered through your server. The browser never contacts KissKH's CDN directly.

When the server builds a player response for an episode:

1. It calls the KissKH API to get the video URL (a .m3u8 HLS playlist or .mp4 file)
2. It wraps that URL into a signed, server-relative path like /vid/{enc-dir}/{enc-meta}/{filename}
3. The player loads /vid/... — your server fetches the real CDN URL, streams the bytes back to the browser
4. For HLS streams, the .m3u8 playlist is rewritten on-the-fly so every segment URL also points to /vid/...

Subtitle files go through /sub/... the same way.

URL Encoding and Security

Proxy paths are encoded to hide the real upstream CDN URL from viewers. When URL_SECRET is set, the path segments are AES-128-CBC encrypted — unguessable without the secret key. Without URL_SECRET, plain base64 is used (still obfuscated, but decodable).

Always set URL_SECRET in production. See Environment Variables for details.

HLS vs MP4

The server automatically handles both video formats:

HLS segment URLs inside the playlist may use disguised image extensions (.png, .jpg, .webp) to evade blockers — the server detects this and serves them as video/mp2t.

Offloading Bandwidth with PROXY_URL

By default, both the application logic and the media proxying happen on the same server. For high-traffic sites, video bandwidth can be significant. You can offload it by running a second instance of the server and setting PROXY_URL on the primary:

# On your primary app server:
PROXY_URL=https://proxy.your-cdn.com

The primary server will still handle all KissKH API calls and page rendering, but all /vid/ and /sub/ URLs will point to the proxy server instead. The proxy server must run the same server.js code.

This lets you put the proxy server on a cheaper high-bandwidth VPS or a different region.

Subtitle Proxy

Subtitle files are also proxied through /sub/.... This is always done on the primary server (not the PROXY_URL server) because some KissKH subtitle files require server-side decryption — see Subtitle Decryption.

Upstream Timeouts and Errors

The proxy uses a 20-second connection timeout for upstream fetches. If the KissKH CDN is slow or unavailable:

• If the client disconnects before the stream starts, the upstream request is cancelled immediately
• If the upstream returns a non-2xx status for non-segment files, the proxy returns a 502 error to the browser
• For disguised-segment files (.png/.jpg extensions used for video), a failed upstream response is streamed as-is rather than blocked (KissKH CDN sometimes uses non-200 status codes on valid segments)

These safeguards ensure a slow or partially-down CDN does not crash or stall the server.