Screenshots
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.
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
And thank you to Engram's community contributors 💜
