raagdosa 10.0.0

Deterministic music library cleanup for DJs and collectors — CLI-first, safe-by-default, undoable.

██████╗  █████╗  █████╗  ██████╗ ██████╗  ██████╗ ███████╗ █████╗
██╔══██╗██╔══██╗██╔══██╗██╔════╝ ██╔══██╗██╔═══██╗██╔════╝██╔══██╗
██████╔╝███████║███████║██║  ███╗██║  ██║██║   ██║███████╗███████║
██╔══██╗██╔══██║██╔══██║██║   ██║██║  ██║██║   ██║╚════██║██╔══██║
██║  ██║██║  ██║██║  ██║╚██████╔╝██████╔╝╚██████╔╝███████║██║  ██║
╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝  ╚═════╝ ╚══════╝╚═╝  ╚═╝

A tag-aware folder organiser for DJs and music collectors.

---

You have a downloads folder. Or three. Files named dj_shadow--endtroducing-WEB-1996-FTD, folders with no tags, folders where every track has a different artist. RaagDosa reads the tags inside each file, groups them into albums, scores how well-tagged each one is, and sorts them into Clean/ or Review/ — without touching your originals.

raagdosa go --dry-run          # see exactly what would happen
raagdosa go                    # do it
raagdosa undo --session last   # change your mind

Every run is logged and fully undoable. Your source folder is never modified.

Beta. This tool moves files. Run --dry-run first. Point it at a test folder before your real library.

---

Install

pip install raagdosa

Requires: Python 3.9+ · macOS, Linux, or Windows (including NTFS drives)

Or run from source:

git clone https://github.com/raagdosa/raagdosa
cd raagdosa
pip install -e .

---

Quick start

raagdosa init              # guided setup (one-time wizard)
raagdosa go --dry-run      # preview — nothing moves
raagdosa go                # do it
raagdosa undo --session last   # change your mind

New to RaagDosa? Start with the User Guide.

---

How it works

SCAN → READ TAGS → VOTE → SCORE → ROUTE → MOVE

It reads every audio tag in every file — artist, album, year, genre, BPM, key, label — and runs a plurality vote across all tracks in the folder to find consensus metadata. A 7-factor confidence score (0.0–1.0) determines the route: above threshold goes to Clean/, below goes to Review/.

Review/ is a holding area, not a bin. Fix the tags, re-run, and those folders promote to Clean/.

---

What RaagDosa does not do

• Does not modify audio tags during folder organising — tags are read-only input for the move pipeline. The separate tag fix workflow can write tag corrections, but only when you explicitly review and approve each change.
• Does not transcode or convert files
• Does not connect to Discogs, MusicBrainz, or any external service
• Does not delete anything, ever
• Does not touch your source folder

---

Privacy

RaagDosa runs entirely on your machine. It does not phone home, collect telemetry, upload usage data, or connect to any external service. Your music library stays yours — no accounts, no analytics, no cloud. Just your files, your tags, your folders.

---

Safety

Every file move is logged to logs/history.jsonl. Undo is always available by session, action ID, or path. Same-filesystem moves use atomic os.rename() — if it fails, there is no partial state. Cross-filesystem moves copy, verify, then delete.

---

Documentation

Guide	What it covers
User Guide	Setup, triage, interactive review, DJ crates, profiles, templates, scoring, config, sessions, undo, tag fixing
Commands Reference	Every command and flag
Changelog	Release history

---

Project links

• Issues: GitHub Issues
• License: MIT

---

Made with strong opinions about folder structure.

If RaagDosa is saving you time, let me know — or buy me a coffee so I know it's resonating.