tunedex
A free, local-first, scriptable DJ library manager.
Documentation: vonmartins.github.io/tunedex
Your music folder (and optionally your beets library) is the source of truth. DJ apps such as Mixxx are targets you sync to safely: every write is planned first, shown as a diff, and backed by a snapshot you can restore.
Status: alpha. Try it with a scratch home and a test profile of your DJ app before you point it at the library you play from.
What it does
- Imports your music folder, Mixxx and beets, read only.
- Cleans tags with bundled fixes and your own rules in YAML.
- Recognizes tracks by their sound and takes their tags from MusicBrainz, when you ask it to.
- Finds and merges duplicates, keeping the best file and moving the others to the system trash.
- Writes the cleaned tags into your files, keeping cover art and the audio intact, and renames files from their tags.
- Exports playlists to Mixxx and M3U.
- Undoes any write: a snapshot is taken before each one.
Everything works from the command line, with JSON output and a Python API for other programs. No accounts, no telemetry, no cloud.
Install
uv tool install tunedex
or pipx install tunedex. Python 3.11 or later, on Linux, macOS and Windows. For the
development version, install git+https://github.com/vonmartins/tunedex@dev.
Quick start
export TUNEDEX_HOME=/tmp/tunedex-try # a scratch home, to try it safely
tunedex scan ~/Music # show what would be added; writes nothing
tunedex scan ~/Music --apply # apply it, after confirming
tunedex fix # show how the tags would be cleaned
tunedex list --where "bpm>=170"
Then follow the tutorial.
Building on tunedex
Every command takes --json and prints one documented JSON document; errors have
stable codes. Python programs can import tunedex. See
using tunedex from another program.
Development
Requires uv.
uv sync
uv run tunedex --help
uv run pytest
See CONTRIBUTING.md for the checks, the conventions and how to preview the documentation.
License
Metadata
Release files for tunedex 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tunedex-0.1.0.tar.gz | 171.4 kB | With provenance | Details for tunedex-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tunedex-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for tunedex-0.1.0-py3-none-any.whl |
Total release size: 392.0 kB
Release files / tunedex-0.1.0.tar.gz
| Download URL | tunedex-0.1.0.tar.gz |
|---|---|
| Size | 171.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5e486bef50311d2c2489f276307e584205e82f5ee2850e80066e970d196e913c
|
|
BLAKE2b-256 checksum How to use checksums |
5fc5492f91b6b29bf9575f012251bfb80c6f689ea4cc75ff25b71e8c28dc9dfd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / tunedex-0.1.0-py3-none-any.whl
| Download URL | tunedex-0.1.0-py3-none-any.whl |
|---|---|
| Size | 220.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
69dca34725acfb5e678b2b143699b44c96a67106ace3717caf5234729b801898
|
|
BLAKE2b-256 checksum How to use checksums |
20ebd1fec44f484a693da5cf0d841ca13c193c1c8497a2b2e34775b4a0616e6f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logSecurity for tunedex 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for tunedex-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.