mirror of
https://github.com/myronblair/kino-app
synced 2026-07-27 21:18:43 -05:00
emergent-agent-e1
93 lines
5.5 KiB
Markdown
93 lines
5.5 KiB
Markdown
# 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)
|