Restreamer/PROJECT.md

PROJECT.md

Goal

A Docker container bundling Python, ffmpeg and yt-dlp that takes YouTube livestream URLs on one side and serves them as continuous, always-on streams on the other, consumable by Jellyfin Live TV via an M3U tuner. The service handles its own stream-session renewal so a channel does not die when YouTube's resolved URL expires after a few hours.

Current state

Initial implementation in place:

• src/restreamer/ — resolver (yt-dlp), ffmpeg process wrapper, per-channel supervisor worker, broadcast fan-out, aiohttp server (/playlist.m3u, /stream/{channel_id}, /healthz), config loading.
• serve.py — entry point.
• Dockerfile / docker-compose.yml — containerized deployment.
• .gitea/workflows/ci.yml — CI: tests, then native amd64 + arm64 builds (one runner per architecture) merged into a single multi-arch image in the Gitea registry.
• channels.example.yaml, .env.example — configuration templates.
• Unit tests for the pure/testable pieces (config parsing, URL expiry parsing, ffmpeg argument building, playlist generation, broadcast fan-out).

Not yet done / not yet verified against a real YouTube livestream and a real Jellyfin instance — see TODO/NOTE comments in code for anything more granular.

Open questions

• Whether channels also need XMLTV EPG data, or the bare M3U + tvg-id is enough for how Jellyfin is being used here.
• Whether any of the YouTube URLs to restream require authentication (cookies) — YtDlpResolver accepts extra ydl_opts for this but no cookie handling is wired up yet.