Engram

Disc ripping and media organization with a reactive web dashboard.
Monitors optical drives, rips with MakeMKV, identifies episodes by transcribing
the audio and matching it against reference subtitles,
and files everything into your media library — automatically.

---

Screenshots

Ripping a TV disc with real-time progress	Episode matching with confidence scores
Human-in-the-loop episode review queue	Completed job with activity log

Features

• Automatic disc detection — monitors optical drives and starts processing on insertion
• Smart classification — distinguishes TV shows from movies using duration analysis, TMDB lookup, and TheDiscDB; uses the MakeMKV disc name as a TMDB fallback for merged-word volume labels (e.g. STRANGENEWWORLDS_SEASON3)
• Episode matching — identifies TV episodes by transcribing the audio and matching it against reference subtitles
• Acoustic fingerprint network — a shared catalog of chromaprint audio fingerprints that identifies episodes without needing subtitles for the show. No audio or video leaves your machine; see Contributing Data
• LLM episode matching (opt-in) — when audio matching is uncertain, send the transcript + TMDB synopses to your configured AI provider for a suggested episode (Gemini, Anthropic, OpenAI, or OpenRouter). Always confirmed via the review queue.
• Subtitle downloads — fetches subtitles via the OpenSubtitles.com REST API (preferred, free tier available) with Addic7ed as fallback
• Real-time dashboard — web UI with WebSocket live updates, progress tracking, and notifications
• Human-in-the-loop — review queue for low-confidence matches, unreadable disc labels, and ambiguous content with a pre-filled correction modal
• Job history & analytics — searchable archive of all completed/failed jobs with drill-down detail panel, processing timeline, and TheDiscDB metadata
• TheDiscDB integration — automatic disc identification via content-hash disc lookup with persisted title mappings
• Contribute back — share disc layouts with TheDiscDB so others can identify the same pressings automatically. Opt in under Settings → TheDiscDB Contributions
• Responsive design — works on desktop and mobile with compact/expanded view modes

Platform support

Feature	Windows	Linux	macOS
Automatic drive detection	Yes	Yes	No
Staging folder auto-import	Yes	Yes	Yes
MakeMKV ripping	Yes	Yes	Yes
Episode matching (ASR)	Yes	Yes	Yes
Web dashboard & API	Yes	Yes	Yes
Tool auto-detection	Yes	Yes	Yes
TheDiscDB / TMDB lookup	Yes	Yes	Yes

Windows has full automatic disc detection via kernel32 APIs. Linux has native optical-drive detection via /sys/block and blkid. On macOS, the backend and dashboard run fully, but disc insertion must be triggered via the staging import API.

On all platforms, Engram supports a staging folder workflow: drop a folder of pre-ripped MKV files into the staging directory and Engram will auto-detect, classify, match, and organize them. This is the primary workflow on systems without optical drives. See Linux / macOS setup for details.

Prerequisites

• MakeMKV with a valid license
• FFmpeg for episode matching (audio extraction and transcription). Engram auto-detects it on your PATH — see installing FFmpeg, or Troubleshooting if it isn't found
• A TMDB API Read Access Token (v4) from TMDB
• If running from source: Python 3.11–3.13 with uv, and Node.js 24 (Python 3.14 is not yet supported — some ML dependencies have no 3.14 wheels)

Install

Option A: Standalone executable (Windows, Linux, macOS)

No Python or Node.js required — the Config Wizard opens in your browser on first launch. Download the build for your platform from the Releases page, extract it, and run the engram executable:

Platform	Download	Run
Windows	engram-win-x64.zip	engram.exe
Linux (x64)	engram-linux-x64.tar.gz	./engram/engram
Linux (arm64 / Jetson)	engram-linux-arm64.tar.gz	./engram/engram
macOS	engram-macos-arm64.tar.gz	./engram/engram

Keep your libraries, staging folder and backups outside the folder you extract Engram into: an update replaces that whole folder.

On Linux arm64 (e.g. NVIDIA Jetson), download engram-linux-arm64.tar.gz. ASR runs on the CPU out of the box; GPU acceleration needs an on-device build step — see Jetson setup.

On macOS, download engram-macos-arm64.tar.gz. It runs natively on Apple Silicon (M1/M2/M3/M4) and transparently on Intel Macs via Rosetta 2. macOS has no automatic optical-drive detection — use the staging-folder workflow (see Linux / macOS setup).

FFmpeg is required for episode matching. Engram auto-detects it on your PATH (Windows: winget install Gyan.FFmpeg, then restart Engram). If the Config Wizard reports FFmpeg missing, see installing FFmpeg and Troubleshooting.

Option B: From source (all platforms)

git clone https://github.com/Jsakkos/engram.git
cd engram

# Backend
cd backend
uv sync
cd ..

# Frontend
cd frontend
npm install
cd ..

For GPU-accelerated transcription (optional):

cd backend
uv sync --extra gpu

An NVIDIA GPU speeds up episode matching considerably. GPU acceleration is opt-in: enable it in Settings → Matching → GPU Acceleration, which downloads the CUDA runtime on demand — this works in the prebuilt standalone build too (macOS and AMD GPUs run on CPU). The uv sync --extra gpu above is the from-source shortcut that installs those libraries via pip. See Performance & Hardware for GPU setup, storage recommendations, and concurrency tuning.

Then start the two dev servers in separate terminals:

# Backend (API on port 8000)
cd backend
uv run uvicorn app.main:app

# Frontend (dashboard on port 5173)
cd frontend
npm run dev

Open http://localhost:5173 in your browser. See the installation guide for distro-specific prerequisites and verification steps.

Option C: Docker (Linux)

Run Engram as a container with the optical drive passed through from the host:

git clone https://github.com/Jsakkos/engram.git
cd engram
# Set MAKEMKV_APP_KEY (and PUID/PGID) in docker-compose.yml, then:
docker compose up -d

Open http://localhost:8000 and complete the setup wizard. MakeMKV is compiled into the ./config volume on first start (one-time), so the image itself ships no MakeMKV binaries. Optical-disc ripping requires a real Linux host with a drive — Docker Desktop on Windows/macOS can run the UI but can't pass through /dev/sr0. See the Docker deployment guide for volumes, device passthrough, GPU notes, and troubleshooting.

Configuration

On first launch the Config Wizard walks you through setup: MakeMKV path, library paths, TMDB token, and more. Settings are stored in the database and editable from the Settings page.

• TMDB: the wizard asks for a Read Access Token (v4 auth) from your TMDB API Settings. This is the long JWT string starting with eyJ..., not the shorter v3 API Key.
• OpenSubtitles (optional): for more reliable subtitle downloads, configure an OpenSubtitles.com account (free tier: 5 downloads/day; consumer API keys at opensubtitles.com/consumers). Without credentials, Engram falls back to scraping Addic7ed.

An optional backend/.env file can override server-level defaults:

Variable	Description	Default
DATABASE_URL	SQLite connection string	sqlite+aiosqlite:///./engram.db
HOST	Server bind address	127.0.0.1
PORT	Server port	8000
DEBUG	Enable simulation endpoints	false

See the configuration guide for the full walkthrough and field reference.

Documentation

Full documentation is published at jsakkos.github.io/engram.

• Getting started — Installation · Configuration · Simulation · Troubleshooting · Getting Help
• User guide — Dashboard · Import Watch Folder · Performance & Hardware · Review Queue · Job History · Linux / macOS setup
• Architecture — Overview · State Machine · WebSocket Protocol
• API reference — REST Endpoints · Data Models
• Development — Contributing · Testing · Subtitle Cache Build
• Changelog

Community

Questions, ideas, or just want to share what you're ripping? Join the Engram community on Discord. It's the fastest way to get help, follow development, and talk to other users.

Bugs and feature requests: in Discord, run /bug or /feature. Trace, our support bot, asks for what's missing, checks for an existing issue, and drafts a GitHub issue that you file with one click. Attach the job's diagnostics bundle and it reads the logs for you. For a quick question, post in the #ask-engram forum, mention @Trace, or use /ask. Prefer GitHub? Open an issue directly. Full guide: Getting Help & Reporting Issues.

License

AGPL-3.0. See LICENSE.

Acknowledgments

• MakeMKV for disc decryption
• mkv-episode-matcher for episode matching
• TheDiscDB for disc content-hash lookups
• TMDB for media metadata and poster art
• Episode data for TheTVDB-numbered shows is provided by TheTVDB.

And thank you to Engram's community contributors 💜