A local-first audit of the technical quality of your film and television library.
It reads every file on the drive, works out what each one actually is — resolution, dynamic range, Dolby Vision profile, codec, bitrate-per-pixel, lossless audio — and grades it against the best disc that was ever pressed of that title. Then it tells you which copies are worth replacing, and helps you replace them.
| Screenshots | What you are setting up |
| Requirements | Node, and five command-line tools |
| Quick start | Four commands and a browser tab |
| First run | Point it at a drive, give it a TMDb token |
| Installing it as an app | Add to Dock, and what works offline |
| How your files should be laid out | Naming that the scanner can read |
| Optional integrations | Jackett, qBittorrent, dovi_convert |
| Running it in Docker | The tools, Jackett and a VPN, in one up |
| What a scan actually does | The eight phases, in order |
| How the score is built | Weights, bands, verdicts |
| Project layout | Where things live |
| Scripts | dev, build, start, lint, test |
| Data, caches and resetting | Everything is regenerable, except two tables |
| Troubleshooting | The failures you are most likely to hit |
Library — every file, graded, grouped by verdict, worst first.
A film — two scores (against the disc, and absolute), the three components behind them, and the specific issues found.
macOS. Not a preference — the app shells out to open -R to reveal files in Finder, and it
expects external drives under /Volumes. Everything else is portable; those two are not.
| Version | Why | |
|---|---|---|
| Node.js | >= 20.9 |
Next.js 16 requires it. node -v to check. |
| npm | ships with Node | Any package manager works; the lockfile is npm's. |
Installed with Homebrew. The first is required; the rest unlock features.
| Tool | Formula | Required? | What it does here |
|---|---|---|---|
| MediaInfo | brew install mediainfo |
Yes | The whole scan. Every codec, resolution, HDR format, audio track and encoder string comes from one mediainfo --Output=JSON call per file. Without it, nothing is graded. |
| ffmpeg | brew install ffmpeg |
Recommended | Demuxes the HEVC stream so the Dolby Vision RPU can be read. Without it, DV files are graded from the container's profile alone. |
| dovi_tool | brew install dovi_tool |
Recommended | Parses that RPU — the enhancement-layer type (MEL / simple FEL / complex FEL), CM version, L1 light levels and per-frame coverage. This is what decides whether a Profile 7 file can be safely flattened. |
| dovi_convert | brew install dovi_convert |
Optional | Runs the Profile 7 → 8.1 conversion from inside the app, and the rebuild back out of it. It keeps the original beside the result, refuses a complex FEL on its own, and — when asked — sets the discarded enhancement layer aside in an archive small enough to keep for good. |
| MKVToolNix | brew install mkvtoolnix |
Optional | Only for the by-hand conversion recipe the app prints (mkvmerge). Not called by the app itself. |
All five in one go:
brew install mediainfo ffmpeg dovi_tool dovi_convert mkvtoolnixOr skip all five — the Docker image has them baked in.
| Cost | Needed for | |
|---|---|---|
| TMDb read access token | Free | Titles, posters, backdrops, collections, episode lists, runtimes. Sign in at themoviedb.org and copy the API Read Access Token (the long v4 JWT — not the short v3 API key). |
# 1. Clone
git clone <your-remote> ripgrade && cd ripgrade
# 2. Install the command-line tools
brew install mediainfo ffmpeg dovi_tool
# 3. Install dependencies
npm install
# 4. Run it
npm run devOpen http://localhost:3000.
The library will be empty — that is expected. Nothing has been pointed at a drive yet.
Note
There is no .env to fill in to get started. The TMDb token and both integrations are configured
from the Settings page and stored in the local database, because the one setting standing
between a fresh install and every poster in your library should not be one that requires a
server restart.
Settings → Library folders → Add folder.
A folder browser opens at /Volumes, so external drives are one click away. Add as many as you
like — a collection outgrows a drive, and the app has no opinion about them living together.
Then press Scan library, in the same section. (Adding a folder only registers it; the scan is the deliberate step, and it also runs by itself on every server start.)
Settings → TMDb.
Paste the v4 read access token and save. The app checks it before storing.
Until this is set the library still works — files are probed and graded on the rubric alone — but there are no posters, no titles beyond what the filename says, no collections, and no disc comparison. It is worth doing first.
The first scan is the slow one: every file is read by MediaInfo, every Dolby Vision file has its RPU head-scanned, every title is matched against TMDb, artwork is downloaded and Blu-ray.com is asked what the best pressing of each film was. Progress runs in the left rail throughout.
Every scan after that reuses the cache and only re-probes files whose size or modification time changed.
Tip
The app rescans itself on every start. The drive changes while the app is not running, so booting it is what refreshes it. The button in Settings is for when you have just moved a file and do not want to wait.
Ripgrade ships a web app manifest, so it can leave the browser and live in the dock with its own icon and its own window — no address bar, no tab strip, and a name in the menu bar.
macOS, Safari — open the app, then File → Add to Dock. Safari picks up the name, the skull and the window shape from the manifest. This is the one that behaves most like a native app: it gets a Dock icon you can keep, and ⌘Q quits it.
Chrome, Edge, Arc — an install button appears at the right of the address bar, or use ⋮ → Cast, save and share → Install page as app. Right-clicking the resulting icon offers Library, Queue and Jobs directly.
Note
Service workers — and so the offline page below — only run on a secure origin. localhost
counts as one; the same app opened from another machine at http://your-nas.local:6969 does not,
unless you put it behind HTTPS. Installing to the dock works either way.
The one thing cached is a fallback page shown when the server cannot be reached at all — the machine it runs on is asleep, or the laptop is off the network. Nothing about the library is stored offline, because none of it would still be true by the time you read it.
The scanner walks each library folder recursively and picks up
.mkv .mp4 .m4v .avi .mov .ts .m2ts .mpg .mpeg .wmv .webm.
One film per folder, named so the title and year are recoverable:
/Volumes/Films/
├── Dune Part Two (2024)/
│ ├── Dune.Part.Two.2024.2160p.UHD.BluRay.REMUX.DV.HDR.TrueHD.7.1.Atmos-GROUP.mkv
│ ├── poster.jpeg ← optional; downloaded from TMDb if absent
│ ├── fanart.jpeg ← optional
│ └── logo.png ← optional (`clearlogo.png` is also recognised)
└── Heat (1995)/
└── Heat.1995.2160p.UHD.BluRay.REMUX.DV.HDR.DTS-HD.MA.5.1-GROUP.mkv
Scene-style release names are read, not merely tolerated: REMUX, WEB-DL, BluRay, 2160p,
REPACK, PROPER and encoder tags all feed the release score. A filename claiming REMUX
over an x265 stream is caught and reclassified — the container is checked against the claim.
Season folders inside a show folder, episodes numbered SxxEyy:
/Volumes/Shows/
└── Severance/
├── Season 01/
│ ├── Severance.S01E01.2160p.ATVP.WEB-DL.DV.HDR10+.DDP5.1.Atmos-GROUP.mkv
│ └── Severance.S01E02...
└── Season 02/
Season 01, season.1, S01 and similar all match. The show folder — the one above the season
folders — is where artwork is looked for.
Both can be named in the environment. For Jackett that is a default rather than a lock: the Settings page wins, so a stack that ships its own Jackett works on the first page load and you can still paste a new key when one rotates — Use the environment puts it back. qBittorrent is still read from the environment first, falling back to Settings.
Jackett is a local proxy that holds your indexer logins and exposes them all as one Torznab feed. Ripgrade talks to one URL on your own machine and never contacts a tracker directly. Everything it does is read-only: a search returns names, sizes and links.
Settings → Jackett — paste the URL (typically http://localhost:9117) and the API key from
Jackett's own dashboard.
Once connected, the Queue page fills itself: a sweep searches for a better copy of every film below your score threshold, and the wishlist pass searches for the films you do not have yet.
Settings → qBittorrent — paste the WebUI URL (typically http://localhost:8080). Username and
password are optional: qBittorrent's bypass authentication for localhost is common, and demanding
credentials it will not ask for is a hurdle for nothing.
Everything sent from the app is tagged with the category ripgrade, so the queue's Wishlist tab only
ever lists what it added. Your other torrents are none of its business.
Create .env in the project root to have these set for you:
JACKETT_URL=http://localhost:9117
JACKETT_API_KEY=your-jackett-api-key
QBITTORRENT_URL=http://localhost:8080
QBITTORRENT_USERNAME=admin
QBITTORRENT_PASSWORD=your-passwordThe Jackett pair is a starting point: connecting Jackett from Settings replaces it, and disconnecting there goes back to it. The qBittorrent trio still overrides Settings.
Important
The TMDb token is deliberately not readable from the environment. It lives in the database and is set from Settings, so there is exactly one place it comes from and one place to change it.
With dovi_convert installed, a Profile 7 film's page gains a working Convert console: it runs
a full-frame RPU scan first, then hands the whole job to dovi_convert, which renames the original
aside rather than deleting it and verifies the result before declaring success.
Settings → Conversion scratch space picks where the working video file lands — a 90 GB remux needs somewhere to go, and that is not a decision an audit tool should make for you.
Settings → Going back to Profile 7 decides whether a conversion keeps the enhancement layer it
discards. On by default, the layer is pulled out into a Film.dovi archive beside the film first — a
tenth to a quarter of the film for a FEL, a couple of gigabytes for a MEL — and the film's page then
offers Rebuild Profile 7, which puts the layer back into the base layer and remuxes the two into
a Profile 7 file again. That is what makes deleting the 90 GB original a reversible decision rather
than a final one. Turning it off saves a pass over the whole film before every conversion, at the
price of a conversion that is final once that original has gone.
Without it, the same page still prints both recipes (dovi_convert, and the by-hand
ffmpeg | dovi_tool + mkvmerge pair) ready to copy into a terminal — and, on a film with its
layer kept, the two that rebuild it.
The five command-line tools are the fiddly half of the install, so there is an image with all of
them already in it: MediaInfo and ffmpeg and mkvmerge from Debian, dovi_tool as its static
release binary, and dovi_convert — which turns out to be one Python file with nothing but the
standard library behind it — fetched at build time. Nothing to brew install.
docker-compose.yml brings up three containers and one that exits:
| What it is | |
|---|---|
| dns | CoreDNS, forwarding every lookup over TLS to Cloudflare. Not a VPN, and that is the point — see below. |
| jackett-init | Runs once, before Jackett, and puts the API key and a starter set of indexers where both sides can find them. Then it is gone. |
| jackett | The indexer proxy, told to resolve through dns and nothing else. |
| ripgrade | The app, with the drive bound in. On the default resolver: TMDb and Blu-ray.com are not names anybody is blocking. |
cp .env.docker.example .env # a key you generate, and where Jackett keeps its config
docker compose up -d --buildThe app is on http://localhost:6969, Jackett's dashboard on http://localhost:9117 — on its own port, on the network it shares with the app.
Not 3000: that port belongs to next dev, and running the container and the dev server at the
same time should not be a choice. RIPGRADE_PORT in .env moves it.
The drive is bound at the same path it has on the host. /Volumes:/Volumes, not
/Volumes:/media — so every absolute path already in the database still resolves, and a library
scanned outside the container is the same library inside it. Docker Desktop shares /Volumes by
default; if you have narrowed that, it is Settings → Resources → File sharing.
Important
A drive plugged in after the container started may not appear inside it — the share is
established when the container is, and Docker Desktop does not always propagate a later mount.
Mount the drive first, then docker compose restart ripgrade.
There is no API key to go and fetch. Ordinarily Jackett invents one on first start and you open its dashboard to copy it out. Here you choose it instead:
openssl rand -hex 16 # into JACKETT_API_KEY in .envjackett-init writes that key into Jackett's ServerConfig.json before Jackett has ever run, and
Jackett — which only generates a key when it does not already have one — keeps it. The same value
reaches the app as JACKETT_API_KEY, so the two come up already agreeing and Settings → Jackett
reads Set by the environment on the first page load.
It is safe on an existing install: the config is parsed and patched rather than rewritten, so the
indexers and the admin password survive a key change. Leave JACKETT_API_KEY blank and the old
behaviour is exactly what you get — Jackett generates its own, and you paste it into Settings.
Note
http://jackett:9117 is the address, not localhost — container to container, by service name.
That is already in .env.docker.example.
Three indexers come pre-configured, for the same reason and by the same route: The Pirate Bay,
TorrentDownload and LimeTorrents. All three are public, so a configured one is nothing but a site
address and a sort preference — no login, nothing encrypted, nothing tied to the machine that
wrote it. The files in docker/jackett-indexers/ are Jackett's own output, captured once, and
jackett-init copies them in before Jackett starts. The Queue works on the first page load.
Only ever into a fresh Jackett. Once it has indexers of its own, the set is yours — dropping one
you did not want should not be undone by the next up. JACKETT_SEED_INDEXERS=0 starts empty.
Private trackers stay manual, and should: their configs carry logins, passkeys and cookies, which is not something to keep in a repo. Add those at http://localhost:9117.
No VPN, deliberately. The trackers are blocked by name, not by address: the ISP answers one
sinkhole for torrentdownload.info, 1337x.to and thepiratebay.org alike, and TLS then fails
against a block page. So the stack runs CoreDNS forwarding over TLS instead, and Jackett resolves
through it — a fix scoped to the one container that needed it, with no subscription and nothing
else on the machine rerouted. The diagnosis is in
docs/Indexer_Connectivity_Fix.md.
Reveal in Finder. There is no Finder in a container, so the button is not drawn — everything else on the film page works unchanged. Convert, audio strip and cleanup all write through the bind mount, and the files land on the host owned by you.
On macOS, every byte the app reads travels through Docker Desktop's file sharing. MediaInfo
only reads headers and barely notices. A dovi_convert run is a 90 GB remux through that same
mount, and it will be meaningfully slower than running the app natively. On Linux, where the drive
is just mounted, none of this applies.
Rebuild costs, what survives a down, running the container and next dev side by side, and the
failures in the order they happen: docs/Docker_Runbook.md.
Eight phases, in order, each visible in the left rail as it runs:
| # | Phase | What happens |
|---|---|---|
| 1 | Walk | Every library folder is walked recursively; video files are collected. Files that vanished since last time are marked absent. |
| 2 | Probe | mediainfo --Output=JSON per file. Cached by path + size + mtime, so unchanged files cost nothing on a rescan. |
| 3 | Dolby Vision | For DV files not yet read: ffmpeg demuxes the HEVC head and dovi_tool parses the first 300 frames. Under a second even on a 90 GB remux; everything structural is fixed at authoring time and correct from frame one. |
| 4 | Match | Each title is searched on TMDb. A result with no match is recorded as "searched, found nothing" so it is not retried every run. |
| 5 | Artwork | Missing posters, backdrops and logos are downloaded to sit beside the film. Files on the drive always win over anything cached. |
| 6 | Discs | Blu-ray.com is asked what the best commercial release of each film — and each season — actually is. Cached forever; refetching is slow and someone else's bandwidth. |
| 7 | Sweep | With Jackett connected, every film below the queue threshold is searched for a better release. |
| 8 | Wishlist | The films you want but do not have are searched for too. |
Three components, weighted:
| Component | Weight | Built from |
|---|---|---|
| Video | 45% | Resolution (2160p 60 / 1080p 40 / 720p 22 / SD 10), dynamic range (Dolby Vision 22 / HDR10+ 20 / HDR10 15 / SDR 0), 10-bit, remux status, and bits-per-pixel-per-frame. |
| Audio | 30% | Lossless 65 / lossy 35, object-based formats (Atmos, DTS:X) +25, and channel count (8ch +10 / 6ch +6). |
| Release | 25% | REMUX 100, WEB-DL 72, unknown 45, and encodes graded 30 – 75 by bitrate density — using the encoder actually found in the stream, not the one the filename claims. |
The weighted total is then capped at video + 15, so no amount of Atmos rescues a bad picture.
Each file gets two numbers: an absolute score against the rubric, and a vs disc score against the best pressing that exists. A 1080p file of a film never released above 1080p is not punished for the resolution it could never have had.
The verdict comes from the score:
| Band | Verdict | Priority |
|---|---|---|
| 90 + | Reference | None |
| 78 – 89 | Excellent | None |
| 62 – 77 | Good | Low |
| 45 – 61 | Upgrade Recommended | Medium |
| 0 – 44 | Must Upgrade | High |
Alongside the score, a catalogue of specific issues is checked — very low bitrate for the resolution, a REMUX claim with no lossless track, runtime drift against TMDb, a disc that is demonstrably better than the copy you hold, and more. The How it works page inside the app renders the entire rubric verbatim from the source, so it can never drift from what actually runs.
ripgrade/
├── app/ # Next.js App Router — every page and server action
│ ├── page.tsx # Library
│ ├── film/ episode/ show/
│ ├── collections/ wishlist/ stats/
│ ├── upgrades/ compare/ downloads/ search/ discover/
│ ├── settings/ how-it-works/
│ ├── api/ # Job event stream, artwork proxy
│ ├── globals.css # Design tokens; every border and radius resolves here
│ ├── manifest.ts # What makes it installable as an app
│ └── layout.tsx # Fonts, sidebar, job providers
├── public/ # Icons, and `sw.js` — the offline fallback, nothing more
├── lib/ # All server logic. `server-only` throughout.
│ ├── scanner.ts # The scan, phase by phase
│ ├── media.ts # MediaInfo
│ ├── dovi.ts # ffmpeg + dovi_tool RPU analysis
│ ├── derive.ts # The rubric — scores, bands, issue catalogue
│ ├── library.ts # Probes → graded library
│ ├── tmdb.ts disc.ts bluray.ts tv*.ts
│ ├── jackett.ts torznab.ts qbittorrent.ts
│ ├── convert.ts # dovi_convert orchestration, both directions
│ ├── thumbs.ts # sharp-backed poster cache
│ └── db.ts # SQLite schema, one file, no migrations
├── test/ # node:test suites over the pure logic
├── data/ # ← generated, git-ignored
├── docs/ # Specs, plans, and these screenshots
└── instrumentation.ts # The scan that runs on every server start
| Command | What it does |
|---|---|
npm run dev |
Dev server with Turbopack on :3000. Scans on boot. |
npm run build |
Production build. The boot scan is skipped during builds. |
npm run start |
Serve the production build. |
npm run lint |
ESLint, Next's config. |
npm test |
Type-checks tsconfig.test.json into data/_test/, then runs node --test over the compiled suites. |
Everything the app stores lives in data/, which is git-ignored:
data/
├── medlib.db # SQLite — probes, matches, TMDb records, disc lookups, settings
├── medlib.db-wal # WAL, so a long scan can write while pages read
├── collections/ # artwork for sets of your own
└── thumbs/ # sharp-generated poster cache, three widths
Settings → Files → Data folder. Pick a folder, and the store is copied there; restart and the app reads it from its new home. Nothing is deleted — the old copy stays where it was, for you to remove once the library has come back up.
Worth doing if you run from source. next dev watches the project folder and Turbopack offers no
way to exclude a path from that — watchOptions is a poll interval and nothing more. So the
write-ahead log, rewritten continuously for the length of a scan, and every thumbnail generated while
you browse, arrive as change events on the dev server's own file watcher. A server left running
through an afternoon of scanning pays for that in memory, and does not give it back.
The choice is written to .ripgrade-data-dir, one line holding one absolute path, git-ignored. It
cannot be a row in the settings table for the obvious reason: that table is inside the database whose
location it would be naming.
RIPGRADE_DATA_DIR overrides it where it is set, and Docker sets it — see below. The Settings row
says so and stops offering to move anything.
The database is a cache, not a source of truth. Almost everything in it is derived from files on
disk, so if the schema ever needs to change the intended fix is to delete data/medlib.db and
rescan rather than to write a migration.
Two things are not derived and will not come back:
- Your wishlist — a list you wrote.
- Your triage decisions — issues you acknowledged, notes you left.
The expensive table is probes: rebuilding it means re-reading the whole drive. Re-deriving
everything else from it costs milliseconds.
# Nuclear reset — rescans from scratch on next start
rm -rf data/
# Just the thumbnails (also a button in Settings)
rm -rf data/thumbs/| Symptom | Cause | Fix |
|---|---|---|
| Every file fails to probe | mediainfo is not on PATH |
brew install mediainfo, then rescan from Settings |
| Dolby Vision files show a profile but no layer type | ffmpeg or dovi_tool missing |
brew install ffmpeg dovi_tool |
| No posters, no titles, no collections | No TMDb token | Settings → TMDb; use the v4 read access token, not the v3 key |
| A whole folder disappeared from the library | The drive is not mounted | The scan reports skipped roots rather than deleting them; plug the drive in and rescan |
| Queue is empty even with films below threshold | Jackett unreachable, or no indexers configured in Jackett | Check Jackett's own dashboard first, then Settings → Jackett |
| Sending a magnet does nothing | qBittorrent WebUI not enabled | Enable it in qBittorrent's preferences, then Settings → qBittorrent |
Another next dev server is already running |
A previous npm run dev is still alive |
The message prints the PID — kill <pid> — or just use the port it names |
| Convert button is missing on a Profile 7 film | dovi_convert not installed |
brew install dovi_convert. The page still prints the manual recipes either way. |
A note on scope. Ripgrade audits files you already have and points at where better copies exist. It never fetches a torrent or contacts a peer itself — Jackett reads public feeds, qBittorrent does the transferring, and both are yours to configure. What you do with the information is your call and your responsibility.
Built with Next.js · React · TypeScript · Tailwind · SQLite · sharp



