Portable Player

A self-hosted personal movie & TV library — like Plex, but yours. Point it at a folder, and it parses the messy filenames, fetches posters and metadata, organizes everything into a clean, searchable library, and gives you a cinematic browse-and-watch experience. The same app runs as a local desktop app or a headless server you reach from any browser on your network.

What it does

• Point at a folder of movies and TV shows — nested any way you like.
• Understands real-world names — scene releases, YTS/RARBG, anime fansubs with [Group] tags and absolute episode numbers, S07E01, specials (S00), multi-episode files, quality/codec/HDR tags. (Validated against a 105-file real library: every file parsed.)
• Rich metadata from TMDB (bring your own free API key): posters, backdrops, overviews, genres, cast, and per-episode titles/stills. No key? You still get a fully browsable library from the filenames alone.
• A beautiful library — featured hero, "Continue Watching", "Recently Added", genre rails, a filterable/searchable poster grid, and detail pages with cast and technical specs.
• In-app playback — a custom player with seek, volume, playback speed, fullscreen, subtitle selection (sidecar .srt/.ass and embedded tracks, served as WebVTT), and resume / continue-watching. Files in codecs the browser can't decode (HEVC, AV1, Dolby AC3/EAC3, DTS) are transcoded on the fly to H.264/AAC — copying the streams it can play and only converting what it must.
• Fix a wrong match — search TMDB from the detail page and pick the right title; metadata and episodes update in place.
• Runs anywhere you want — a local Windows app, or a headless server on a NAS/mini-PC that you reach from any device. One codebase, both modes.
• Never holds your files hostage — the database is a disposable cache that rebuilds from a rescan. Files are only moved if you explicitly opt in.

Quick start (Windows, local)

1. Install Node.js 20+.
2. Double-click start.bat. The first run installs dependencies, builds the UI, starts the server, and opens http://localhost:8730.
3. In Settings, add your media folder (e.g. D:\Portable Player) and optionally paste a free TMDB API key.
4. Watch it scan, then browse and play.

Prefer the command line?

npm install
npm run build:web
npm start         # → http://localhost:8730

For live development with hot reload:

npm run dev       # server (8730) + Vite UI (5274) together

See SETUP.md for the desktop app, server/LAN mode, and troubleshooting.

How it works

 pick a folder ─▶ scan files ─▶ parse names ─▶ ffprobe ─▶ match on TMDB
                                                                │
   beautiful UI ◀── REST API ◀── SQLite library ◀── cache art ─┘

The backend (Node + Express + SQLite) does all the work and serves a REST API plus range-based video streaming. The frontend (React + Vite + Tailwind) is a single-page app. Electron wraps the exact same server for the desktop build.

See ARCHITECTURE.md for the full design and ROADMAP.md for status.

Project layout

packages/
  shared/    domain types & API contracts (the spine)
  server/    the engine (parser, scanner, probe, matcher, organizer) + REST API
  web/       React browsing UI + video player
  electron/  desktop shell + Windows packaging

Tech

TypeScript everywhere · Node 20+ · Express · SQLite (better-sqlite3, with a built-in node:sqlite fallback) · TMDB · ffprobe/ffmpeg · React 18 · Vite · Tailwind · Electron.

License

MIT.