Cross-platform support, streaming playlists, and OAuth

Playlists tab: build an .m3u8 from a Spotify or TIDAL playlist link by
matching each track against files already in the collection. Falls back to
pasted 'Artist - Title' lines or a CSV export, which always work. Import tab
gains an "add to playlist" picker, plus a button to rebuild folder playlists.

OAuth 2.0 Authorization Code + PKCE for TIDAL and Spotify. Sign-in happens on
the provider's own site, so no password ever reaches Sortero; tokens go to the
OS credential store. Connecting also lifts Spotify's 50-track embed cap.

Cross-platform: platform-appropriate config/data directories, an OS-agnostic
credential store with a 0600 file fallback, a portable "reveal in file
manager", and pure-Python .ico generation so Windows icons need no macOS
tooling. build_app.py replaces the shell script and builds on all three
platforms; --universal2 checks the interpreter is actually universal before
invoking PyInstaller.

CI builds macOS (universal2), Windows and Linux on a tag and attaches them to
a GitHub release.

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

Author: sparkly-quasar

.github/workflows/release.yml

@@ -0,0 +1,87 @@
+name: Build and release
+
+# Push a tag like v0.1.0 to build all three platforms and attach them to a
+# GitHub release. Also runnable by hand from the Actions tab.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to build and release (e.g. v0.1.0)"
+        required: true
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-14
+            name: macOS-universal2
+            args: "--universal2"
+          - os: windows-latest
+            name: windows-x86_64
+            args: ""
+          - os: ubuntu-22.04
+            name: linux-x86_64
+            args: ""
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      # setup-python ships the python.org macOS build, which is universal2 -
+      # that is what makes the universal Mac app possible.
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Tk (Linux)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y python3-tk
+
+      - name: Create venv and install deps
+        shell: bash
+        run: |
+          python -m venv .venv
+          if [ "$RUNNER_OS" = "Windows" ]; then PY=.venv/Scripts/python.exe; else PY=.venv/bin/python; fi
+          $PY -m pip install -q --upgrade pip
+          $PY -m pip install -q mutagen keyring pyinstaller
+
+      - name: Build
+        shell: bash
+        run: |
+          if [ "$RUNNER_OS" = "Windows" ]; then PY=.venv/Scripts/python.exe; else PY=.venv/bin/python; fi
+          $PY build/build_app.py ${{ matrix.args }}
+
+      - name: Verify macOS binary is universal
+        if: runner.os == 'macOS'
+        run: |
+          BIN=build/dist/Sortero.app/Contents/MacOS/Sortero
+          lipo -archs "$BIN"
+          lipo -archs "$BIN" | grep -q x86_64 && lipo -archs "$BIN" | grep -q arm64 \
+            || { echo "not universal"; exit 1; }
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: Sortero-${{ matrix.name }}
+          path: build/dist/*.zip
+          if-no-files-found: error
+
+  release:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+      - name: Publish release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.event.inputs.tag || github.ref_name }}
+          name: Sortero ${{ github.event.inputs.tag || github.ref_name }}
+          generate_release_notes: true
+          files: artifacts/**/*.zip

README.md

@@ -47,6 +47,23 @@ DJ Collection/
 | **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. |
 
+## Streaming playlists
+
+Paste a Spotify or TIDAL playlist link on the **Playlists** tab and Sortero
+matches each track against files you already own, then writes an `.m3u8`.
+
+Connect an account (Playlists → Accounts) to read playlists of any length. It
+uses OAuth 2.0 with PKCE: you sign in on Spotify's or TIDAL's own website, so
+Sortero never sees your password, and the tokens are stored in your OS
+credential store. One-time setup is creating a free app at
+[developer.tidal.com](https://developer.tidal.com) or the
+[Spotify dashboard](https://developer.spotify.com/dashboard) and adding
+`http://127.0.0.1:8899/callback` as a redirect URI.
+
+Without connecting, Spotify links fall back to a public preview capped at 50
+tracks, and TIDAL links need a connection. Pasting a tracklist as
+`Artist - Title` lines, or loading a CSV export, always works.
+
 ## Why energy ends up in Grouping
 
 Mixed In Key writes `Cm - Energy 6` into the **comment** field. The key half
@@ -58,15 +75,39 @@ software can sort on. Sortero copies it to **Grouping** as `5A - Energy 6`
 
 Build the app, then open `Sortero.app` and point it at your collection.
 
+Sortero runs on **macOS, Windows and Linux**. Grab the build for your platform
+from the [Releases page](../../releases):
+
+| Platform | Artifact |
+|---|---|
+| macOS (Intel + Apple Silicon) | `Sortero-macOS-universal2.zip` |
+| Windows | `Sortero-windows-x86_64.zip` |
+| Linux | `Sortero-linux-x86_64.zip` |
+
+macOS builds are ad-hoc signed, not notarised, so the first launch needs
+right-click → Open.
+
 ### 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
+./.venv/bin/pip install -U pip mutagen keyring pyinstaller
+./.venv/bin/python build/build_app.py
+```
+
+Requires Python 3.12 with Tk — `brew install python-tk@3.12` on macOS,
+`apt install python3-tk` on Debian/Ubuntu; the Windows installer includes it.
+
+A **universal2** macOS build needs a universal2 Python (the python.org
+installer ships one; Homebrew's is single-architecture):
+
+```bash
+./.venv/bin/python build/build_app.py --universal2
 ```
 
-Requires Python 3.12 with Tk (`brew install python-tk@3.12`).
+The script checks the interpreter first and tells you if it can't. Release
+builds run in GitHub Actions, where `setup-python` provides a universal2
+interpreter — see `.github/workflows/release.yml`.
 
 ### Running without building
 
@@ -77,6 +118,7 @@ Requires Python 3.12 with Tk (`brew install python-tk@3.12`).
 ## Safety
 
 - Dry-run previews on every destructive tab; nothing moves until you confirm.
-- Journals in `~/Library/Application Support/Sortero/journals/`.
+- Journals live alongside your other app data: `~/Library/Application Support/Sortero`
+  on macOS, `%APPDATA%\\Sortero` on Windows, `$XDG_DATA_HOME/sortero` on Linux.
 - 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,111 @@
+#!/usr/bin/env python3
+"""Build the Sortero desktop app for the platform you run this on.
+
+    python build/build_app.py [--universal2]
+
+macOS   -> build/dist/Sortero.app   (+ a .zip you can hand to someone else)
+Windows -> build/dist/Sortero/Sortero.exe
+Linux   -> build/dist/Sortero/Sortero
+
+--universal2 (macOS) builds an Intel + Apple Silicon binary. It requires a
+universal2 Python - the python.org installer ships one; Homebrew's does not.
+The script checks first and tells you rather than failing deep inside
+PyInstaller.
+"""
+import argparse, os, shutil, subprocess, sys, zipfile
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+BUILD = os.path.join(ROOT, "build")
+DIST = os.path.join(BUILD, "dist")
+WORK = os.path.join(BUILD, "work")
+IS_MAC, IS_WIN = sys.platform == "darwin", os.name == "nt"
+
+
+def venv_python():
+    for cand in (os.path.join(ROOT, ".venv", "Scripts", "python.exe"),
+                 os.path.join(ROOT, ".venv", "bin", "python")):
+        if os.path.exists(cand):
+            return cand
+    return sys.executable
+
+
+def mac_arches(py):
+    try:
+        out = subprocess.run(["lipo", "-archs", os.path.realpath(py)],
+                             capture_output=True, text=True).stdout
+        return out.split()
+    except Exception:
+        return []
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--universal2", action="store_true",
+                    help="macOS: build a universal (Intel + Apple Silicon) binary")
+    args = ap.parse_args()
+
+    py = venv_python()
+    print(f"==> python: {py}")
+
+    print("==> generating icons")
+    subprocess.run([py, os.path.join(BUILD, "gen_icon.py")], check=True)
+
+    icon = None
+    if IS_MAC:
+        icon = os.path.join(BUILD, "Sortero.icns")
+    elif IS_WIN:
+        icon = os.path.join(BUILD, "Sortero.ico")
+
+    for d in (DIST, WORK):
+        shutil.rmtree(d, ignore_errors=True)
+
+    cmd = [py, "-m", "PyInstaller", "--noconfirm", "--clean", "--windowed",
+           "--name", "Sortero",
+           "--distpath", DIST, "--workpath", WORK, "--specpath", BUILD,
+           "--hidden-import", "mutagen", "--collect-submodules", "mutagen",
+           "--hidden-import", "keyring", "--collect-submodules", "keyring"]
+    if icon and os.path.exists(icon):
+        cmd += ["--icon", icon]
+    if IS_MAC:
+        cmd += ["--osx-bundle-identifier", "com.sortero.app"]
+        if args.universal2:
+            arches = mac_arches(py)
+            if "x86_64" not in arches or "arm64" not in arches:
+                sys.exit(
+                    f"\nCannot build universal2: this Python is {'/'.join(arches) or 'single-arch'}.\n"
+                    "PyInstaller can only produce a universal2 binary from a universal2 Python.\n"
+                    "Install one from https://www.python.org/downloads/macos/ (the installer is\n"
+                    "universal2), recreate the venv with it, then re-run with --universal2.\n")
+            cmd += ["--target-arch", "universal2"]
+    cmd.append(os.path.join(ROOT, "run.py"))
+
+    print("==> building")
+    subprocess.run(cmd, check=True, cwd=ROOT)
+
+    if IS_MAC:
+        app = os.path.join(DIST, "Sortero.app")
+        if not os.path.isdir(app):
+            sys.exit("build failed: no Sortero.app")
+        # Ad-hoc signature so Gatekeeper will run it locally.
+        subprocess.run(["codesign", "--force", "--deep", "--sign", "-", app],
+                       capture_output=True)
+        arch = "-".join(mac_arches(os.path.join(app, "Contents", "MacOS", "Sortero"))) or "unknown"
+        zip_path = os.path.join(DIST, f"Sortero-macOS-{arch}.zip")
+        print("==> zipping (ditto preserves the bundle)")
+        subprocess.run(["ditto", "-c", "-k", "--sequesterRsrc", "--keepParent",
+                        app, zip_path], check=True)
+        print(f"\nbuilt {app}\nzip:  {zip_path}  ({os.path.getsize(zip_path)/1e6:.1f} MB)")
+    else:
+        target = os.path.join(DIST, "Sortero")
+        plat = "windows" if IS_WIN else "linux"
+        zip_path = os.path.join(DIST, f"Sortero-{plat}-x86_64.zip")
+        with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as z:
+            for dirpath, _, files in os.walk(target):
+                for f in files:
+                    fp = os.path.join(dirpath, f)
+                    z.write(fp, os.path.relpath(fp, DIST))
+        print(f"\nbuilt {target}\nzip:  {zip_path}")
+
+
+if __name__ == "__main__":
+    main()