Sortero: a DJ collection organiser for macOS

Consolidates a scattered DJ library into one canonical copy per track while
preserving curation as playlists rather than duplicated files.

- Organise: files tracks to Tracks/<Genre>/Artist - Title, collapses duplicate
  copies into one file, and rewrites every existing folder as an .m3u8 that
  points at the survivor, so vibe folders imported from Spotify/Tidal and gig
  sets keep their curation without duplicating audio.
- Tags: strips download-site spam from Genre/Comment, infers missing
  Artist/Title from filenames, normalises Genre, and promotes Mixed In Key
  energy out of the comment field into the sortable Grouping field.
- Duplicates: exact (content-hashed) and likely (artist/title/version plus
  duration) matching that never groups distinct remixes together.
- Import: routes analysed tracks to Tracks/<Genre> and unanalysed ones to
  'To Be Processed'; a dedicated action files the 'Processed' folder.
- History: every operation is journalled and reversible.

'To Be Processed' and 'Processed' are never reorganised. Nothing is deleted -
extra copies move to _Quarantine.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: sparkly-quasar

.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+build/dist/
+build/work/
+build/Sortero.iconset/
+build/Sortero.spec
+.DS_Store

README.md

@@ -0,0 +1,82 @@
+# Sortero
+
+A macOS app for getting a DJ collection under control: one canonical copy of
+every track, playlists that preserve your curation, clean tags, and an intake
+lane for new music.
+
+![tabs: Overview, Organise, Tags, Duplicates, Import, History](build/icon_1024.png)
+
+## The idea
+
+The consensus among working DJs is that the *filesystem* should be shallow and
+predictable, and the *software* should do the organising — crates and playlists
+reference a track, they don't copy it. Sortero applies that:
+
+- **One file per track**, at `Tracks/<Genre>/Artist - Title.ext`
+- **Playlists as pointers.** Every folder you have today — Spotify/Tidal vibe
+  imports, gig sets — becomes an `.m3u8` in `_Playlists/` pointing at that one
+  file. A track curated into five vibes is five playlist entries and one file.
+- **Key, BPM and energy live in tags**, where rekordbox and Mixxx can sort them.
+- **Nothing is deleted.** Extra copies go to `_Quarantine/`. Every operation is
+  journalled and reversible from the History tab.
+
+## Layout it produces
+
+```
+DJ Collection/
+  Tracks/<Genre>/Artist - Title.ext    canonical home for every track
+  Sets/<Set Name>/                     optional: gig folders kept as folders
+  Albums/<Album>/                      full releases, left intact
+  Mixes/                               recordings over 20 minutes
+  _Playlists/*.m3u8                    every folder you had, as a playlist
+  _Quarantine/                         duplicates and rejects, never deleted
+  To Be Processed/                     your Platinum Notes / Mixed In Key stage
+  Processed/                           analysed and ready to file
+```
+
+`To Be Processed` and `Processed` are never reorganised.
+
+## Tabs
+
+| Tab | What it does |
+|---|---|
+| **Overview** | Track count, size, and what share has key+BPM, genre and energy. Lists what needs attention. |
+| **Organise** | Previews every move before anything happens. Collapses duplicates, writes playlists, files tracks by genre. |
+| **Tags** | Strips download-site spam from Genre/Comment, infers missing Artist/Title from filenames, normalises Genre, and promotes Mixed In Key energy into the sortable Grouping field. |
+| **Duplicates** | Exact (identical audio) and Likely (same artist/title/version, same length). Different remixes are never grouped. Extras move to `_Quarantine`. |
+| **Import** | Add files or folders. Analysed tracks go straight to `Tracks/<Genre>`; anything missing key/BPM lands in `To Be Processed`. Tracks already in the library are flagged, not copied. **"Sort the 'Processed' folder"** files everything you've already run through PN and MIK. |
+| **History** | Every operation, with one-click undo. |
+
+## Why energy ends up in Grouping
+
+Mixed In Key writes `Cm - Energy 6` into the **comment** field. The key half
+usually also reaches `TKEY`, but the energy half is stranded somewhere no DJ
+software can sort on. Sortero copies it to **Grouping** as `5A - Energy 6`
+(Camelot + energy), which rekordbox and Mixxx expose as a sortable column.
+
+## Running it
+
+Build the app, then open `Sortero.app` and point it at your collection.
+
+### Building from source
+
+```bash
+python3.12 -m venv .venv
+./.venv/bin/pip install -U pip mutagen pyinstaller
+./build/build_app.sh          # -> build/dist/Sortero.app
+```
+
+Requires Python 3.12 with Tk (`brew install python-tk@3.12`).
+
+### Running without building
+
+```bash
+./.venv/bin/python run.py
+```
+
+## Safety
+
+- Dry-run previews on every destructive tab; nothing moves until you confirm.
+- Journals in `~/Library/Application Support/Sortero/journals/`.
+- Duplicate removal is quarantine-only — Sortero never calls `unlink` on your music.
+- Back up before the first big reorganisation anyway.

build/Sortero.icns

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Build Sortero.app. Run from the repo root:  ./build/build_app.sh
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+VENV=./.venv
+[ -d "$VENV" ] || { echo "no venv - see README"; exit 1; }
+
+echo "==> regenerating icon"
+"$VENV/bin/python" build/gen_icon.py
+
+echo "==> building app bundle"
+rm -rf build/dist build/work dist/Sortero.app
+# --specpath makes relative paths resolve against it, so pass the icon absolute
+ICON="$(cd build && pwd)/Sortero.icns"
+"$VENV/bin/pyinstaller" \
+  --noconfirm --clean --windowed \
+  --name Sortero \
+  --icon "$ICON" \
+  --osx-bundle-identifier com.sortero.app \
+  --distpath build/dist \
+  --workpath build/work \
+  --specpath build \
+  --hidden-import mutagen \
+  --collect-submodules mutagen \
+  run.py
+
+APP="build/dist/Sortero.app"
+[ -d "$APP" ] || { echo "build failed"; exit 1; }
+
+# Ad-hoc sign so macOS will run it locally without a Gatekeeper prompt loop.
+codesign --force --deep --sign - "$APP" 2>/dev/null || echo "(codesign skipped)"
+
+echo "==> built $APP"
+du -sh "$APP"

build/build_app.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Generate Sortero.icns with no third-party imaging dependencies.
+
+Draws a rounded-square tile with three sorted bars (short -> long), which reads
+as both 'sort' and 'levels'. Writes a PNG by hand, then hands off to sips and
+iconutil to produce the .icns.
+"""
+import math, os, struct, subprocess, sys, zlib
+
+S = 1024
+BG_TOP = (28, 30, 38)
+BG_BOT = (16, 17, 22)
+BARS = [
+    (0.30, 0.42, (255, 92, 122)),    # y-centre, width fraction, colour
+    (0.50, 0.62, (255, 176, 74)),
+    (0.70, 0.80, (86, 214, 178)),
+]
+CORNER = 0.22 * S
+BAR_H = 0.105 * S
+BAR_X = 0.13 * S
+
+
+def rounded_alpha(x, y, w, h, r):
+    """Coverage 0..1 of a rounded rect, sampled 2x2 for smooth edges."""
+    acc = 0.0
+    for dx in (0.25, 0.75):
+        for dy in (0.25, 0.75):
+            px, py = x + dx, y + dy
+            cx = min(max(px, r), w - r)
+            cy = min(max(py, r), h - r)
+            d = math.hypot(px - cx, py - cy)
+            if px < 0 or py < 0 or px > w or py > h:
+                continue
+            acc += 1.0 if d <= r else max(0.0, 1.0 - (d - r))
+    return acc / 4.0
+
+
+def blend(dst, src, a):
+    return tuple(int(round(d + (s - d) * a)) for d, s in zip(dst, src))
+
+
+def render():
+    rows = []
+    for y in range(S):
+        t = y / (S - 1)
+        bg = tuple(int(round(a + (b - a) * t)) for a, b in zip(BG_TOP, BG_BOT))
+        row = bytearray()
+        row.append(0)                                   # PNG filter: none
+        for x in range(S):
+            a = rounded_alpha(x, y, S, S, CORNER)
+            if a <= 0:
+                row += bytes((0, 0, 0, 0))
+                continue
+            px = bg
+            for cy_frac, w_frac, colour in BARS:
+                cy = cy_frac * S
+                if abs(y - cy) <= BAR_H / 2:
+                    bx0, bx1 = BAR_X, BAR_X + w_frac * (S - 2 * BAR_X)
+                    br = BAR_H / 2
+                    ba = rounded_alpha(x - bx0, y - (cy - BAR_H / 2),
+                                       bx1 - bx0, BAR_H, br)
+                    if ba > 0:
+                        px = blend(px, colour, ba)
+            row += bytes(px) + bytes((int(round(a * 255)),))
+        rows.append(bytes(row))
+    return b"".join(rows)
+
+
+def chunk(tag, data):
+    return (struct.pack(">I", len(data)) + tag + data
+            + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF))
+
+
+def write_png(path, raw):
+    ihdr = struct.pack(">IIBBBBB", S, S, 8, 6, 0, 0, 0)   # 8-bit RGBA
+    with open(path, "wb") as fh:
+        fh.write(b"\x89PNG\r\n\x1a\n")
+        fh.write(chunk(b"IHDR", ihdr))
+        fh.write(chunk(b"IDAT", zlib.compress(raw, 9)))
+        fh.write(chunk(b"IEND", b""))
+
+
+def main():
+    out = os.path.dirname(os.path.abspath(__file__))
+    master = os.path.join(out, "icon_1024.png")
+    print("rendering…")
+    write_png(master, render())
+
+    iconset = os.path.join(out, "Sortero.iconset")
+    os.makedirs(iconset, exist_ok=True)
+    for size in (16, 32, 64, 128, 256, 512, 1024):
+        for scale, suffix in ((1, ""), (2, "@2x")):
+            px = size * scale
+            if px > 1024:
+                continue
+            name = f"icon_{size}x{size}{suffix}.png"
+            subprocess.run(["sips", "-z", str(px), str(px), master,
+                            "--out", os.path.join(iconset, name)],
+                           check=True, capture_output=True)
+    icns = os.path.join(out, "Sortero.icns")
+    subprocess.run(["iconutil", "-c", "icns", iconset, "-o", icns], check=True)
+    print("wrote", icns)
+
+
+if __name__ == "__main__":
+    main()

build/gen_icon.py

@@ -0,0 +1,6 @@
+#!/usr/bin/env python3
+"""Dev entry point: python run.py"""
+from sortero.app import main
+
+if __name__ == "__main__":
+    main()

build/icon_1024.png

@@ -0,0 +1,4 @@
+from .app import main
+
+if __name__ == "__main__":
+    main()