{"id":37321255,"url":"https://github.com/bybrooklyn/alchemist","last_synced_at":"2026-06-06T22:00:55.383Z","repository":{"id":331758440,"uuid":"1129078842","full_name":"bybrooklyn/alchemist","owner":"bybrooklyn","description":"Alchemist is a Rust-based video transcoding system that automatically converts your media library to efficient AV1/HEVC format using hardware acceleration (GPU) or software encoding (CPU fallback).","archived":false,"fork":false,"pushed_at":"2026-04-04T18:30:36.000Z","size":96650,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-04T20:30:15.931Z","etag":null,"topics":["astro","automation","bun","ffmpeg-wrapper","rust","tailwindcss","transcoding"],"latest_commit_sha":null,"homepage":"https://alchemist-project.org","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bybrooklyn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-06T15:18:56.000Z","updated_at":"2026-04-04T18:29:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bybrooklyn/alchemist","commit_stats":null,"previous_names":["brooklynloveszelda/alchemist","bybrooklyn/alchemist"],"tags_count":43,"template":false,"template_full_name":null,"purl":"pkg:github/bybrooklyn/alchemist","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bybrooklyn%2Falchemist","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bybrooklyn%2Falchemist/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bybrooklyn%2Falchemist/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bybrooklyn%2Falchemist/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bybrooklyn","download_url":"https://codeload.github.com/bybrooklyn/alchemist/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bybrooklyn%2Falchemist/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31539229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astro","automation","bun","ffmpeg-wrapper","rust","tailwindcss","transcoding"],"created_at":"2026-01-16T03:18:56.634Z","updated_at":"2026-06-06T22:00:55.372Z","avatar_url":"https://github.com/bybrooklyn.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Alchemist\n\nPoint it at your media library. Walk away. Come back to a smaller, better-encoded collection.\n\nAlchemist saves space automatically without asking you to babysit shell commands or risk your originals. It is GPLv3 open source, self-hosted, and ships as one application with a web UI for setup, monitoring, and day-to-day control. No paid tier, no private \"pro\" feature tree, no license key.\n\n## Why Alchemist?\n\nRunning `ffmpeg` by hand works when you only have a few files and a lot of patience. Flow tools like Tdarr can scale and branch, but they also ask you to run more moving parts and model media policy as a graph. Alchemist is built for the self-hoster who wants the boring path: one process, deterministic planning, plain explanations, automatic hardware selection, and public GPLv3 code for every feature it ships.\n\n## What It Does\n\nAlchemist scans your library, inspects each file, and decides whether transcoding would actually help. If a file is already efficient, it skips it and tells you why in plain English instead of leaving you to guess.\n\nIf supported hardware is available, Alchemist uses it automatically. NVIDIA, Intel, AMD, and Apple Silicon are all detected and used without manual setup, and if there is no GPU available it falls back to CPU encoding on its own.\n\nYour originals stay safe. Alchemist never overwrites anything until the new file passes its quality checks. You can keep both files or let Alchemist replace the original, but nothing is lost until you decide that is what you want.\n\nEverything is visible in the web dashboard. You can see what is running, what was skipped, how much space you have recovered, and pause or cancel work whenever you want.\n\n## Features\n\n- Give movies, TV, and home videos different behavior with per-library profiles.\n- Convert or remux a single uploaded file from the **Convert** page using the same pipeline Alchemist uses for library jobs.\n- Catch corrupt or broken files before they surprise you with Library Doctor.\n- See exactly how much storage you have recovered in the savings dashboard.\n- Understand every skipped file immediately with plain-English explanations.\n- Get a ping when work finishes through Discord, Gotify, ntfy, Telegram, email, or a webhook, with quiet hours for non-critical events.\n- Create named API tokens for automation, with `read_only`, `arr_webhook`, `jellyfin`, and `full_access` access classes.\n- Accept Sonarr/Radarr download webhooks through a narrowed `arr_webhook` token and optional container path translations.\n- Connect Jellyfin with a narrowed plugin token for enqueue, completion events, job details, and library refresh.\n- Expose read-only operational context to local assistants through the MCP server.\n- Keep heavy jobs out of the way with a scheduler for off-peak hours.\n- Push urgent files to the front with the priority queue.\n- Switch the engine between background, balanced, and throughput modes without restarting the app.\n- Let hardware acceleration happen automatically on NVIDIA, Intel, AMD, or Apple, with CPU fallback when needed and cached detection on repeat boots.\n- Preserve HDR metadata or tonemap to SDR depending on what you need.\n- Add folders once and let watch folders keep monitoring them automatically.\n- Shape audio output with stream rules for commentary stripping, language filtering, and default-track retention.\n- Surface storage-focused recommendations through Library Intelligence, including remux opportunities and commentary cleanup candidates.\n\n## Hardware Support\n\nAlchemist uses hardware acceleration when it can and falls back to CPU encoding automatically when it cannot. You do not need different workflows for different machines.\n\n| Vendor | Encoders                                 |\n|--------|------------------------------------------|\n| NVIDIA | AV1, HEVC, H.264 (NVENC)                 |\n| Intel  | AV1, HEVC, H.264 (QSV)                   |\n| AMD    | HEVC, H.264 (VAAPI/AMF)                  |\n| Apple  | HEVC, H.264 (VideoToolbox)               |\n| CPU    | AV1 (SVT-AV1), HEVC (x265), H.264 (x264) |\n\nCPU fallback is automatic when no GPU is available.\n\n## Quick Start\n\n### Docker (Recommended)\n\nIf you want the fastest path to a running instance, use the published container:\n\n```yaml\nservices:\n  alchemist:\n    image: ghcr.io/bybrooklyn/alchemist:latest\n    container_name: alchemist\n    ports:\n      - \"3000:3000\"\n    volumes:\n      - ~/.config/alchemist:/app/config\n      - ~/.config/alchemist:/app/data\n      - /path/to/media:/media\n    environment:\n      - ALCHEMIST_CONFIG_PATH=/app/config/config.toml\n      - ALCHEMIST_DB_PATH=/app/data/alchemist.db\n    restart: unless-stopped\n```\n\nThen open [http://localhost:3000](http://localhost:3000) in your browser.\nFirst-time setup is only reachable from the local network.\n\nOn Linux and macOS, the default host-side config location is\n`~/.config/alchemist/config.toml`. When you use Docker, the\nrecommended bind mount is still `~/.config/alchemist`, mapped\ninto `/app/config` and `/app/data` inside the container.\n\nIf you prefer `docker run`, this is the trimmed equivalent:\n\n```bash\ndocker run -d --name alchemist -p 3000:3000 -v ~/.config/alchemist:/app/config -v ~/.config/alchemist:/app/data -v /path/to/media:/media -e ALCHEMIST_CONFIG_PATH=/app/config/config.toml -e ALCHEMIST_DB_PATH=/app/data/alchemist.db --restart unless-stopped ghcr.io/bybrooklyn/alchemist:latest\n```\n\n### Binary\n\nDownload the latest release from [GitHub Releases](https://github.com/bybrooklyn/alchemist/releases). Prebuilt binaries are published for Linux x86_64, Linux ARM64, Windows x86_64, macOS Intel, and macOS Apple Silicon.\n\nFFmpeg must be installed separately for binary installs:\n\n```bash\nsudo apt install ffmpeg\nsudo dnf install ffmpeg\nsudo pacman -S ffmpeg\nbrew install ffmpeg\nwinget install Gyan.FFmpeg\n```\n\nStart Alchemist, then open [http://localhost:3000](http://localhost:3000):\n\n```bash\n./alchemist\n```\n\nIf port 3000 is already busy, native runs automatically use the next available\nport and print an `INFO` line with the exact\n`http://127.0.0.1:\u003cport\u003e` link. Set `ALCHEMIST_SERVER_PORT=3000` to require a\nspecific port.\n\nOn Windows, run `alchemist.exe` instead.\n\nDirect Linux/macOS binary installs can check for signed updates from the\nAbout dialog. Alchemist verifies the release manifest and asset checksum,\nbacks up the database, drains active jobs, then restarts to apply eligible\ndirect-binary updates. Docker, Homebrew, AUR, Windows, and source installs\nshow the appropriate package-manager or manual update guidance instead.\n\n### From Source\n\nFor macOS and Linux:\n\n```bash\ngit clone https://github.com/bybrooklyn/alchemist.git\ncd alchemist\njust install\njust build\n./target/release/alchemist\n```\n\nAlchemist requires Rust 1.85 or later (MSRV). Use `rustup update stable` to ensure you are on a recent toolchain, and make sure FFmpeg is installed separately.\n\nFor Windows local development:\n\n```bash\njust install-w\njust dev\njust check\n```\n\nThe core contributor path is supported on Windows. Broader release and utility recipes remain Unix-first.\n\n## CLI\n\nAlchemist exposes explicit CLI subcommands:\n\n```bash\nalchemist scan /path/to/media\nalchemist run /path/to/media\nalchemist plan /path/to/media\nalchemist plan /path/to/media --json\n```\n\n- `scan` enqueues matching work and exits\n- `run` scans, enqueues, and waits for processing to finish\n- `plan` analyzes files and reports what Alchemist would do without enqueuing jobs\n\n## First Run\n\n1. Open [http://localhost:3000](http://localhost:3000).\n2. Complete the setup wizard. It takes about 2 minutes.\n   During first-time setup, the web UI is reachable only from the local network.\n3. Add your media folders in Watch Folders.\n4. Alchemist runs the initial scan and queues matching work automatically.\n5. Click **Start** in the header when you are ready for the engine to process queued work.\n6. Check the Dashboard to see progress and savings.\n\n## Automation + Subpath Notes\n\n- API automation can use bearer tokens created in **Settings → API Tokens**.\n- Read-only tokens are limited to observability and monitoring routes.\n- ARR webhooks should use the dedicated `arr_webhook` token class, not a full-access token.\n- Jellyfin plugins should use the dedicated `jellyfin` token class, not a full-access token.\n- MCP clients can launch `alchemist --mcp` for read-only engine, job, scan, savings, and system-health tools.\n\n## Open Source\n\nAlchemist is GPLv3. The public repository is the product:\nthere is no commercial unlock, no separate enterprise build,\nno license-key gate, and telemetry is opt-in/off by default.\nSee [Open Source](docs/docs/open-source.md) for the details.\n\n## Backups\n\nAlchemist stores all state in a single SQLite database. You can download a\nconsistent, gzip-compressed snapshot at any time:\n\n- UI: **Settings → Runtime → Backup database**\n- API: `POST /api/system/backup` (requires a full-access token)\n\nThe snapshot is produced via SQLite's online backup path, so it is safe to run\nwhile encodes are in flight.\n\n## Supported Platforms\n\n| Platform | Status |\n|----------|--------|\n| Linux x86_64 | ✅ Supported |\n| Linux ARM64 | ✅ Supported |\n| Windows x86_64 | ✅ Supported |\n| macOS Apple Silicon | ✅ Supported |\n| macOS Intel | ✅ Supported |\n| Docker linux/amd64 | ✅ Supported |\n| Docker linux/arm64 | ✅ Supported |\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/?repos=bybrooklyn%2Falchemist\u0026type=date\u0026legend=top-left\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=bybrooklyn/alchemist\u0026type=date\u0026theme=dark\u0026legend=top-left\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=bybrooklyn/alchemist\u0026type=date\u0026legend=top-left\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=bybrooklyn/alchemist\u0026type=date\u0026legend=top-left\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n## License\n\nLicensed under GPLv3. See [LICENSE](LICENSE) for details.\n\n## Contributing\n\nStart with [CONTRIBUTING.md](CONTRIBUTING.md) for contribution terms,\n[docs/docs/contributing/development.md](docs/docs/contributing/development.md)\nfor local setup, and [RELEASING.md](RELEASING.md) for the release process.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbybrooklyn%2Falchemist","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbybrooklyn%2Falchemist","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbybrooklyn%2Falchemist/lists"}