Fzz Proxy

Fast, lightweight HLS and media proxy built as a single dependency-free Node service.

Fzz Proxy is designed for people who want a clean self-hosted proxy that is easy to run, easy to publish, and strong enough for real streaming workloads without dragging in a heavy framework stack.

Why Fzz Proxy

Area	Fzz Proxy
Runtime	Single dependency-free Node service
Playlist support	Master, variant, iframe, alternate audio, subtitles, LL-HLS tags
Media support	TS, fMP4, keys, mp4, subtitles, byte ranges
Security	CORS allowlist, token auth, rate limiting
Performance	Keep-alive pooling, smart in-memory cache
Usability	Simple query API, root metadata route, Docker support

Features

• Rewrites HLS playlists
• Streams segments, keys, mp4, subtitles, and other media
• Forwards custom headers per request
• Handles alternate audio, subtitles, iframe playlists, LL-HLS parts, maps, and keys
• Supports CORS allowlists
• Uses keep-alive upstream connection pooling
• Uses smart in-memory caching for playlists and small cacheable media
• Supports optional token protection for public deployments
• Includes built-in per-IP rate limiting

Quick Start

npm start

API

Base routes:

• GET /playlist?url={encoded}&headers={encodedJson}
• GET /media?url={encoded}&headers={encodedJson}
• GET /proxy?url={encoded}&headers={encodedJson}&mode=auto|playlist|media
• GET /health
• GET /meta

Example:

const proxy = "http://localhost:8080";
const url = encodeURIComponent("https://example.com/master.m3u8");
const headers = encodeURIComponent(JSON.stringify({
  Referer: "https://example.com/",
  Origin: "https://example.com"
}));

const playlistUrl = `${proxy}/playlist?url=${url}&headers=${headers}`;

Public Deploy

Recommended minimum settings for a public deployment:

ALLOWED_ORIGINS=https://your-app.com
ACCESS_TOKENS=change-this-token
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_REQUESTS=240

Then call the proxy with &token=change-this-token.

Public GitHub Setup

Useful repo files already included:

• LICENSE
• .env.example
• Dockerfile

Docker

docker build -t fzz-proxy .
docker run -p 8080:8080 --env-file .env.example fzz-proxy

Config

• PORT=8080
• HOST=0.0.0.0
• REQUEST_TIMEOUT_MS=15000
• UPSTREAM_REDIRECT_LIMIT=5
• DEFAULT_USER_AGENT=Mozilla/5.0 Fzz-Proxy/1.0
• ALLOWED_ORIGINS_FILE=./allowed_origins.txt
• ALLOWED_ORIGINS=*
• PLAYLIST_CACHE_TTL_MS=4000
• MEDIA_CACHE_TTL_MS=30000
• CACHE_MAX_ENTRIES=500
• CACHE_MAX_BYTES=67108864
• MEDIA_CACHE_MAX_BYTES=1048576
• ACCESS_TOKENS=token1,token2
• RATE_LIMIT_WINDOW_MS=60000
• RATE_LIMIT_MAX_REQUESTS=240

If ALLOWED_ORIGINS is set, it overrides the file. Use * to allow all origins.

Notes

• Keep ALLOWED_ORIGINS=* only for local testing.
• Enable ACCESS_TOKENS before exposing the proxy publicly.
• Range requests and authenticated media are intentionally not body-cached.