# 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.
- `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.