What this app does
Uttarayan Song Queue is a small self-hosted jukebox: paste a YouTube URL, it gets validated
(music only, not age-restricted) and dropped onto a queue, and a single local worker plays
songs back to back — downloading each one first so playback survives a flaky connection,
then handing it to ffplay. Anyone can enqueue a song or check its wait time; an
admin can log in to view the live queue, skip the current or any queued song, and manage
one or more "default playlists" that loop automatically whenever the real queue is empty
(interrupted instantly the moment a real song gets enqueued).
System design
producer_api.py (FastAPI) exposes the REST endpoints — /enqueue,
/status/<id>, /wait-time, and /now-playing are
public; /queue, /skip, and the playlist-management endpoints require
HTTP Basic admin auth. A valid request publishes one message per song to a single Kafka topic
(via confluent-kafka, one broker, one partition — strict order relies on exactly
one consumer).
consumer_worker.py is that lone consumer: it long-polls Kafka, downloads each
song's audio with yt-dlp to a temp file, plays it with ffplay, then
commits the offset — so a message is never marked done until its audio has actually finished
(or failed). When the real queue is empty it falls back to whichever default playlist is
marked active, and bails out of that fallback song within ~0.2s if a real song shows up.
State (queue position, wait times, playlists, who's playing what) lives in small shared JSON
files rather than a database — deliberately simple, since this is a single local user's app,
not a distributed system. run.py ties it all together: starts Kafka via Docker
Compose, then launches the API and worker as child processes.