Netflix

Build a self-hosted personal media streaming server and web player. Single project, runs on my own machine, no accounts service, no cloud, no telemetry.

Stack, no substitutions:
- Node.js with TypeScript, Fastify for the API
- SQLite via better-sqlite3 for the library database
- React with Vite for the frontend, plain CSS, no component library
- ffmpeg and ffprobe invoked as child processes
- hls.js in the browser for playback

What it does:
1. Reads MEDIA_ROOT from .env and recursively scans it for video files (mp4, mkv, avi, mov). Parses filenames into title, year, and optional season/episode.
2. Runs ffprobe on each file to record duration, resolution, codecs, and audio tracks.
3. Optionally enriches each title with metadata and poster art from the TMDB API using TMDB_API_KEY from .env. If the key is missing, skip enrichment gracefully and show a generated placeholder poster.
4. Serves a library browse UI: poster grid, search, filter by movie vs series, series drilldown to seasons and episodes.
5. Plays video at /watch/:id. If the source is browser-friendly h264/aac, stream it directly with HTTP range support. Otherwise transcode on the fly to HLS with ffmpeg, segmenting into a cache directory, and serve the playlist to hls.js. Reuse cached segments on repeat plays.
6. Tracks watch progress per profile. Local profiles are just names in SQLite, no passwords, no auth provider. Resume where you left off, mark watched at 90 percent, and show a Continue Watching row.
7. Extracts embedded subtitle tracks with ffmpeg, converts to WebVTT, and exposes them as selectable tracks in the player.
8. A CLI command "npm run scan" for rescanning, plus a watcher that picks up new files while running.

Explicitly out of scope: any content acquisition, downloading, scraping, or DRM. No native mobile or TV apps. No recommendation engine beyond a recently-added row. No multi-user auth or public internet exposure; bind to localhost by default and document that exposing it is my problem.

Deliver a README with setup steps, a .env.example listing MEDIA_ROOT, TMDB_API_KEY, PORT, and TRANSCODE_CACHE_DIR, and seed the database on first run. Keep the whole thing runnable with npm install then npm run dev.

# AGENTS.md — Build guide for Netflix

## Project scope
A self-hosted streaming site that scans a local media folder, pulls metadata and artwork, and plays it back in the browser with per-profile resume.

Catalogue verdict: no. You can absolutely build a Netflix, the software part is the easy part. A video catalog, transcoding pipeline, adaptive streaming player, watch progress, and profiles is a genuinely fun weekend of work, and self-hosted media servers already prove it. What you cannot build is the thing you were actually paying for: thousands of hours of licensed content plus originals you legally cannot obtain. A media server pointed at an empty disk is a very nice empty shelf. The honest DIY move is Jellyfin or a hand-rolled version of it over media you already own, which changes what the product is rather than replacing it.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Media files you actually have the right to store
- A machine with disk space and enough CPU or a GPU for transcoding
- ffmpeg installed
- A metadata API key, for example TMDB
- Bandwidth if you want to stream outside your own network

## Stack and architecture
- Node.js with TypeScript, Fastify for the API.
- Model source media, edit decisions, processing jobs, and exported assets; keep stable source IDs and timestamps.
- Interface for this streaming workflow: a focused streaming input, review, and export interface.

## Security and data integrity
- Keep the original media file untouched when decoding or rendering fails; show the failing job and allow retry.
- Keep API keys and OAuth secrets in .env; redact them from logs, generated files, and error responses.
- State the practical limit: The entire catalog: licensed films, TV, and originals you cannot legally acquire.

## Agent implementation rules
- Project rule, data: Model source media, edit decisions, processing jobs, and exported assets; keep stable source IDs and timestamps.
- Project rule, behavior: Runs ffprobe on each file to record duration, resolution, codecs, and audio tracks.
- Project rule, recovery: Keep the original media file untouched when decoding or rendering fails; show the failing job and allow retry.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this streaming operation with sample or user-owned data: Runs ffprobe on each file to record duration, resolution, codecs, and audio tracks.
- Show a concrete result or export: Explicitly out of scope: any content acquisition, downloading, scraping, or DRM. No native mobile or TV apps. No recommendation engine beyond a recently-added row. No multi-user auth or public internet exposure; bind to localhost by default and document that exposing it is my problem.
- State the practical limit: The entire catalog: licensed films, TV, and originals you cannot legally acquire.

## Engineering roadmap
1. Phase 1, architecture and data: Node.js with TypeScript, Fastify for the API. Model source media, edit decisions, processing jobs, and exported assets; keep stable source IDs and timestamps.
2. Phase 2, implement: Runs ffprobe on each file to record duration, resolution, codecs, and audio tracks.
3. Phase 3, implement: Serves a library browse UI: poster grid, search, filter by movie vs series, series drilldown to seasons and episodes.
4. Phase 4, review and output: Plays video at /watch/:id. If the source is browser-friendly h264/aac, stream it directly with HTTP range support. Otherwise transcode on the fly to HLS with ffmpeg, segmenting into a cache directory, and serve the playlist to hls.js. Reuse cached segments on repeat plays. Explicitly out of scope: any content acquisition, downloading, scraping, or DRM. No native mobile or TV apps. No recommendation engine beyond a recently-added row. No multi-user auth or public internet exposure; bind to localhost by default and document that exposing it is my problem.
5. Phase 5, recovery and acceptance: Keep the original media file untouched when decoding or rendering fails; show the failing job and allow retry. Verify this invariant with a saved fixture: The original hash must remain unchanged; cuts and captions must stay aligned after export despite a variable input frame rate. State the practical limit: The entire catalog: licensed films, TV, and originals you cannot legally acquire.

## Paid-product capabilities outside this build
- The entire catalog: licensed films, TV, and originals you cannot legally acquire
- Global CDN delivery that does not stutter on hotel wifi
- Native apps on every TV, console, phone, and streaming stick
- Downloads with DRM, offline playback, and multi-device sync that just works
- Recommendations built on hundreds of millions of viewing histories

## Implementation prompt
Build a self-hosted personal media streaming server and web player. Single project, runs on my own machine, no accounts service, no cloud, no telemetry.

Stack, no substitutions:
- Node.js with TypeScript, Fastify for the API
- SQLite via better-sqlite3 for the library database
- React with Vite for the frontend, plain CSS, no component library
- ffmpeg and ffprobe invoked as child processes
- hls.js in the browser for playback

What it does:
1. Reads MEDIA_ROOT from .env and recursively scans it for video files (mp4, mkv, avi, mov). Parses filenames into title, year, and optional season/episode.
2. Runs ffprobe on each file to record duration, resolution, codecs, and audio tracks.
3. Optionally enriches each title with metadata and poster art from the TMDB API using TMDB_API_KEY from .env. If the key is missing, skip enrichment gracefully and show a generated placeholder poster.
4. Serves a library browse UI: poster grid, search, filter by movie vs series, series drilldown to seasons and episodes.
5. Plays video at /watch/:id. If the source is browser-friendly h264/aac, stream it directly with HTTP range support. Otherwise transcode on the fly to HLS with ffmpeg, segmenting into a cache directory, and serve the playlist to hls.js. Reuse cached segments on repeat plays.
6. Tracks watch progress per profile. Local profiles are just names in SQLite, no passwords, no auth provider. Resume where you left off, mark watched at 90 percent, and show a Continue Watching row.
7. Extracts embedded subtitle tracks with ffmpeg, converts to WebVTT, and exposes them as selectable tracks in the player.
8. A CLI command "npm run scan" for rescanning, plus a watcher that picks up new files while running.

Explicitly out of scope: any content acquisition, downloading, scraping, or DRM. No native mobile or TV apps. No recommendation engine beyond a recently-added row. No multi-user auth or public internet exposure; bind to localhost by default and document that exposing it is my problem.

Deliver a README with setup steps, a .env.example listing MEDIA_ROOT, TMDB_API_KEY, PORT, and TRANSCODE_CACHE_DIR, and seed the database on first run. Keep the whole thing runnable with npm install then npm run dev.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.