Alchemist documentation / A Dead Signal Works project
Alchemist.
Alchemist is a self-hosted, AGPLv3 transcoding pipeline that scans your media library and encodes only what's worth encoding, using NVENC, Intel Quick Sync, VAAPI, AMF, or Apple VideoToolbox.
Alchemist scans your media library, analyzes every file, and decides whether transcoding it would actually save meaningful space. If a file is already efficiently compressed, it skips it and tells you exactly why in plain English. If it can save space without hurting quality, it encodes it using whatever hardware you have, on your schedule.
Your originals are never touched until the new file passes quality validation. Nothing is deleted until you say so.
Alchemist is AGPLv3 open source. There is no paid tier, no private “pro” build, no license key, and no phone-home check.
What it does
- Scans configured library directories and queues files for analysis
- Runs FFprobe on each file to extract codec, resolution, bitrate, HDR/color data, audio/subtitle facts, and cheap structure metadata
- Builds factual analyzer labels and metrics, then applies BPP (bits-per-pixel) analysis and size thresholds to decide whether transcoding is worth it
- Selects the best available encoder automatically (NVIDIA NVENC, Intel QSV, AMD VAAPI/AMF, Apple VideoToolbox, CPU fallback) and caches valid hardware detection across repeat boots
- Encodes to AV1, HEVC, or H.264 based on your configured target
- Validates output quality (optional VMAF scoring) before promoting the result
- Tells you exactly why every skipped file was skipped
- Supports named API tokens for observability, full automation, and Sonarr/Radarr webhook ingress
- Exposes a read-only MCP server for local assistant integrations
- Can be served under a path prefix such as
/alchemist - Includes an experimental single-file Conversion / Remux utility with command preview and source/output estimates
- Expands Library Intelligence beyond duplicate detection into storage-focused recommendations
- Sends notifications through Discord, Gotify, ntfy, Telegram, email, or webhooks, with quiet hours for non-critical events
What it is not
Alchemist is not Tdarr and not FileFlows. It does not try to be a visual workflow product, a plugin marketplace, or a general-purpose file automation suite. It is one application for one job: decide what media is worth optimizing, encode it safely, and explain every decision.
Hardware support
Alchemist detects and selects the best available hardware encoder automatically (NVIDIA NVENC, Intel QSV, AMD VAAPI/AMF, Apple VideoToolbox, or CPU fallback). Repeat boots reuse a valid cached detection result when the OS, architecture, FFmpeg/FFprobe versions, and hardware settings have not changed.
For detailed codec support matrices (AV1, HEVC, H.264) and vendor-specific setup guides, see the Hardware Acceleration documentation.
Where to start
| Goal | Start here |
|---|---|
| Get it running | Installation |
| Docker setup | Docker |
| Get your GPU working | Hardware |
| Using Jellyfin | Alchemist for Jellyfin |
| Comparing to Tdarr or FileFlows | Alchemist vs Tdarr · Alchemist vs FileFlows |
| Why it’s AGPLv3 | Open Source |
| Automate with tokens | API |
| Connect local assistants | MCP Server |
| Understand skip decisions | Skip Decisions |
| Tune per-library behavior | Profiles |
Nightly builds
docker pull ghcr.io/bybrooklyn/alchemist:nightlyPublished on every push to master that passes Rust checks.
Version format: 0.3.0-dev.3-nightly+abc1234.
Stable: ghcr.io/bybrooklyn/alchemist:latest
License
AGPLv3. Free to use, modify, and distribute under the same license. Genuinely open source — not source-available.