kino-app/memory/PRD.md

Kino — PRD

Original problem statement

build me a netflix clone and have the ability to request and automatically download movies off the internet and store them for viewing in the website/app. I have a proxmox server that I can give you access to to store everything and you can use my github for backup of scripts, software and documents

Scope decisions (legal/ethical)

• Auto-download of copyrighted movies is not implemented (illegal).
• Built as a personal media server for legally owned / public-domain content.
• "Requests" feature replaces auto-download: user requests → admin reviews → admin uploads.
• Confirmed: internal-network deployment only (Proxmox), not public internet.

Personas

• Admin — manages library, uploads movies, fulfils user requests, configures integrations.
• Member — browses, watches, builds watchlist (per profile), submits requests.
• Kids — separate profile with parental rating cap (e.g. PG max).

Tech stack

• Backend: FastAPI + Motor (MongoDB), JWT (bcrypt + python-jose), ffmpeg (HLS transcoding)
• Frontend: React 19 + react-router 7 + Tailwind + shadcn/ui + lucide-react + sonner + hls.js
• Storage: local filesystem with MEDIA_ROOT env (Proxmox-friendly: mount NAS path)
• External: TMDB (metadata), Radarr (library import) — both optional, configured by admin

Implemented

Phase 1 (2026-04-29)

• JWT auth, admin role, admin seeding
• Movies CRUD, multipart upload
• Range-aware streaming endpoint
• Watchlist + Continue Watching
• Movie request queue
• 10 seeded public-domain movies
• Cinematic UI (Fraunces + Geist, blood-orange #D9381E)
• Pages: Login, Register, Browse, MyList, Search, Player, Requests, Admin, AdminUpload
• Proxmox + Caddy deployment guide

Phase 2 (2026-04-29)

• Multi-profile ("Who's Watching"): up to 5 per account, avatar color, kids flag, max_rating cap
• Parental controls: profile-scoped movie filtering (G/PG/PG-13/R/NR ladder)
• Profile-scoped watchlist + progress (continue watching)
• TMDB metadata auto-fill on upload (admin configures key in Settings)
• Subtitles: upload .srt or .vtt; auto-convert SRT→WEBVTT; in-player track selection
• Radarr import: pull library list, multi-select, bulk import as Movie entries
• HLS transcoding via ffmpeg: admin-triggered, background task, status tracking, <video> auto-uses HLS when ready (via hls.js fallback for non-Safari)
• Admin Settings page for TMDB + Radarr config with masked inputs + connection test

Phase 3 (2026-04-29)

• Adaptive bitrate (ABR) HLS: admin chooses Quick (stream-copy, instant) or ABR (re-encode to 360p/480p/720p/1080p with master playlist)
• Smart variant selection: ladder auto-trims to source resolution (no upscaling)
• Auth-aware playlist serving rewrites ?auth= into every relative URL so hls.js segment requests stay authenticated
• Quality badge in admin row shows HLS done · Quick or HLS done · ABR
• Defensive -pix_fmt yuv420p ensures encoder works across all source chroma formats

Phase 4 (2026-04-29)

• Background Transcode Queue with persistent storage in MongoDB
• Single FIFO worker started at backend boot; processes one job at a time
• ffmpeg runs at low CPU priority (nice -n 19) so streaming + UI stay snappy during transcodes
• Auto-transcode toggle in Settings: Off / Quick / ABR — applied to every new upload AND Radarr import
• Pause/resume queue, cancel pending jobs, retry failed/cancelled jobs, clear finished history
• Stat tiles (pending/running/done/failed/cancelled) on /admin/queue
• Crash recovery: stuck running jobs are reset to failed on backend restart
• Cancel of a pending job clears hls_path to avoid stale references

Phase 5 (2026-07-23)

• Sonarr / TV Shows — Show → Episode data model, Sonarr library import (multi-select), season/episode picker UI, dedicated /shows browse page
• Episode player with auto-next-episode CTA in last 20s, auto-advance on video end, profile-scoped progress + continue-watching
• Trakt.tv sync — OAuth device-code flow to connect account, auto-scrobble on every movie AND episode progress update (start/pause/stop based on % watched)
• OpenSubtitles auto-search — one-click subtitle search by TMDB ID in the upload flow, auto-converts SRT to WEBVTT, attaches directly to movie
• Bulk TMDB enrichment — sweeps every existing movie with missing metadata (cast/director/description/poster) and backfills from TMDB in one click

Backlog (P1)

• Sonarr (TV shows): requires episodes/seasons data model — significant addition
• Subtitle search via OpenSubtitles API
• Trakt.tv sync (mark watched, ratings)
• DLNA/Chromecast casting

Backlog (P2)

• LDAP/OIDC SSO for household-wide auth
• Mobile native wrapper (Capacitor)
• Admin user management UI (currently only seed admin)
• Live transcoding (subtitle burn-in, codec conversion for old TVs)
• Watch parties (synchronized playback)

External keys/services needed for full functionality

• TMDB: free API key from https://www.themoviedb.org/settings/api → paste in Admin → Settings
• Radarr: existing Radarr install on Proxmox; URL + API key (Settings → General in Radarr) → paste in Admin → Settings. Radarr's media path must be readable by Kino on disk.

Test credentials

See /app/memory/test_credentials.md

Test reports

• /app/test_reports/iteration_1.json — Phase 1 (21/21 backend, 9/9 UI)
• /app/test_reports/iteration_2.json — Phase 2 (42/42 backend, all UI flows pass)