One media collection. Many libraries. Keep your originals where they are.
Catabolic is a command-line media catalog for files spread across drives and mounted storage. Identify and tag your media, search it with SQL or GraphQL, and publish selected files into folders your apps understand. Generated symlink libraries point back to your existing files, so the same collection can have several layouts without duplicating the media.
For example, a film on your NAS can appear in both a Plex library and a favorites folder, each with its own naming scheme. An optional processing rule can create a smaller version in separate storage and publish it to another library. Catabolic records which original each generated version came from.
Get started · Documentation · FAQ
- Bring scattered media into one catalog. Inventory movies, TV, music, books, photos, documents, and more. Search recorded metadata even when a drive is offline.
- Curate once, publish in several places. Add identities, tags, and relationships; save selections and generate app-specific or custom folder layouts.
- See what needs attention. The work inbox brings together unidentified files, pending reviews, failed processing, and publication work.
- Make and track additional versions. Use optional FFmpeg recipes for previews, remuxes, and transcodes, or register results from external processors. Review storage estimates before queuing work.
- Keep libraries up to date. Opt into watchers for scheduled scans and query-driven work, and connect published outputs to Plex or Jellyfin for library refreshes.
Requires Python 3.11+ on macOS or Linux. Catabolic is currently alpha.
python3 -m venv ~/.venvs/catabolic
. ~/.venvs/catabolic/bin/activate
python -m pip install catabolic
catabolic --helpSee installation for pipx, checkout installs, and upgrades.
Repository documentation may describe changes beyond the installed release;
catabolic docs opens the guides bundled with your version.
The first-catalog walkthrough takes a disposable sample file from inventory to identification to a verified symlink library. It needs no media server, API key, or FFmpeg installation.
To start inventorying your own media, create a workspace on a local disk, outside
your source folders. Replace /path/to/your/media before running:
mkdir -p ~/catabolic-workspace/state
cd ~/catabolic-workspace
export CATABOLIC_DB="$PWD/state/catalog.sqlite3"
export CATABOLIC_PROFILE=default
catabolic init
catabolic location bind media --root /path/to/your/media
catabolic scan
catabolic --json files --unidentified --limit 20This records files in the catalog. Identifying them and publishing a library are
separate steps; continue with the recommended workflow.
Keep CATABOLIC_DB and CATABOLIC_PROFILE set when returning in another terminal.
Scans default to common media extensions. Scan policies let you add file types, scan all files, or use include/exclude patterns. Filtering retains recorded history and does not establish that a file is missing. Scans also report unfinished work; see coverage and continuation.
Catabolic stores media identities, file locations, relationships, and processing results in SQLite. Three reusable definitions turn that catalog into workflows:
| Definition | What it does | Example |
|---|---|---|
| Query | Selects catalog records using SQL or GraphQL | Movies without a recorded transcode |
| Rule | Applies an explicit processing or analysis operation to a selection | Generate a smaller version of each selected movie |
| Projection | Maps query results to an output layout or destination metadata | Build a library or curate genres and collection membership |
Processing results become catalog evidence. On the next evaluation, a query for missing versions stops selecting items whose results have been recorded. Queries can also feed projections directly when no processing is needed. Destination mappings apply query results to Plex/Jellyfin metadata and collections, all folder presets, calibre/Immich imports, and NFO/OPDS/XSPF exports. Each operation declares its verification and recovery capabilities and requires a reviewed plan.
Preview the selection and planned changes, execute a bounded batch, then verify the result. Jobs and filesystem journals support recovery after interruptions. Start with the query, rule, and projection guide.
Folder presets include Plex, Jellyfin, Emby, Kodi, Infuse, Navidrome, Audiobookshelf, Komga, and Kavita. A preset controls folder naming; API integration is a separate capability. See application compatibility for requirements and the full list.
For Plex and Jellyfin, consumer bindings connect published outputs to an existing server library and can request scans after publication. Plex also supports browser sign-in, explicit library creation, and metadata import from an existing library to help identify files you have already scanned. You can also match existing published files and publish curated metadata to Plex, with a field-by-field preview and verification.
A media server must be able to read both the symlinks and their source targets. An accepted scan request does not prove indexing completed; see the consumer validation record for tested behavior and live-service qualification limits.
Use the CLI's global --json option and exit codes in scripts and agent workflows.
Saved queries, explicit previews, and the work inbox provide a shared workflow
for people and automation. See automation,
SQL queries, and GraphQL.
The optional HTTP backend exposes authorized queries, metadata, media content, and durable rendition requests. It includes scoped tokens, OpenAPI and GraphQL contracts, and a TypeScript client contract. Serving content and enabling processing require explicit configuration.
Catabolic preserves source media. Symlink publication creates managed output folders; processing creates separate files. Explicit application imports, such as calibre or Immich imports, copy or upload selected media.
Generated libraries depend on their sources and are not backups. Start with a small collection, keep backups, and preview changes before applying them.
| Next step | Guide |
|---|---|
| Identify, curate, and publish your first collection | Recommended workflow |
| Review outstanding work and completion requirements | Work inbox · Worklogs |
| Schedule scans and maintain outputs | Watchers · Maintenance |
| Generate previews, remuxes, or transcodes | Processing rules · External processors |
| Handle offline sources and choose fallback versions | Fallback policies · Source trust |
| Upgrade or diagnose a problem | Database migrations · Troubleshooting |
| Contribute or publish a release | Development · Release testing |
All guides are also available offline with catabolic docs.
MIT License. Copyright 2026 Jaga Tranvo and The Catabolic Contributors.