Skip to main content

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

GPL-3.0-or-later.

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)

Source distribution for tunedex 0.1.0
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)

Table of built distributions (wheels) for tunedex 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page