Disc ripping and media organization with a reactive web dashboard.
Monitors optical drives, rips with MakeMKV, identifies episodes via audio fingerprinting,
and files everything into your media library — automatically.
 Ripping a TV disc with real-time progress |
 Audio fingerprint matching with confidence scores |
 Human-in-the-loop episode review queue |
 Completed job with activity log |
- 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) - Audio fingerprint matching — identifies TV episodes via ASR transcription matched against subtitles
- 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 fingerprinting with persisted title mappings
- Responsive design — works on desktop and mobile with compact/expanded view modes
| 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.
- MakeMKV with a valid license
- FFmpeg for episode matching (audio fingerprinting). 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)
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-windows-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 |
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.
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 gpuAn 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 devOpen http://localhost:5173 in your browser. See the installation guide for distro-specific prerequisites and verification steps.
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 -dOpen 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.
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.
Full documentation is published at jsakkos.github.io/engram.
- Getting started — Installation · Configuration · Simulation · Troubleshooting
- 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
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. For bugs and feature requests, open an issue.
AGPL-3.0. See LICENSE.
- MakeMKV for disc decryption
- mkv-episode-matcher for audio fingerprinting
- TheDiscDB for disc content-hash lookups
- TMDB for media metadata and poster art
And thank you to Engram's community contributors 💜
