Metadata-Version: 2.4
Name: tunedex
Version: 0.1.0
Summary: Free, local-first, scriptable DJ library manager.
Author: VonMartins
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Dist: mutagen>=1.48.1
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=15.0.0
Requires-Dist: send2trash>=1.8.3
Requires-Dist: typer>=0.27.3
Requires-Python: >=3.11
Project-URL: Documentation, https://vonmartins.github.io/tunedex/
Project-URL: Repository, https://github.com/vonmartins/tunedex
Project-URL: Changelog, https://github.com/vonmartins/tunedex/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/vonmartins/tunedex/issues
Description-Content-Type: text/markdown

# tunedex

A free, local-first, scriptable DJ library manager.

**Documentation: [vonmartins.github.io/tunedex](https://vonmartins.github.io/tunedex/)**

Your music folder (and optionally your [beets](https://beets.io) 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

```sh
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

```sh
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](https://vonmartins.github.io/tunedex/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](https://vonmartins.github.io/tunedex/guides/from-another-program/).

## Development

Requires [uv](https://docs.astral.sh/uv/).

```sh
uv sync
uv run tunedex --help
uv run pytest
```

See [CONTRIBUTING.md](https://github.com/vonmartins/tunedex/blob/main/CONTRIBUTING.md) for the checks, the conventions and how to
preview the documentation.

## License

[GPL-3.0-or-later](https://github.com/vonmartins/tunedex/blob/main/LICENSE).
