fix: switch build_* a yt-dlp nightly channel (v1.11.2)

Fix strutturale ricorrente errore "yt-dlp exit 1" nel download.
YouTube rompe API ogni 1-2 settimane; yt-dlp stable esce ogni ~4
settimane, quindi la build imbarcava binari gia' obsoleti al rilascio.

- build_macos.py + build_windows.py: URL switch da
  yt-dlp/yt-dlp/releases/latest → yt-dlp/yt-dlp-nightly-builds
- Sempre re-download (niente skip se bundle_bin/yt-dlp esiste) —
  garantisce binario 24-48h, non 3-4 settimane

.gitignore

@@ -49,3 +49,12 @@ server/node_modules/
 server/.wrangler/
 server/.dev.vars
 server/dist/
+
+# Dedup local cache (SQLite fingerprint cache, per macchina dell'utente)
+dedup_cache.db
+dedup_cache.db-journal
+catalog_cache.db
+catalog_cache.db-journal
+
+# Log persistente (rotating file)
+logs/

api/bridge.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 import os
+import queue
 import re
 import threading
 import time
@@ -15,7 +16,7 @@ from typing import Any, Callable, Optional
 import requests
 
 from core.config import load_config, save_config, VERSION, LICENSE_API_URL
-from core import beatport, spotify_client
+from core import beatport, spotify_client, traxsource
 from core import license as license_mod
 from core.downloader import (
     download_playlist,
@@ -45,6 +46,9 @@ from core.upgrader import (
     request_stop as request_upgrade_stop,
     count_files_info,
 )
+from core import dedup
+from core import catalog
+from core import flatten
 
 
 SPOTIFY_GUIDE_TEXT = """\
@@ -110,6 +114,12 @@ class Api:
         self._download_thread: Optional[threading.Thread] = None
         self._upgrade_thread: Optional[threading.Thread] = None
         self._video_thread: Optional[threading.Thread] = None
+        self._dedup_thread: Optional[threading.Thread] = None
+        self._catalog_thread: Optional[threading.Thread] = None
+        self._flatten_thread: Optional[threading.Thread] = None
+        # Coda usata dal resolve_callback per attendere la scelta utente
+        # sul modal "match locali multipli" della tab Upgrade.
+        self._upgrade_resolve_q: "queue.Queue[dict]" = queue.Queue(1)
 
     # ------------------------------------------------------------------
     # Helpers
@@ -126,7 +136,40 @@ class Api:
             pass
 
     def _log(self, view: str, msg: str) -> None:
+        # Emit alla UI + mirror sul file di log persistente
         self._emit("log", {"view": view, "msg": msg})
+        try:
+            import logging
+            logging.getLogger(f"ui.{view}").info(msg)
+        except Exception:
+            pass
+
+    # ------------------------------------------------------------------
+    # Log persistente
+    # ------------------------------------------------------------------
+    def get_log_file_path(self) -> str:
+        """Ritorna il path del file di log corrente (per apertura da UI)."""
+        try:
+            from core.applog import log_file_path
+            return str(log_file_path())
+        except Exception:
+            return ""
+
+    def open_log_folder(self) -> dict:
+        """Apre la cartella dei log nel file manager del sistema."""
+        try:
+            from core.applog import log_file_path
+            import subprocess
+            folder = log_file_path().parent
+            if sys.platform == "darwin":
+                subprocess.Popen(["open", str(folder)])
+            elif sys.platform == "win32":
+                os.startfile(str(folder))  # type: ignore[attr-defined]
+            else:
+                subprocess.Popen(["xdg-open", str(folder)])
+            return {"ok": True, "path": str(folder)}
+        except Exception as e:
+            return {"ok": False, "error": str(e)}
 
     # ------------------------------------------------------------------
     # Bootstrap
@@ -164,6 +207,7 @@ class Api:
             "bitrate": payload.get("bitrate", "320K"),
             "hq_threshold": threshold,
             "cookies_path": (payload.get("cookies_path") or "").strip(),
+            "cookies_browser": (payload.get("cookies_browser") or "").strip().lower(),
             "output_dir": (payload.get("output_dir") or "").strip(),
             "theme": payload.get("theme", "dark"),
         })
@@ -882,6 +926,8 @@ class Api:
             return {"ok": False, "error": "Upgrade gia in corso"}
 
         directory = (payload.get("directory") or "").strip()
+        archive_dir = (payload.get("archive_dir") or "").strip() or None
+        archive_auto_pick = bool(payload.get("archive_auto_pick", False))
         recursive = bool(payload.get("recursive", False))
         try:
             threshold = int(payload.get("threshold", 310))
@@ -898,9 +944,16 @@ class Api:
         cfg = load_config()
         cookies_path = cfg.get("cookies_path", "")
 
+        # Drain la queue di risoluzione da eventuali run precedenti (safety)
+        try:
+            while True:
+                self._upgrade_resolve_q.get_nowait()
+        except queue.Empty:
+            pass
+
         self._upgrade_thread = threading.Thread(
             target=self._upgrade_worker,
-            args=(directory, threshold, cookies_path, recursive),
+            args=(directory, threshold, cookies_path, recursive, archive_dir, archive_auto_pick),
             daemon=True,
         )
         self._upgrade_thread.start()
@@ -908,10 +961,63 @@ class Api:
 
     def stop_upgrade(self) -> dict:
         request_upgrade_stop()
+        # Sblocca eventuale resolve_callback in attesa: inviamo scelta 'skip'
+        # cosi il worker esce pulito invece di restare bloccato in q.get().
+        try:
+            self._upgrade_resolve_q.put_nowait({"action": "skip"})
+        except queue.Full:
+            pass
         self._log("upgrade", "[INFO] Interruzione richiesta...")
         return {"ok": True}
 
-    def _upgrade_worker(self, directory, threshold, cookies_path, recursive):
+    def read_audio_data_url(self, path: str) -> dict:
+        """Legge un file audio locale e lo ritorna come data URL base64
+        per il preview HTML5 nel modal upgrade. WKWebView (macOS pywebview)
+        blocca `file://` da HTML servito via file://, quindi passiamo dal
+        bridge. Limite: 60MB per non esplodere la memoria JS."""
+        import base64 as _b64
+        MAX = 60 * 1024 * 1024
+        try:
+            p = Path(path or "")
+            if not p.exists() or not p.is_file():
+                return {"ok": False, "error": "File non trovato"}
+            size = p.stat().st_size
+            if size > MAX:
+                return {"ok": False, "error": f"File troppo grande ({size // 1024 // 1024}MB, max 60MB)"}
+            ext = p.suffix.lower().lstrip(".")
+            mime_map = {
+                "mp3": "audio/mpeg", "m4a": "audio/mp4", "aac": "audio/aac",
+                "wav": "audio/wav", "flac": "audio/flac", "ogg": "audio/ogg",
+                "opus": "audio/opus", "webm": "audio/webm",
+            }
+            mime = mime_map.get(ext, "audio/mpeg")
+            b64 = _b64.b64encode(p.read_bytes()).decode("ascii")
+            return {"ok": True, "data_url": f"data:{mime};base64,{b64}"}
+        except Exception as e:
+            return {"ok": False, "error": str(e)}
+
+    def upgrade_resolve_candidates(self, choice: dict) -> dict:
+        """Riceve la scelta utente dal modal 'match locali multipli' e la
+        deposita nella queue attesa dal resolve_callback del worker.
+
+        `choice`: {'action': 'use_local'|'use_youtube'|'skip', 'path': str?}
+        """
+        if not isinstance(choice, dict):
+            choice = {"action": "skip"}
+        try:
+            # Drain (nel caso rarissimo di doppio put) e poi metti la nuova
+            try:
+                self._upgrade_resolve_q.get_nowait()
+            except queue.Empty:
+                pass
+            self._upgrade_resolve_q.put_nowait(choice)
+            return {"ok": True}
+        except Exception as e:
+            return {"ok": False, "error": str(e)}
+
+    def _upgrade_worker(self, directory, threshold, cookies_path, recursive,
+                         archive_dir: Optional[str] = None,
+                         archive_auto_pick: bool = False):
         view = "upgrade"
 
         def progress_cb(idx, total, filename, status, old_kbps, new_kbps):
@@ -938,6 +1044,19 @@ class Api:
                 diff = new_kbps - old_kbps
                 diff_str = f" (+{diff}kbps)" if diff > 0 else ""
                 self._log(view, f"[UPGRADE] {filename}: {old_kbps} -> {new_kbps}kbps{diff_str}")
+            elif status == "local_copy":
+                self._log(view, f"[LOCALE] {filename}: uso match dall'archivio")
+            elif status == "local_upgraded":
+                diff = new_kbps - old_kbps
+                diff_str = f" (+{diff}kbps)" if diff > 0 else ""
+                self._log(view, f"[LOCALE OK] {filename}: {old_kbps} -> {new_kbps}kbps{diff_str}")
+            elif status == "skipped_by_user":
+                self._log(view, f"[SKIP] {filename} (saltato manualmente)")
+            elif status == "resolve_wait":
+                self._log(view, f"[SCELTA] {filename}: match multipli, in attesa scelta utente")
+            elif status == "scan_archive":
+                # `new_kbps` in questo caso trasporta il count delle chiavi
+                self._log(view, f"[ARCHIVIO] Indicizzati {new_kbps} gruppi audio")
             elif status == "download_error":
                 self._log(view, f"[ERRORE] {filename}: download fallito")
             elif status == "stopped":
@@ -948,7 +1067,35 @@ class Api:
 
             self._emit("upgrade:progress", payload_evt)
 
-        upgrade_folder(directory, threshold, cookies_path, recursive, progress_cb)
+        def resolve_cb(source_path: str, candidates: list) -> dict:
+            """Bloccante: emette evento e attende scelta utente via queue.
+            Se archive_auto_pick=True, salta il modal e sceglie il primo
+            candidato (già ordinato per bitrate DESC nel core).
+            `source_path` è il path assoluto del file sorgente (per il preview
+            audio nel modal)."""
+            src_name = Path(source_path).name if source_path else ""
+            if archive_auto_pick and candidates:
+                top = candidates[0]
+                path = top.get("path") if isinstance(top, dict) else str(top)
+                self._log(view, f"[AUTO] {src_name}: match multipli, uso {Path(path).name}")
+                return {"action": "use_local", "path": path}
+            self._emit("upgrade:candidates_needed", {
+                "file": src_name,
+                "source_path": source_path,
+                "candidates": candidates,
+            })
+            try:
+                # Timeout 10 min — se l'utente sparisce, salta il brano
+                choice = self._upgrade_resolve_q.get(timeout=600)
+            except queue.Empty:
+                choice = {"action": "skip"}
+            return choice
+
+        upgrade_folder(
+            directory, threshold, cookies_path, recursive, progress_cb,
+            archive_dir=archive_dir,
+            resolve_callback=resolve_cb,
+        )
         self._emit("upgrade:done", {"ok": True})
 
     # ------------------------------------------------------------------
@@ -1165,6 +1312,110 @@ class Api:
             "subfolder": subfolder,
         })
 
+    # ================================================================
+    # Traxsource charts
+    # ================================================================
+    def _traxsource_output_dir(self, out_root: str, genre_name: str) -> Path:
+        """Cartella dove finiscono i file Traxsource. Coerente con la
+        sanitizzazione di `start_tracks_download` (slash -> underscore)."""
+        safe_genre = genre_name.replace("/", "_").replace("\\", "_").strip()
+        subfolder = f"Traxsource_{safe_genre}" if safe_genre else "Traxsource"
+        return Path(out_root) / subfolder
+
+    def traxsource_genres(self) -> list:
+        """Lista dei generi Traxsource per il dropdown UI."""
+        return traxsource.list_genres()
+
+    def traxsource_fetch_chart(self, slug: str, force_refresh: bool = False) -> dict:
+        """Fetches la Top 100 corrente per il genere. Salva l'ultimo genere in config."""
+        try:
+            cfg = load_config()
+            cfg["traxsource_last_genre"] = slug
+            save_config(cfg)
+        except Exception:
+            pass
+
+        try:
+            tracks = traxsource.fetch_top100(slug, force_refresh=force_refresh)
+        except ValueError as e:
+            return {"ok": False, "error": "invalid_genre", "message": str(e)}
+        except traxsource.TraxsourceUnreachableError as e:
+            return {"ok": False, "error": "unreachable", "message": str(e)}
+        except traxsource.TraxsourceParseError as e:
+            return {"ok": False, "error": "parse", "message": str(e)}
+
+        return {"ok": True, "tracks": [asdict(t) for t in tracks]}
+
+    def traxsource_check_existing(self, tracks: list, genre_name: str) -> list:
+        """True per ogni track già presente nella cartella output Traxsource.
+        Match euristico: filename (senza extension) deve contenere sia il titolo
+        che il primo artista (case-insensitive)."""
+        cfg = load_config()
+        out_root = (cfg.get("output_dir") or "").strip()
+        if not out_root:
+            return [False] * len(tracks)
+
+        out_dir = self._traxsource_output_dir(out_root, genre_name)
+        if not out_dir.exists():
+            return [False] * len(tracks)
+
+        existing_stems = [p.stem.lower() for p in out_dir.glob("*.mp3")]
+        result = []
+        for t in tracks:
+            title = (t.get("title") or "").lower().strip()
+            artists = (t.get("artists") or "")
+            first_artist = artists.split(",")[0].split("&")[0].strip().lower()
+            if not title or not first_artist:
+                result.append(False)
+                continue
+            result.append(any(
+                (title in stem and first_artist in stem)
+                for stem in existing_stems
+            ))
+        return result
+
+    def traxsource_download_selected(self, tracks: list, genre_name: str) -> dict:
+        """Converte i TraxsourceTrack in tracklist compatibile con
+        start_tracks_download + costruisce metadata paralleli per il tagger ID3
+        (album=label Traxsource, date=YYYY-MM corrente, genre=nome genere)."""
+        cfg = load_config()
+        out_root = (cfg.get("output_dir") or "").strip()
+        if not out_root:
+            return {"ok": False, "error": "Cartella output non impostata"}
+
+        target = self._traxsource_output_dir(out_root, genre_name)
+        subfolder = target.name  # es. "Traxsource_Tech House"
+
+        import datetime as _dt
+        current_month = _dt.date.today().strftime("%Y-%m")
+
+        converted: list = []
+        metadata: list = []
+        for t in tracks:
+            title = (t.get("title") or "").strip()
+            artists = (t.get("artists") or "").strip()
+            if not title:
+                continue
+            converted.append({"name": title, "artist": artists})
+            metadata.append({
+                "title": title,
+                "artist": artists,
+                "album": (t.get("label") or "").strip() or f"Traxsource Top 100 {current_month}",
+                "date": current_month,
+                "genre": genre_name,
+                "cover_url": (t.get("cover_url_large") or t.get("image_url") or "").strip(),
+            })
+
+        if not converted:
+            return {"ok": False, "error": "Nessun brano valido"}
+
+        return self.start_tracks_download({
+            "tracks": converted,
+            "output_dir": out_root,
+            "subfolder": subfolder,
+            "metadata": metadata,
+        })
+
     # ================================================================
     # Music Search — Spotify + YouTube
     # ================================================================
@@ -1452,3 +1703,563 @@ class Api:
             "subfolder": subfolder,
             "metadata": metadata,
         })
+
+    # ================================================================
+    # WAV -> MP3 converter
+    # ================================================================
+    def convert_pick_wav_files(self) -> list:
+        """Apre file picker multi-selezione per .wav. Ritorna list di path."""
+        if not self.window:
+            return []
+        try:
+            filetypes = ("WAV files (*.wav)",)
+            result = self.window.create_file_dialog(
+                self._open_dialog_type(),
+                allow_multiple=True,
+                file_types=filetypes,
+            )
+        except Exception:
+            return []
+        if not result:
+            return []
+        return [str(p) for p in result if str(p).lower().endswith(".wav")]
+
+    def convert_pick_wav_folder(self, recursive: bool = True) -> list:
+        """Apre folder picker, scan .wav (opzionalmente ricorsivo)."""
+        from core import converter
+        if not self.window:
+            return []
+        try:
+            result = self.window.create_file_dialog(self._folder_dialog_type())
+        except Exception:
+            return []
+        if not result:
+            return []
+        folder = str(result[0]) if isinstance(result, (list, tuple)) else str(result)
+        return converter.list_wav_files(folder, recursive=recursive)
+
+    def convert_start(self, payload: dict) -> dict:
+        """Avvia conversione batch. Payload:
+            {files: [str], bitrate: int, vbr: bool, output_dir: str | None}
+        Se output_dir e vuoto/None, il .mp3 va accanto al .wav.
+        """
+        if self._any_job_running():
+            return {"ok": False, "error": "Un'operazione e' gia in corso"}
+
+        files = payload.get("files") or []
+        if not files:
+            return {"ok": False, "error": "Nessun file selezionato"}
+
+        try:
+            bitrate = int(payload.get("bitrate", 320))
+        except (TypeError, ValueError):
+            bitrate = 320
+        if bitrate not in (128, 192, 256, 320):
+            return {"ok": False, "error": "Bitrate non valido"}
+        vbr = bool(payload.get("vbr", False))
+        output_dir = (payload.get("output_dir") or "").strip() or None
+
+        gate = self._gate("audio")
+        if gate:
+            return gate
+
+        self._download_thread = threading.Thread(
+            target=self._convert_worker,
+            args=(list(files), bitrate, vbr, output_dir),
+            daemon=True,
+        )
+        self._download_thread.start()
+        return {"ok": True}
+
+    def convert_stop(self) -> dict:
+        from core import converter as conv
+        conv.request_stop()
+        self._log("convert", "[INFO] Interruzione richiesta...")
+        return {"ok": True}
+
+    def _convert_worker(self, files: list, bitrate: int, vbr: bool,
+                        output_dir: Optional[str]) -> None:
+        from core import converter as conv
+        conv.reset_stop()
+        view = "convert"
+        total = len(files)
+        mode = "VBR" if vbr else "CBR"
+
+        self._log(view, f"[INFO] Conversione di {total} file (MP3 {bitrate}k {mode})")
+        if output_dir:
+            self._log(view, f"[INFO] Destinazione: {output_dir}")
+        else:
+            self._log(view, "[INFO] Destinazione: accanto al file originale")
+
+        _last = [0.0]
+
+        def make_progress_cb(idx: int, filename: str):
+            def cb(pct: int):
+                import time as _t
+                if pct == -1:
+                    # interruzione
+                    self._emit("convert:progress", {
+                        "idx": idx, "total": total, "file": filename,
+                        "status": "stopped", "pct": 0,
+                    })
+                    return
+                # throttle
+                now = _t.monotonic()
+                if pct < 100 and now - _last[0] < 0.10:
+                    return
+                _last[0] = now
+                self._emit("convert:progress", {
+                    "idx": idx, "total": total, "file": filename,
+                    "status": "converting" if pct < 100 else "done",
+                    "pct": pct,
+                    "overall": min(((idx + pct / 100) / total), 1.0) if total else 0,
+                })
+            return cb
+
+        for i, src_path in enumerate(files):
+            if conv.is_stopped():
+                self._log(view, "[INFO] Conversione interrotta.")
+                break
+
+            src = Path(src_path)
+            if not src.exists():
+                self._log(view, f"[ERRORE] File mancante: {src.name}")
+                continue
+
+            dst_dir = Path(output_dir) if output_dir else src.parent
+            dst = dst_dir / (src.stem + ".mp3")
+
+            # Skip se il .mp3 esiste gia (protezione contro overwrite)
+            if dst.exists():
+                self._log(view, f"[SKIP] {dst.name} esiste gia'")
+                self._emit("convert:progress", {
+                    "idx": i, "total": total, "file": src.name,
+                    "status": "skipped", "pct": 100,
+                    "overall": min(((i + 1) / total), 1.0) if total else 1,
+                })
+                continue
+
+            self._log(view, f"[CONVERTI] {src.name}")
+            self._emit("convert:progress", {
+                "idx": i, "total": total, "file": src.name,
+                "status": "converting", "pct": 0,
+            })
+
+            try:
+                conv.convert_wav_to_mp3(
+                    str(src), str(dst),
+                    bitrate=bitrate, vbr=vbr,
+                    progress_callback=make_progress_cb(i, src.name),
+                )
+                self._log(view, f"[OK] {dst.name}")
+            except Exception as e:
+                self._log(view, f"[ERRORE] {src.name}: {e}")
+                self._emit("convert:progress", {
+                    "idx": i, "total": total, "file": src.name,
+                    "status": f"error: {e}", "pct": 0,
+                })
+
+        self._emit("convert:done", {"ok": True})
+
+    # ================================================================
+    # DEDUP — audio duplicati via Chromaprint fingerprinting
+    # ================================================================
+    def dedup_pick_folder(self) -> str:
+        """Folder picker per la cartella da scansionare."""
+        return self.browse_directory()
+
+    def dedup_start_scan(self, payload: dict) -> dict:
+        """Avvia worker di scansione. Payload: {directory, recursive}.
+
+        Salva `dedup_last_folder` e `dedup_recursive` in config per la
+        prossima apertura del tab.
+        """
+        if self._dedup_thread and self._dedup_thread.is_alive():
+            return {"ok": False, "error": "Scansione dedup gia in corso"}
+
+        directory = (payload.get("directory") or "").strip()
+        recursive = bool(payload.get("recursive", True))
+        method = (payload.get("method") or "fingerprint").strip()
+        if method not in ("fingerprint", "filename"):
+            method = "fingerprint"
+
+        if not directory:
+            return {"ok": False, "error": "Cartella non impostata"}
+        if not os.path.isdir(directory):
+            return {"ok": False, "error": "Cartella non trovata"}
+
+        # Persist last folder/recursive/method
+        try:
+            cfg = load_config()
+            cfg["dedup_last_folder"] = directory
+            cfg["dedup_recursive"] = recursive
+            cfg["dedup_method"] = method
+            save_config(cfg)
+        except Exception:
+            pass
+
+        self._dedup_thread = threading.Thread(
+            target=self._dedup_worker,
+            args=(directory, recursive, method),
+            daemon=True,
+        )
+        self._dedup_thread.start()
+        return {"ok": True}
+
+    def dedup_stop_scan(self) -> dict:
+        dedup.request_stop()
+        self._log("dedup", "[INFO] Interruzione richiesta...")
+        return {"ok": True}
+
+    def dedup_move_to_trash(self, paths: list) -> dict:
+        """Sposta i file in cestino via send2trash. Non consuma quota."""
+        if not isinstance(paths, list):
+            return {"ok": False, "error": "paths deve essere una lista"}
+        # Sanitize: solo str non vuote
+        clean = [str(p).strip() for p in paths if p and str(p).strip()]
+        if not clean:
+            return {"ok": False, "error": "Nessun file da cancellare"}
+
+        result = dedup.move_to_trash(clean)
+        moved_n = len(result.get("moved", []))
+        failed_n = len(result.get("failed", []))
+        if moved_n:
+            self._log("dedup", f"[OK] {moved_n} file spostati nel cestino")
+        for f in result.get("failed", []):
+            self._log("dedup",
+                      f"[ERRORE] {f.get('path')}: {f.get('error')}")
+        return {"ok": True, "moved": result.get("moved", []),
+                "failed": result.get("failed", []),
+                "moved_count": moved_n, "failed_count": failed_n}
+
+    def _dedup_worker(self, directory: str, recursive: bool,
+                       method: str = "fingerprint") -> None:
+        """Esegue la scansione in background e emette progress/done."""
+        view = "dedup"
+        dedup.reset_stop()
+        method_label = "audio fingerprint" if method == "fingerprint" else "nome file"
+        self._log(view, f"[INFO] Scansione: {directory} (metodo: {method_label}, recursive={recursive})")
+
+        _last = [0.0]
+        _THROTTLE = 0.05
+
+        def progress_cb(idx: int, total: int, filename: str, status: str, err_msg: str = "") -> None:
+            # Throttle solo eventi 'computing'/'cached' (che possono essere migliaia)
+            if status in ("computing", "cached"):
+                now = time.monotonic()
+                if now - _last[0] < _THROTTLE and idx != total:
+                    return
+                _last[0] = now
+            payload_evt = {
+                "idx": idx, "total": total,
+                "filename": filename, "status": status,
+            }
+            if err_msg:
+                payload_evt["error_msg"] = err_msg
+            if total > 0:
+                payload_evt["overall"] = min(idx / total, 1.0)
+            if status == "completed":
+                payload_evt["overall"] = 1.0
+                self._log(view, f"[INFO] Scansione completata ({total} file).")
+            elif status == "stopped":
+                self._log(view, "[INFO] Scansione interrotta.")
+            elif status == "error" and filename:
+                detail = f": {err_msg}" if err_msg else ""
+                self._log(view, f"[ERRORE] {filename}{detail}")
+            self._emit("dedup:progress", payload_evt)
+
+        def group_cb(group: dict) -> None:
+            """Emit streaming: appena un gruppo raggiunge/aggiorna >=2 file."""
+            try:
+                self._emit("dedup:group", group)
+            except Exception:
+                pass
+
+        try:
+            groups = dedup.scan_folder(directory, recursive=recursive,
+                                       progress_callback=progress_cb,
+                                       method=method,
+                                       group_callback=group_cb)
+        except Exception as e:
+            self._log(view, f"[ERRORE] {e}")
+            self._emit("dedup:done", {"ok": False, "error": str(e),
+                                       "groups": []})
+            return
+
+        n_groups = len(groups)
+        n_dupes = sum(max(0, len(g) - 1) for g in groups)
+        total_bytes = sum(sum(int(e.get("size") or 0) for e in g[1:])
+                          for g in groups)
+        self._log(view,
+                  f"[INFO] Gruppi: {n_groups} — duplicati: {n_dupes} — "
+                  f"spazio recuperabile: ~{total_bytes // 1024 // 1024} MB")
+        self._emit("dedup:done", {
+            "ok": True,
+            "groups": groups,
+            "n_groups": n_groups,
+            "n_dupes": n_dupes,
+            "reclaimable_bytes": total_bytes,
+        })
+
+    # ================================================================
+    # CATALOGA — sposta file audio in <output>/<Anno>/<Genere>/
+    # via Chromaprint + AcoustID.
+    # ================================================================
+    def catalog_pick_source_folder(self) -> str:
+        """Folder picker per la cartella sorgente da catalogare."""
+        return self.browse_directory()
+
+    def catalog_pick_target_folder(self) -> str:
+        """Folder picker per la cartella target (dove finiscono i file
+        organizzati). Se l'utente lascia vuoto → si usa la source."""
+        return self.browse_directory()
+
+    def catalog_start_scan(self, payload: dict) -> dict:
+        """Avvia worker di scansione + lookup AcoustID. Payload:
+        {source, target?, recursive}. Persiste last source/target/recursive.
+        """
+        if self._catalog_thread and self._catalog_thread.is_alive():
+            return {"ok": False, "error": "Scansione catalogo gia in corso"}
+
+        source = (payload.get("source") or "").strip()
+        target = (payload.get("target") or "").strip()
+        recursive = bool(payload.get("recursive", True))
+
+        if not source:
+            return {"ok": False, "error": "Cartella input non impostata"}
+        if not os.path.isdir(source):
+            return {"ok": False, "error": "Cartella input non trovata"}
+        # target vuoto → sposta in-place nella source
+        if not target:
+            target = source
+
+        # Persist last source/target/recursive
+        try:
+            cfg = load_config()
+            cfg["catalog_last_source"] = source
+            cfg["catalog_last_target"] = target
+            cfg["catalog_recursive"] = recursive
+            save_config(cfg)
+        except Exception:
+            pass
+
+        self._catalog_thread = threading.Thread(
+            target=self._catalog_worker,
+            args=(source, recursive),
+            daemon=True,
+        )
+        self._catalog_thread.start()
+        return {"ok": True}
+
+    def catalog_stop_scan(self) -> dict:
+        catalog.request_stop()
+        self._log("catalog", "[INFO] Interruzione richiesta...")
+        return {"ok": True}
+
+    def catalog_move_files(self, entries: list, target_root: str, layout: str = "year_genre") -> dict:
+        """Sposta le entry selezionate in <target_root>/<year>/<genre>/.
+
+        Non consuma quota (e' una riorganizzazione di file locali,
+        non un download). Ritorna il summary con moved/failed/operations.
+        """
+        if not isinstance(entries, list):
+            return {"ok": False, "error": "entries deve essere una lista"}
+        target = (target_root or "").strip()
+        if not target:
+            return {"ok": False, "error": "Cartella destinazione mancante"}
+
+        def log_cb(op: dict) -> None:
+            src = op.get("src", "")
+            dst = op.get("dst", "")
+            self._log("catalog", f"[MOVE] {src} → {dst}")
+            try:
+                self._emit("catalog:log", op)
+            except Exception:
+                pass
+
+        try:
+            safe_layout = layout if layout in ("year_genre", "genre_year") else "year_genre"
+            result = catalog.move_files(entries, target, log_callback=log_cb, layout=safe_layout)
+        except Exception as e:
+            self._log("catalog", f"[ERRORE] move: {e}")
+            return {"ok": False, "error": str(e)}
+
+        moved_n = result.get("moved", 0)
+        failed = result.get("failed", []) or []
+        if moved_n:
+            self._log("catalog", f"[OK] {moved_n} file organizzati")
+        for f in failed:
+            self._log("catalog",
+                      f"[ERRORE] {f.get('path')}: {f.get('error')}")
+
+        return {
+            "ok": True,
+            "moved": moved_n,
+            "failed_count": len(failed),
+            "failed": failed,
+            "operations": result.get("operations", []),
+        }
+
+    # ------------------------------------------------------------------
+    # FLATTEN — sposta tutti i file audio delle sotto-cartelle nella root
+    # ------------------------------------------------------------------
+    def flatten_pick_folder(self) -> str:
+        if not self.window:
+            return ""
+        try:
+            r = self.window.create_file_dialog(self._folder_dialog_type())
+        except Exception:
+            return ""
+        if not r:
+            return ""
+        return str(r[0]) if isinstance(r, (list, tuple)) else str(r)
+
+    def flatten_start(self, payload: dict) -> dict:
+        """Payload: {directory, remove_empty}."""
+        if self._flatten_thread and self._flatten_thread.is_alive():
+            return {"ok": False, "error": "Operazione gia' in corso"}
+        directory = (payload.get("directory") or "").strip()
+        if not directory:
+            return {"ok": False, "error": "Cartella non impostata"}
+        if not os.path.isdir(directory):
+            return {"ok": False, "error": "Cartella non trovata"}
+        remove_empty = bool(payload.get("remove_empty", True))
+        self._flatten_thread = threading.Thread(
+            target=self._flatten_worker,
+            args=(directory, remove_empty),
+            daemon=True,
+        )
+        self._flatten_thread.start()
+        return {"ok": True}
+
+    def flatten_stop(self) -> dict:
+        flatten.request_stop()
+        return {"ok": True}
+
+    def _flatten_worker(self, directory: str, remove_empty: bool) -> None:
+        view = "flatten"
+        self._log(view, f"[INFO] Appiattisco: {directory} (remove_empty={remove_empty})")
+
+        def progress_cb(idx, total, name, status, err=""):
+            payload = {"idx": idx, "total": total, "filename": name, "status": status}
+            if err:
+                payload["error_msg"] = err
+            if total > 0:
+                payload["overall"] = min(idx / total, 1.0)
+            if status == "completed":
+                payload["overall"] = 1.0
+                self._log(view, f"[INFO] Completato: {total} file processati.")
+            elif status == "stopped":
+                self._log(view, "[INFO] Operazione interrotta.")
+            elif status == "error" and name:
+                self._log(view, f"[ERRORE] {name}: {err}")
+            self._emit("flatten:progress", payload)
+
+        def log_cb(op):
+            self._log(view, f"[MOVE] {op.get('src','')} → {op.get('dst','')}")
+
+        try:
+            result = flatten.flatten_folder(
+                directory,
+                remove_empty=remove_empty,
+                progress_callback=progress_cb,
+                log_callback=log_cb,
+            )
+        except Exception as e:
+            self._log(view, f"[ERRORE] {e}")
+            self._emit("flatten:done", {"ok": False, "error": str(e)})
+            return
+
+        moved = result.get("moved", 0)
+        failed = result.get("failed", []) or []
+        dirs_removed = result.get("dirs_removed", 0)
+        self._log(view, f"[OK] Spostati {moved} file. Cartelle rimosse: {dirs_removed}. Falliti: {len(failed)}.")
+        self._emit("flatten:done", {
+            "ok": True,
+            "moved": moved,
+            "failed_count": len(failed),
+            "failed": failed,
+            "dirs_removed": dirs_removed,
+        })
+
+    def _catalog_worker(self, directory: str, recursive: bool) -> None:
+        """Esegue scan + lookup AcoustID in background, emette streaming."""
+        view = "catalog"
+        catalog.reset_stop()
+        self._log(view,
+                  f"[INFO] Scansione: {directory} (recursive={recursive})")
+
+        _last = [0.0]
+        _THROTTLE = 0.05
+
+        def progress_cb(idx: int, total: int, filename: str,
+                         status: str, err_msg: str = "") -> None:
+            # Throttle solo eventi "computing"/"lookup" (possono essere tanti)
+            if status in ("computing", "lookup"):
+                now = time.monotonic()
+                if now - _last[0] < _THROTTLE and idx != total:
+                    return
+                _last[0] = now
+            payload_evt = {
+                "idx": idx, "total": total,
+                "filename": filename, "status": status,
+            }
+            if err_msg:
+                payload_evt["error_msg"] = err_msg
+            if total > 0:
+                payload_evt["overall"] = min(idx / total, 1.0)
+            if status == "completed":
+                payload_evt["overall"] = 1.0
+                self._log(view, f"[INFO] Scansione completata ({total} file).")
+            elif status == "stopped":
+                self._log(view, "[INFO] Scansione interrotta.")
+            elif status == "error" and filename:
+                detail = f": {err_msg}" if err_msg else ""
+                self._log(view, f"[ERRORE] {filename}{detail}")
+            self._emit("catalog:progress", payload_evt)
+
+        def entry_cb(entry: dict) -> None:
+            """Streaming: appena un file è processato, emit alla UI."""
+            try:
+                self._emit("catalog:entry", entry)
+            except Exception:
+                pass
+
+        # Prova a ottenere un token Spotify per il fallback (facoltativo).
+        # Se non ci sono creds o l'auth fallisce, procediamo senza fallback.
+        spotify_token = None
+        try:
+            cfg = load_config()
+            cid = (cfg.get("client_id") or "").strip()
+            csecret = (cfg.get("client_secret") or "").strip()
+            if cid and csecret:
+                spotify_token = get_access_token(cid, csecret)
+        except Exception:
+            spotify_token = None
+
+        try:
+            entries = catalog.scan_folder(
+                directory,
+                recursive=recursive,
+                progress_callback=progress_cb,
+                entry_callback=entry_cb,
+                spotify_token=spotify_token,
+            )
+        except Exception as e:
+            self._log(view, f"[ERRORE] {e}")
+            self._emit("catalog:done", {"ok": False, "error": str(e),
+                                         "entries": []})
+            return
+
+        n_matched = sum(1 for e in entries if e.get("matched"))
+        n_unmatched = len(entries) - n_matched
+        self._log(view,
+                  f"[INFO] Match AcoustID: {n_matched} · non identificati: "
+                  f"{n_unmatched} (totale {len(entries)})")
+        self._emit("catalog:done", {
+            "ok": True,
+            "entries": entries,
+            "n_total": len(entries),
+            "n_matched": n_matched,
+            "n_unmatched": n_unmatched,
+        })

build_macos.py

@@ -39,21 +39,23 @@ def log(msg):
 # 1. Scarica yt-dlp standalone
 # =========================================================================
 def download_ytdlp():
-    """Scarica il binario standalone di yt-dlp per macOS."""
+    """Scarica il binario standalone di yt-dlp per macOS.
+
+    Usa il NIGHTLY channel invece dello stable perche' YouTube rompe le
+    API ogni 1-2 settimane e la stable resta indietro di 3-4 settimane
+    tipicamente. La nightly esce quasi ogni giorno con i fix.
+    Sempre re-download: garantisce che ogni build imbarca yt-dlp fresco.
+    """
     arch = platform.machine()  # arm64 o x86_64
     if arch == "arm64":
-        url = "https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos"
+        url = "https://github.com/yt-dlp/yt-dlp-nightly-builds/releases/latest/download/yt-dlp_macos"
     else:
-        url = "https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos_legacy"
+        url = "https://github.com/yt-dlp/yt-dlp-nightly-builds/releases/latest/download/yt-dlp_macos_legacy"
 
     dest = BUNDLE_DIR / "yt-dlp"
-    if dest.exists():
-        log(f"yt-dlp gia presente: {dest}")
-        return dest
-
-    log(f"Scarico yt-dlp da {url} ...")
     BUNDLE_DIR.mkdir(parents=True, exist_ok=True)
 
+    log(f"Scarico yt-dlp nightly da {url} ...")
     # Usa curl perche urllib di Python 3.8 ha problemi SSL su macOS
     subprocess.run(
         ["curl", "-L", "-o", str(dest), url],
@@ -64,6 +66,48 @@ def download_ytdlp():
     return dest
 
 
+# =========================================================================
+# 1b. Scarica fpcalc (Chromaprint) — usato dal tab Dedup
+# =========================================================================
+def download_fpcalc():
+    """Scarica il binario universal Chromaprint fpcalc per macOS."""
+    dest = BUNDLE_DIR / "fpcalc"
+    if dest.exists():
+        log(f"fpcalc gia presente: {dest}")
+        return dest
+
+    url = ("https://github.com/acoustid/chromaprint/releases/download/"
+           "v1.5.1/chromaprint-fpcalc-1.5.1-macos-universal.tar.gz")
+    log(f"Scarico fpcalc da {url} ...")
+    BUNDLE_DIR.mkdir(parents=True, exist_ok=True)
+
+    tmp_tar = BUNDLE_DIR / "_fpcalc.tar.gz"
+    subprocess.run(["curl", "-L", "-o", str(tmp_tar), url], check=True)
+    # Estrae ovunque nella cartella, poi trova fpcalc e lo sposta al posto
+    tmp_extract = BUNDLE_DIR / "_fpcalc_extract"
+    if tmp_extract.exists():
+        shutil.rmtree(tmp_extract)
+    tmp_extract.mkdir()
+    subprocess.run(["tar", "-xzf", str(tmp_tar), "-C", str(tmp_extract)],
+                   check=True)
+    # Trova fpcalc nel folder estratto
+    found = None
+    for p in tmp_extract.rglob("fpcalc"):
+        if p.is_file():
+            found = p
+            break
+    if not found:
+        shutil.rmtree(tmp_extract, ignore_errors=True)
+        tmp_tar.unlink(missing_ok=True)
+        raise RuntimeError("fpcalc non trovato nell'archivio")
+    shutil.copy2(found, dest)
+    dest.chmod(dest.stat().st_mode | stat.S_IEXEC)
+    shutil.rmtree(tmp_extract, ignore_errors=True)
+    tmp_tar.unlink(missing_ok=True)
+    log(f"fpcalc scaricato: {dest}")
+    return dest
+
+
 # =========================================================================
 # 2. Raccogli ffmpeg/ffprobe + dylib
 # =========================================================================
@@ -511,6 +555,7 @@ def main():
         shutil.rmtree(BUNDLE_DIR)
 
     download_ytdlp()
+    download_fpcalc()
     bundle_ffmpeg()
     run_pyinstaller()
 

build_windows.py

@@ -29,8 +29,10 @@ BUILD_DIR = ROOT / "build"
 DIST_DIR = ROOT / "dist"
 BUNDLE_DIR = ROOT / "bundle_bin"
 
-YTDLP_URL = "https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp.exe"
+YTDLP_URL = "https://github.com/yt-dlp/yt-dlp-nightly-builds/releases/latest/download/yt-dlp.exe"
 FFMPEG_URL = "https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-win64-gpl.zip"
+FPCALC_URL = ("https://github.com/acoustid/chromaprint/releases/download/"
+              "v1.5.1/chromaprint-fpcalc-1.5.1-windows-x86_64.zip")
 
 
 def log(msg):
@@ -41,13 +43,11 @@ def log(msg):
 # 1. Scarica yt-dlp.exe
 # =========================================================================
 def download_ytdlp():
+    """Scarica sempre il nightly fresco: la stable resta indietro di
+    3-4 settimane rispetto alle rotture API YouTube."""
     dest = BUNDLE_DIR / "yt-dlp.exe"
-    if dest.exists():
-        log(f"yt-dlp.exe gia presente: {dest}")
-        return dest
-
-    log(f"Scarico yt-dlp.exe ...")
     BUNDLE_DIR.mkdir(parents=True, exist_ok=True)
+    log(f"Scarico yt-dlp.exe nightly ...")
     urllib.request.urlretrieve(YTDLP_URL, dest)
     log(f"yt-dlp.exe scaricato ({dest.stat().st_size // 1024 // 1024} MB)")
     return dest
@@ -87,6 +87,33 @@ def download_ffmpeg():
         sys.exit(1)
 
 
+# =========================================================================
+# 2b. Scarica fpcalc.exe (Chromaprint) — usato dal tab Dedup
+# =========================================================================
+def download_fpcalc():
+    dest = BUNDLE_DIR / "fpcalc.exe"
+    if dest.exists():
+        log("fpcalc.exe gia presente")
+        return
+
+    log(f"Scarico fpcalc.exe ...")
+    BUNDLE_DIR.mkdir(parents=True, exist_ok=True)
+
+    response = urllib.request.urlopen(FPCALC_URL)
+    zip_data = io.BytesIO(response.read())
+    with zipfile.ZipFile(zip_data) as zf:
+        for member in zf.namelist():
+            basename = Path(member).name
+            if basename == "fpcalc.exe":
+                data = zf.read(member)
+                dest.write_bytes(data)
+                log(f"  Estratto: fpcalc.exe ({len(data) // 1024} KB)")
+
+    if not dest.exists():
+        print("ERRORE: fpcalc.exe non trovato nello zip!")
+        sys.exit(1)
+
+
 # =========================================================================
 # 3. PyInstaller
 # =========================================================================
@@ -187,6 +214,7 @@ def main():
 
     download_ytdlp()
     download_ffmpeg()
+    download_fpcalc()
     run_pyinstaller()
 
     print("\n" + "=" * 50)

core/acoustid.py

@@ -0,0 +1,240 @@
+"""AcoustID + MusicBrainz lookup con cache SQLite.
+
+Data un fingerprint Chromaprint (calcolato via `fpcalc`), interroga il
+servizio pubblico AcoustID (https://acoustid.org) per recuperare
+metadati sulla traccia: artista, titolo, anno di rilascio piu' antico
+e (best-effort) un genere estratto dai tag dei release group MusicBrainz.
+
+I risultati vengono cacheati su SQLite (chiave = fingerprint) per non
+sprecare quota API su scan ripetute. La rate limit e' auto-imposta a
+~3 req/s per rispettare i limiti pubblici AcoustID.
+
+Nota: l'API AcoustID base NON restituisce sempre il genere — dipende
+dai tag presenti nel release group MusicBrainz. Molte tracce dance
+electronic hanno pochi tag; il campo `genre` puo' quindi essere vuoto
+anche con un match valido. In quel caso il chiamante rimapa in
+"Unknown Genre".
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from pathlib import Path
+from typing import Optional
+
+import requests
+
+
+# App key pubblica per MusicTools. Puo' essere sovrascritta passando
+# `app_key` esplicito o via config. Chiavi si ottengono gratis su
+# https://acoustid.org/api-key (max ~3 req/s).
+# Default: chiave pubblica di MusicBrainz Picard (open-source tagger ufficiale).
+# Per uso intenso registra una app dedicata su https://acoustid.org/api-key
+# e settala in Impostazioni → acoustid_app_key.
+_APP_KEY = "v8pQ6oyB"
+_API_URL = "https://api.acoustid.org/v2/lookup"
+_REQUEST_TIMEOUT = 20
+_RATE_LIMIT_SEC = 0.35  # ~3 req/s max
+
+
+def _cache_db_path() -> Path:
+    """Path del DB di cache dei lookup AcoustID.
+
+    Riusa `_get_config_dir` di core.config cosi' finisce nella stessa
+    cartella di config.json e dedup_cache.db.
+    """
+    from core.config import _get_config_dir
+    return _get_config_dir() / "catalog_cache.db"
+
+
+def _init_db(conn: sqlite3.Connection) -> None:
+    """Crea (idempotente) lo schema della cache."""
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS lookups(
+            fingerprint TEXT PRIMARY KEY,
+            payload     TEXT NOT NULL,
+            cached_at   REAL NOT NULL
+        );
+        """
+    )
+    conn.commit()
+
+
+def _open_cache() -> sqlite3.Connection:
+    """Apre (creando se serve) la connessione alla cache."""
+    p = _cache_db_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(p))
+    _init_db(conn)
+    return conn
+
+
+def _get_cached(conn: sqlite3.Connection, fingerprint: str) -> Optional[dict]:
+    row = conn.execute(
+        "SELECT payload FROM lookups WHERE fingerprint = ?", (fingerprint,)
+    ).fetchone()
+    if not row:
+        return None
+    try:
+        return json.loads(row[0])
+    except Exception:
+        return None
+
+
+def _put_cache(conn: sqlite3.Connection, fingerprint: str, data: dict) -> None:
+    conn.execute(
+        "INSERT OR REPLACE INTO lookups(fingerprint, payload, cached_at)"
+        " VALUES (?, ?, ?)",
+        (fingerprint, json.dumps(data, ensure_ascii=False), time.time()),
+    )
+    conn.commit()
+
+
+# Rate-limit state (globale al processo — vale anche se lookup chiamato
+# da thread diversi: non e' esattamente thread-safe ma il worst-case e'
+# una richiesta leggermente troppo veloce, non un ban).
+_last_request_at = [0.0]
+
+
+def _throttle() -> None:
+    """Attende quel tanto che basta per rispettare _RATE_LIMIT_SEC."""
+    now = time.monotonic()
+    elapsed = now - _last_request_at[0]
+    if elapsed < _RATE_LIMIT_SEC:
+        time.sleep(_RATE_LIMIT_SEC - elapsed)
+    _last_request_at[0] = time.monotonic()
+
+
+def _extract_min_year(releases: list) -> Optional[int]:
+    """Trova l'anno piu' antico tra i release. Ignora date invalide."""
+    year: Optional[int] = None
+    for rel in releases or []:
+        date = rel.get("date") if isinstance(rel, dict) else None
+        if not isinstance(date, dict):
+            continue
+        y = date.get("year")
+        if isinstance(y, int) and y > 0:
+            if year is None or y < year:
+                year = y
+    return year
+
+
+def _extract_top_genre(releases: list) -> str:
+    """Sceglie il tag piu' rilevante dai releasegroup (max `count`)."""
+    for rel in releases or []:
+        rg = rel.get("releasegroup") if isinstance(rel, dict) else None
+        if not isinstance(rg, dict):
+            continue
+        tags = rg.get("tags") or []
+        if not isinstance(tags, list) or not tags:
+            continue
+        try:
+            top = max(tags, key=lambda t: int(t.get("count", 0) or 0))
+        except (TypeError, ValueError):
+            top = tags[0]
+        name = (top.get("name") or "").strip() if isinstance(top, dict) else ""
+        if name:
+            return name
+    return ""
+
+
+def lookup(fingerprint: str, duration: float,
+           app_key: str = _APP_KEY) -> dict:
+    """Interroga AcoustID (o cache) per una tripla (year, genre, title).
+
+    Ritorna sempre un dict con almeno il campo `matched: bool`. In caso
+    di match valido, aggiunge `year: int|None`, `genre: str`,
+    `artist: str`, `title: str`. In caso di errore aggiunge `error: str`
+    ma NON alza eccezione: chiamanti di batch (Cataloga) devono poter
+    continuare anche se una chiamata singola fallisce.
+
+    Cache: risultati validi E "no match" vengono cacheati sul
+    fingerprint — cosi' scansioni ripetute non re-interrogano l'API.
+    Errori transitori (rete/HTTP) NON vengono cacheati.
+    """
+    if not fingerprint:
+        return {"matched": False, "error": "fingerprint vuoto"}
+    if not app_key:
+        app_key = _APP_KEY
+
+    conn = _open_cache()
+    try:
+        cached = _get_cached(conn, fingerprint)
+        if cached is not None:
+            return cached
+
+        _throttle()
+        try:
+            resp = requests.get(
+                _API_URL,
+                params={
+                    "client": app_key,
+                    "meta": "recordings+releases+releasegroups",
+                    "duration": int(duration or 0),
+                    "fingerprint": fingerprint,
+                },
+                timeout=_REQUEST_TIMEOUT,
+            )
+        except requests.RequestException as e:
+            return {"matched": False, "error": f"network: {e}"}
+        except Exception as e:
+            return {"matched": False, "error": str(e)}
+
+        if resp.status_code != 200:
+            return {"matched": False, "error": f"HTTP {resp.status_code}"}
+
+        try:
+            data = resp.json()
+        except Exception as e:
+            return {"matched": False, "error": f"JSON malformato: {e}"}
+
+        if data.get("status") != "ok":
+            err = data.get("error", {}) or {}
+            msg = err.get("message") if isinstance(err, dict) else str(err)
+            return {"matched": False, "error": msg or "AcoustID status non-ok"}
+
+        results = data.get("results") or []
+        if not results:
+            result = {"matched": False}
+            _put_cache(conn, fingerprint, result)
+            return result
+
+        # Match col miglior score
+        best = max(results, key=lambda r: r.get("score", 0) or 0)
+        recordings = best.get("recordings") or []
+        if not recordings:
+            result = {"matched": False}
+            _put_cache(conn, fingerprint, result)
+            return result
+
+        rec = recordings[0] or {}
+        title = (rec.get("title") or "").strip()
+        artists = rec.get("artists") or []
+        artist_names = [
+            (a.get("name") or "").strip()
+            for a in artists
+            if isinstance(a, dict) and a.get("name")
+        ]
+        artist = ", ".join(n for n in artist_names if n)
+
+        releases = rec.get("releases") or []
+        year = _extract_min_year(releases)
+        genre = _extract_top_genre(releases)
+
+        result = {
+            "matched": bool(year or genre or title),
+            "year": year,
+            "genre": genre,
+            "artist": artist,
+            "title": title,
+        }
+        _put_cache(conn, fingerprint, result)
+        return result
+    finally:
+        try:
+            conn.close()
+        except Exception:
+            pass

core/applog.py

@@ -0,0 +1,134 @@
+"""Setup logging persistente su file rotante.
+
+Chiamato in `main.py` prima di qualsiasi import pesante. Il file di log
+vive in:
+  - macOS:   ~/Library/Application Support/MusicTools/logs/app.log
+  - Windows: %APPDATA%/MusicTools/logs/app.log
+  - Dev:     <project_root>/logs/app.log
+
+Rotazione: 1 file al giorno, mantiene gli ultimi 7. Cattura anche stdout
+e stderr per non perdere `print()` o traceback che l'app windowed
+altrimenti scarterebbe.
+"""
+
+from __future__ import annotations
+
+import logging
+import logging.handlers
+import os
+import sys
+from pathlib import Path
+
+
+_setup_done = False
+
+
+def _logs_dir() -> Path:
+    """Directory dei log — parallela a config.json."""
+    if getattr(sys, "frozen", False):
+        if sys.platform == "win32":
+            base = Path(os.environ.get("APPDATA", Path.home()))
+        else:
+            base = Path.home() / "Library" / "Application Support"
+        d = base / "MusicTools" / "logs"
+    else:
+        d = Path(__file__).resolve().parent.parent / "logs"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def log_file_path() -> Path:
+    return _logs_dir() / "app.log"
+
+
+def _install_excepthook() -> None:
+    """Cattura ogni uncaught exception dentro il file di log.
+    NON tocca sys.stdout/stderr (romperebbe WebKit)."""
+    import traceback
+    logger = logging.getLogger("uncaught")
+    _orig = sys.excepthook
+
+    def _hook(exc_type, exc_value, tb):
+        try:
+            logger.error(
+                "Uncaught: %s: %s\n%s",
+                exc_type.__name__,
+                exc_value,
+                "".join(traceback.format_exception(exc_type, exc_value, tb)),
+            )
+        except Exception:
+            pass
+        try:
+            _orig(exc_type, exc_value, tb)
+        except Exception:
+            pass
+
+    sys.excepthook = _hook
+
+    # Anche per exception in threading (Python 3.8+)
+    try:
+        _orig_thread = threading_excepthook = getattr(__import__("threading"), "excepthook", None)
+
+        def _thread_hook(args):
+            try:
+                logger.error(
+                    "Thread uncaught: %s: %s\n%s",
+                    args.exc_type.__name__,
+                    args.exc_value,
+                    "".join(traceback.format_exception(args.exc_type, args.exc_value, args.exc_traceback)),
+                )
+            except Exception:
+                pass
+            if _orig_thread:
+                try:
+                    _orig_thread(args)
+                except Exception:
+                    pass
+
+        if threading_excepthook is not None:
+            __import__("threading").excepthook = _thread_hook
+    except Exception:
+        pass
+
+
+def setup() -> Path:
+    """Configura il logger root — NON tocca stdout/stderr per non rompere
+    WebKit (segfault). Cattura traceback via sys.excepthook + logger.
+    """
+    global _setup_done
+    path = log_file_path()
+    if _setup_done:
+        return path
+    _setup_done = True
+
+    root = logging.getLogger()
+    root.setLevel(logging.INFO)
+
+    fmt = logging.Formatter(
+        fmt="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    # File handler con rotazione giornaliera (max 7 file = 7 giorni)
+    fh = logging.handlers.TimedRotatingFileHandler(
+        str(path),
+        when="midnight",
+        backupCount=7,
+        encoding="utf-8",
+        utc=False,
+    )
+    fh.setFormatter(fmt)
+    fh.setLevel(logging.INFO)
+    root.addHandler(fh)
+
+    # Se in dev, mantieni anche console (utile durante lavoro)
+    if not getattr(sys, "frozen", False):
+        ch = logging.StreamHandler(sys.__stderr__)
+        ch.setFormatter(fmt)
+        ch.setLevel(logging.INFO)
+        root.addHandler(ch)
+
+    _install_excepthook()
+
+    root.info(f"MusicTools log start — file: {path}")
+    return path

core/beatport.py

@@ -24,6 +24,7 @@ class BeatportTrack:
     duration_sec: int
     beatport_id: int
     image_url: str = ""   # URL cover art (default vuoto per retrocompatibilità test)
+    release_date: str = ""  # ISO YYYY-MM-DD, vuoto se mancante
 
     @property
     def display(self) -> str:
@@ -177,6 +178,7 @@ def _parse_tracks(data: dict) -> list:
                 duration_sec=length_ms // 1000,
                 beatport_id=int(item.get("id") or 0),
                 image_url=_extract_image_url(item.get("image")),
+                release_date=str(item.get("publish_date") or item.get("new_release_date") or "").strip(),
             )
         except (TypeError, ValueError) as e:
             raise BeatportParseError(f"track[{i}] shape inattesa: {e}") from e

core/catalog.py

@@ -0,0 +1,390 @@
+"""Cataloga file audio in sottocartelle <Anno>/<Genere>/ via AcoustID.
+
+Pipeline:
+  1. Scansiona la cartella (opzionalmente ricorsivo) filtrando per
+     estensioni audio (AUDIO_EXTENSIONS di core.upgrader).
+  2. Per ogni file calcola il fingerprint Chromaprint (`fpcalc`,
+     riusa `core.dedup.compute_fingerprint`).
+  3. Lookup AcoustID (cache SQLite) per estrarre year + genre +
+     artist + title.
+  4. `move_files` sposta le entry selezionate in
+     `<target>/<Year>/<Genre>/<filename>`. Se manca year/genre usa
+     "Unknown Year" / "Unknown Genre".
+
+Progress callback firma:
+    (processed, total, filename, status[, err_msg])
+Status: 'computing' | 'lookup' | 'error' | 'stopped' | 'completed'.
+
+`entry_callback(entry)` viene chiamato per ogni file processato,
+permettendo alla UI di aggiornare la tabella in streaming.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import threading
+from pathlib import Path
+from typing import Callable, Optional
+
+from core.acoustid import lookup
+
+
+_NUM_PREFIX = re.compile(r"^\s*\d+\s*[.\-)]\s*")
+_PAREN_TAIL = re.compile(r"\s*[\[(].*?[\])]\s*$")
+_DASH_SPLIT = re.compile(r"\s+[-–—]\s+")
+
+
+def _parse_filename(stem: str) -> tuple:
+    """Estrae (artist, title) da nome file tipo 'Artista - Titolo (Mix)'.
+    Ritorna ('', stem) se non c'è dash separator."""
+    s = stem.strip()
+    s = _NUM_PREFIX.sub("", s)
+    # Rimuove parentesi finali (Extended Mix), [Original Mix] ecc.
+    for _ in range(3):
+        s = _PAREN_TAIL.sub("", s).strip()
+    parts = _DASH_SPLIT.split(s, maxsplit=1)
+    if len(parts) == 2:
+        artist, title = parts[0].strip(), parts[1].strip()
+        if artist and title:
+            return artist, title
+    return "", s
+
+
+def _spotify_lookup_fallback(stem: str, token: str, genre_cache: dict) -> Optional[dict]:
+    """Fallback quando AcoustID non trova nulla: search Spotify col filename.
+
+    Ritorna {matched, year, genre, artist, title} o None su errore.
+    Popola `genre_cache` (dict artist_id → primo genere) per non chiamare
+    l'API `/artists/<id>` per ogni traccia dello stesso artista.
+    """
+    from core.spotify_client import search_tracks, get_artist_genres
+
+    artist_hint, title_hint = _parse_filename(stem)
+    query = f"{artist_hint} {title_hint}".strip() if artist_hint else title_hint
+    if not query:
+        return None
+
+    try:
+        results = search_tracks(token, query, limit=1)
+    except Exception:
+        return None
+    if not results:
+        return None
+
+    top = results[0]
+    release_date = (top.get("release_date") or "").strip()
+    year = None
+    if len(release_date) >= 4 and release_date[:4].isdigit():
+        year = int(release_date[:4])
+
+    # Prendi il primo genere dell'artista (con cache per non abusare l'API)
+    genre = ""
+    artist_id = top.get("artist_id") or ""
+    if artist_id:
+        if artist_id in genre_cache:
+            genres = genre_cache[artist_id]
+        else:
+            try:
+                genres = get_artist_genres(token, artist_id) or []
+            except Exception:
+                genres = []
+            genre_cache[artist_id] = genres
+        if genres:
+            genre = genres[0]
+
+    return {
+        "matched": bool(year or genre or top.get("name")),
+        "year": year,
+        "genre": genre,
+        "artist": top.get("artists", "") or "",
+        "title": top.get("name", "") or "",
+        "_source": "spotify",
+    }
+from core.dedup import compute_fingerprint
+from core.paths import find_fpcalc
+from core.upgrader import AUDIO_EXTENSIONS
+
+
+# ------------------------------------------------------------------
+# Stop / interrupt
+# ------------------------------------------------------------------
+_stop_event = threading.Event()
+
+
+def request_stop() -> None:
+    """Segnala al worker di interrompere la scansione al prossimo file."""
+    _stop_event.set()
+
+
+def reset_stop() -> None:
+    """Azzera il flag di stop prima di iniziare una nuova scansione."""
+    _stop_event.clear()
+
+
+def is_stopped() -> bool:
+    return _stop_event.is_set()
+
+
+# ------------------------------------------------------------------
+# Sanitize path
+# ------------------------------------------------------------------
+# Caratteri vietati o problematici in nomi cartella cross-platform.
+# `/` e `\` sono trattati a parte perche' MusicBrainz usa spesso
+# genre-name-style come "electronic/house": vogliamo rimpiazzarli con
+# `_` (non con lo split, che creerebbe path nesting indesiderati).
+_FORBIDDEN = re.compile(r'[<>:"|?*\\/]+')
+_MULTI_SPACE = re.compile(r"\s+")
+
+
+def _sanitize_folder(name: str) -> str:
+    """Sanitize per path filesystem: rimpiazza chars non validi con `_`.
+
+    - Chars vietati Windows (<>:"|?*) + slash → `_`
+    - Spazi multipli collassati in uno solo
+    - Trim finale
+    - Troncamento a 100 char (limite pratico per path lunghi cumulati)
+    """
+    if not name:
+        return ""
+    s = _FORBIDDEN.sub("_", name).strip()
+    s = _MULTI_SPACE.sub(" ", s)
+    if len(s) > 100:
+        s = s[:100].rstrip()
+    return s
+
+
+# ------------------------------------------------------------------
+# Scan
+# ------------------------------------------------------------------
+def scan_folder(
+    directory: str,
+    recursive: bool = True,
+    progress_callback: Optional[Callable] = None,
+    entry_callback: Optional[Callable] = None,
+    spotify_token: Optional[str] = None,
+) -> list:
+    """Scansiona la cartella e ritorna la lista di entry con metadata.
+
+    Ogni entry:
+        {path, size, fingerprint, matched, year, genre, artist, title, error?}
+
+    - `progress_callback(idx, total, filename, status[, err])`:
+      chiamato con status 'computing' | 'lookup' | 'error' | 'stopped'
+      | 'completed'. Firma retrocompatibile (4 args) supportata.
+    - `entry_callback(entry)`: chiamato appena ogni file e' processato
+      (streaming alla UI).
+    """
+    reset_stop()
+    base = Path(directory)
+    if not base.exists() or not base.is_dir():
+        if progress_callback:
+            _emit_progress(progress_callback, 0, 0, "", "completed", "")
+        return []
+
+    files: list = []
+    iterator = base.rglob("*") if recursive else base.iterdir()
+    for f in iterator:
+        try:
+            if f.is_file() and f.suffix.lower() in AUDIO_EXTENSIONS:
+                files.append(f)
+        except OSError:
+            continue
+    files.sort()
+
+    total = len(files)
+    if total == 0:
+        if progress_callback:
+            _emit_progress(progress_callback, 0, 0, "", "completed", "")
+        return []
+
+    fpcalc = find_fpcalc()
+
+    entries: list = []
+    # Cache locale per non re-fetchare i generi dello stesso artista Spotify
+    _spotify_genre_cache: dict = {}
+    for i, fp_path in enumerate(files, start=1):
+        if is_stopped():
+            _emit_progress(progress_callback, i - 1, total, "", "stopped", "")
+            return entries
+
+        try:
+            size = fp_path.stat().st_size
+        except OSError as e:
+            _emit_progress(progress_callback, i, total, fp_path.name,
+                           "error", f"stat: {e}")
+            continue
+
+        # Fingerprint
+        _emit_progress(progress_callback, i, total, fp_path.name, "computing", "")
+        res = compute_fingerprint(fpcalc, str(fp_path)) if fpcalc else None
+        if not res or not res.get("fingerprint"):
+            err = (res or {}).get("_error") or "fpcalc non disponibile"
+            entry = {
+                "path": str(fp_path), "size": size, "fingerprint": "",
+                "matched": False, "error": err,
+                "year": None, "genre": "", "artist": "", "title": "",
+            }
+            entries.append(entry)
+            if entry_callback:
+                try:
+                    entry_callback(entry)
+                except Exception:
+                    pass
+            _emit_progress(progress_callback, i, total, fp_path.name,
+                           "error", err)
+            continue
+
+        fp_hash = res["fingerprint"]
+        duration = float(res.get("duration") or 0)
+
+        # AcoustID lookup (cache SQLite dentro core.acoustid)
+        _emit_progress(progress_callback, i, total, fp_path.name, "lookup", "")
+        info = lookup(fp_hash, duration)
+
+        matched = bool(info.get("matched"))
+        source = "acoustid"
+
+        # Fallback su Spotify se AcoustID non ha trovato niente e abbiamo il token.
+        # Molti file (mashup, bootleg, extended mix) non sono in MusicBrainz ma Spotify
+        # ha ottima copertura per dance/electronic.
+        if not matched and spotify_token:
+            _emit_progress(progress_callback, i, total, fp_path.name, "spotify_fallback", "")
+            fb = _spotify_lookup_fallback(fp_path.stem, spotify_token, _spotify_genre_cache)
+            if fb and fb.get("matched"):
+                info = fb
+                matched = True
+                source = "spotify"
+
+        entry = {
+            "path": str(fp_path),
+            "size": size,
+            "fingerprint": fp_hash,
+            "matched": matched,
+            "year": info.get("year"),
+            "genre": (info.get("genre") or "").strip(),
+            "artist": (info.get("artist") or "").strip(),
+            "title": (info.get("title") or "").strip(),
+            "source": source,
+        }
+        if info.get("error"):
+            entry["error"] = info["error"]
+
+        entries.append(entry)
+        if entry_callback:
+            try:
+                entry_callback(entry)
+            except Exception:
+                pass
+
+    _emit_progress(progress_callback, total, total, "", "completed", "")
+    return entries
+
+
+def _emit_progress(cb: Optional[Callable], idx: int, total: int,
+                    name: str, status: str, err: str = "") -> None:
+    """Chiama progress_callback in modo retrocompatibile (4 o 5 args)."""
+    if not cb:
+        return
+    try:
+        cb(idx, total, name, status, err)
+    except TypeError:
+        try:
+            cb(idx, total, name, status)
+        except Exception:
+            pass
+    except Exception:
+        pass
+
+
+# ------------------------------------------------------------------
+# Move
+# ------------------------------------------------------------------
+def move_files(entries: list, target_root: str,
+                log_callback: Optional[Callable] = None,
+                layout: str = "year_genre") -> dict:
+    """Sposta i file elencati in `<target_root>/<year>/<genre>/<filename>`.
+
+    - Se `year` manca → cartella "Unknown Year"
+    - Se `genre` manca → cartella "Unknown Genre"
+    - Se il file destinazione esiste gia', aggiunge suffisso _1, _2...
+      (non sovrascrive mai).
+
+    Ritorna un dict:
+        {
+          "moved": int,               # numero file spostati con successo
+          "skipped": int,             # entries scartate (0 per ora)
+          "failed": [{path, error}],  # errori per file
+          "operations": [{src, dst}], # log ops riuscite (utile per undo)
+        }
+
+    `log_callback(op)` viene chiamato per ogni operazione riuscita
+    (streaming alla UI).
+    """
+    target_base = Path(target_root)
+    try:
+        target_base.mkdir(parents=True, exist_ok=True)
+    except OSError as e:
+        return {"moved": 0, "skipped": 0,
+                "failed": [{"path": target_root,
+                            "error": f"impossibile creare target: {e}"}],
+                "operations": []}
+
+    result = {"moved": 0, "skipped": 0, "failed": [], "operations": []}
+
+    for entry in entries or []:
+        src_str = (entry or {}).get("path") or ""
+        src = Path(src_str)
+        if not src_str:
+            result["failed"].append({"path": "",
+                                     "error": "path mancante"})
+            continue
+        if not src.exists():
+            result["failed"].append({"path": src_str,
+                                     "error": "file non esiste"})
+            continue
+
+        year = entry.get("year")
+        genre = (entry.get("genre") or "").strip()
+
+        year_folder = str(year) if year else "Unknown Year"
+        genre_folder = _sanitize_folder(genre) or "Unknown Genre"
+
+        if layout == "genre_year":
+            dst_dir = target_base / genre_folder / year_folder
+        else:  # year_genre (default)
+            dst_dir = target_base / year_folder / genre_folder
+        try:
+            dst_dir.mkdir(parents=True, exist_ok=True)
+        except OSError as e:
+            result["failed"].append({"path": src_str,
+                                     "error": f"mkdir: {e}"})
+            continue
+
+        dst = dst_dir / src.name
+
+        # Anti-overwrite: se il target esiste, aggiungi _1, _2, ...
+        if dst.exists():
+            stem = dst.stem
+            suffix = dst.suffix
+            i = 1
+            while dst.exists():
+                dst = dst_dir / f"{stem}_{i}{suffix}"
+                i += 1
+
+        try:
+            shutil.move(str(src), str(dst))
+        except Exception as e:
+            result["failed"].append({"path": src_str, "error": str(e)})
+            continue
+
+        result["moved"] += 1
+        op = {"src": src_str, "dst": str(dst)}
+        result["operations"].append(op)
+        if log_callback:
+            try:
+                log_callback(op)
+            except Exception:
+                pass
+
+    return result

core/config.py

@@ -5,7 +5,7 @@ import os
 import sys
 from pathlib import Path
 
-VERSION = "v1.8.5"
+VERSION = "v1.11.2"
 
 
 APP_NAME = "MusicTools"
@@ -68,14 +68,26 @@ DEFAULTS = {
     "bitrate": "320K",
     "hq_threshold": 310,
     "cookies_path": str(_project_dir / "cookies.txt"),
+    "cookies_browser": "",  # "" | chrome | safari | firefox | edge | brave
     "output_dir": str(_project_dir / "MUSICA"),
     "theme": "dark",
     # ---- Beatport ----
     "beatport_last_genre": "melodic-house-techno",  # ultimo genere Top 100 caricato
+    # ---- Traxsource ----
+    "traxsource_last_genre": "tech-house",
     # ---- Music Search (Spotify + YouTube) ----
     "spotify_search_last_query": "",
     "spotify_search_artist_mode": False,
     "youtube_search_last_query": "",
+    # ---- Dedup (audio duplicati via Chromaprint) ----
+    "dedup_last_folder": "",
+    "dedup_recursive": True,
+    "dedup_method": "fingerprint",  # "fingerprint" | "filename"
+    # ---- Cataloga (AcoustID -> <Anno>/<Genere>/) ----
+    "catalog_last_source": "",
+    "catalog_last_target": "",
+    "catalog_recursive": True,
+    "acoustid_app_key": "",  # opzionale: se vuoto usa default in core/acoustid.py
     # ---- Licenza ----
     "license_key": "",          # chiave fornita all'utente via email
     "license_email": "",        # email associata all'acquisto

core/converter.py

@@ -0,0 +1,176 @@
+"""Conversione WAV -> MP3 via ffmpeg subprocess."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import threading
+from pathlib import Path
+from typing import Callable, Optional
+
+from core.paths import find_ffmpeg_dir, subprocess_flags
+
+
+_stop_event = threading.Event()
+_current_process: Optional[subprocess.Popen] = None
+_process_lock = threading.Lock()
+
+
+def request_stop() -> None:
+    _stop_event.set()
+    with _process_lock:
+        if _current_process and _current_process.poll() is None:
+            _current_process.terminate()
+
+
+def reset_stop() -> None:
+    _stop_event.clear()
+
+
+def is_stopped() -> bool:
+    return _stop_event.is_set()
+
+
+# VBR quality mapping da bitrate label a -q:a (libmp3lame). Piu basso = migliore qualita.
+# Vedi https://trac.ffmpeg.org/wiki/Encode/MP3
+_VBR_QUALITY = {
+    128: 5,
+    192: 2,
+    256: 0,
+    320: 0,  # V0 e' ~245k medio; per >V0 c'e' solo CBR 320
+}
+
+
+def _find_ffmpeg() -> str:
+    """Trova il binario ffmpeg dentro bundle_bin o PATH.
+
+    Solleva RuntimeError se non trovato.
+    """
+    ffmpeg_dir = find_ffmpeg_dir()
+    if ffmpeg_dir:
+        for name in ("ffmpeg", "ffmpeg.exe"):
+            p = Path(ffmpeg_dir) / name
+            if p.exists():
+                return str(p)
+    # Fallback PATH
+    import shutil
+    ff = shutil.which("ffmpeg")
+    if ff:
+        return ff
+    raise RuntimeError("ffmpeg non trovato nel bundle o nel PATH")
+
+
+def convert_wav_to_mp3(
+    input_path: str,
+    output_path: str,
+    bitrate: int = 320,
+    vbr: bool = False,
+    progress_callback: Optional[Callable] = None,
+) -> None:
+    """Converte un file WAV in MP3.
+
+    Args:
+        input_path: file .wav sorgente
+        output_path: file .mp3 destinazione
+        bitrate: 128 / 192 / 256 / 320
+        vbr: True per Variable Bit Rate (-q:a), False per Constant (-b:a)
+        progress_callback: opzionale, chiamato con (percent 0..100)
+
+    Raises:
+        RuntimeError: se ffmpeg non trovato o exit non-zero.
+        FileNotFoundError: se input_path non esiste.
+    """
+    src = Path(input_path)
+    if not src.exists():
+        raise FileNotFoundError(f"File sorgente non trovato: {input_path}")
+
+    dst = Path(output_path)
+    dst.parent.mkdir(parents=True, exist_ok=True)
+
+    ffmpeg = _find_ffmpeg()
+
+    cmd = [ffmpeg, "-y", "-i", str(src)]
+    if vbr:
+        quality = _VBR_QUALITY.get(bitrate, 2)
+        cmd.extend(["-c:a", "libmp3lame", "-q:a", str(quality)])
+    else:
+        cmd.extend(["-c:a", "libmp3lame", "-b:a", f"{bitrate}k"])
+    cmd.extend([
+        "-map_metadata", "0",     # copia metadata WAV se presenti
+        "-id3v2_version", "3",
+        "-progress", "pipe:2",     # progress su stderr in formato key=value
+        str(dst),
+    ])
+
+    # Prova a ottenere la durata totale per calcolare % — leggendo lo stream INFO
+    duration_us = _probe_duration_us(ffmpeg, str(src))
+
+    global _current_process
+    with _process_lock:
+        _current_process = subprocess.Popen(
+            cmd,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,
+            **subprocess_flags(),
+        )
+        proc = _current_process
+
+    try:
+        for line in proc.stderr:
+            if is_stopped():
+                proc.terminate()
+                if progress_callback:
+                    progress_callback(-1)  # segnale di interruzione
+                return
+            if not progress_callback or not duration_us:
+                continue
+            # ffmpeg -progress emette "out_time_us=<microsecondi>"
+            m = re.match(r"out_time_us=(\d+)", line.strip())
+            if m:
+                elapsed = int(m.group(1))
+                pct = min(100, int(elapsed * 100 / duration_us))
+                progress_callback(pct)
+
+        rc = proc.wait()
+
+        if rc != 0:
+            raise RuntimeError(f"ffmpeg exit {rc}")
+
+        if progress_callback:
+            progress_callback(100)
+    finally:
+        with _process_lock:
+            _current_process = None
+
+
+def _probe_duration_us(ffmpeg: str, input_path: str) -> int:
+    """Estrae la durata in microsecondi via ffmpeg -f null. Ritorna 0 se non riesce."""
+    try:
+        # ffprobe potrebbe non essere sempre bundlato; usa ffmpeg
+        result = subprocess.run(
+            [ffmpeg, "-i", input_path, "-f", "null", "-"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            **subprocess_flags(),
+        )
+        # Cerca "Duration: HH:MM:SS.ms"
+        m = re.search(r"Duration:\s+(\d+):(\d+):(\d+)\.(\d+)", result.stderr)
+        if m:
+            h, mi, s, ms = map(int, m.groups())
+            total_sec = h * 3600 + mi * 60 + s + ms / 100
+            return int(total_sec * 1_000_000)
+    except Exception:
+        pass
+    return 0
+
+
+def list_wav_files(directory: str, recursive: bool = True) -> list:
+    """Scan cartella per file .wav. Ritorna list di path stringa ordinati."""
+    root = Path(directory)
+    if not root.is_dir():
+        return []
+    pattern = "**/*.wav" if recursive else "*.wav"
+    return sorted(str(p) for p in root.glob(pattern) if p.is_file())

core/dedup.py

@@ -0,0 +1,518 @@
+"""Deduplicator audio via Chromaprint fingerprinting + SQLite cache.
+
+Pipeline:
+  1. Scansiona la cartella (opzionalmente ricorsivo) filtrando per
+     estensioni audio (AUDIO_EXTENSIONS di core.upgrader).
+  2. Per ogni file calcola il fingerprint Chromaprint (`fpcalc -json`).
+     Il valore viene messo in cache SQLite: al re-scan, se
+     (size, mtime) coincide col record, riusiamo il fingerprint senza
+     rilanciare fpcalc.
+  3. Raggruppa i file per fingerprint identico (>= 2 file). Per ogni
+     gruppo, i file vengono ordinati per bitrate DESC (tie-break: size
+     DESC): il primo e' quello "da tenere", gli altri i duplicati.
+  4. `move_to_trash` invia i path selezionati al cestino di sistema
+     tramite send2trash (reversibile via Finder/Explorer).
+
+Progress callback firma:
+    (processed: int, total: int, filename: str, status: str)
+Status validi: 'scanning' | 'computing' | 'cached' | 'error' | 'stopped'
+              | 'completed'.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import subprocess
+import threading
+from pathlib import Path
+from typing import Callable, Optional
+
+from core.paths import find_fpcalc, subprocess_flags
+from core.upgrader import AUDIO_EXTENSIONS, get_bitrate
+
+
+# Timeout massimo per una singola invocazione fpcalc.
+_FPCALC_TIMEOUT_SEC = 30
+
+
+# ------------------------------------------------------------------
+# Stop / interrupt
+# ------------------------------------------------------------------
+_stop_event = threading.Event()
+
+
+def request_stop() -> None:
+    """Segnala al worker di interrompere la scansione al prossimo file."""
+    _stop_event.set()
+
+
+def reset_stop() -> None:
+    """Azzera il flag di stop prima di iniziare una nuova scansione."""
+    _stop_event.clear()
+
+
+def is_stopped() -> bool:
+    return _stop_event.is_set()
+
+
+# ------------------------------------------------------------------
+# Cache SQLite
+# ------------------------------------------------------------------
+def _cache_db_path() -> Path:
+    """Path del DB di cache dei fingerprint.
+
+    Riusa `_get_config_dir` di core.config cosi' finisce nella stessa
+    cartella di config.json (~/Library/Application Support/MusicTools/
+    su macOS, %APPDATA%/MusicTools/ su Windows, project root in dev).
+    """
+    from core.config import _get_config_dir
+    return _get_config_dir() / "dedup_cache.db"
+
+
+def _init_db(conn: sqlite3.Connection) -> None:
+    """Crea (idempotente) lo schema della cache."""
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS files (
+            path        TEXT PRIMARY KEY,
+            size        INTEGER NOT NULL,
+            mtime       REAL NOT NULL,
+            duration    REAL,
+            fingerprint TEXT,
+            bitrate     INTEGER
+        )
+        """
+    )
+    conn.commit()
+
+
+def _open_cache(db_path: Optional[Path] = None) -> sqlite3.Connection:
+    """Apre (creando se serve) la connessione alla cache."""
+    p = db_path or _cache_db_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(p))
+    _init_db(conn)
+    return conn
+
+
+def _cache_get(conn: sqlite3.Connection, path: str,
+               size: int, mtime: float) -> Optional[dict]:
+    """Ritorna il record se (size, mtime) invariato, altrimenti None."""
+    cur = conn.execute(
+        "SELECT size, mtime, duration, fingerprint, bitrate FROM files WHERE path = ?",
+        (path,),
+    )
+    row = cur.fetchone()
+    if not row:
+        return None
+    csize, cmtime, dur, fp, br = row
+    # Tolleranza minima sul mtime (float precision su alcuni FS)
+    if csize != size or abs(float(cmtime) - float(mtime)) > 0.001:
+        return None
+    if not fp:
+        return None
+    return {
+        "size": int(csize),
+        "mtime": float(cmtime),
+        "duration": float(dur) if dur is not None else 0.0,
+        "fingerprint": str(fp),
+        "bitrate": int(br) if br is not None else 0,
+    }
+
+
+def _cache_put(conn: sqlite3.Connection, path: str, size: int, mtime: float,
+               duration: float, fingerprint: str, bitrate: int) -> None:
+    """Upsert (SQLite ha ON CONFLICT REPLACE via INSERT OR REPLACE)."""
+    conn.execute(
+        "INSERT OR REPLACE INTO files (path, size, mtime, duration, fingerprint, bitrate)"
+        " VALUES (?, ?, ?, ?, ?, ?)",
+        (path, int(size), float(mtime), float(duration or 0),
+         str(fingerprint or ""), int(bitrate or 0)),
+    )
+    conn.commit()
+
+
+# ------------------------------------------------------------------
+# fpcalc
+# ------------------------------------------------------------------
+def _run_fpcalc(fpcalc: str, path: str, length: Optional[int] = None) -> dict:
+    """Esegue fpcalc una volta. Ritorna {duration, fingerprint} su successo
+    o {_error: str} su fallimento."""
+    cmd = [fpcalc, "-json"]
+    if length is not None:
+        cmd += ["-length", str(length)]
+    cmd.append(str(path))
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=_FPCALC_TIMEOUT_SEC,
+            **subprocess_flags(),
+        )
+    except subprocess.TimeoutExpired:
+        return {"_error": f"timeout {_FPCALC_TIMEOUT_SEC}s"}
+    except (OSError, ValueError) as e:
+        return {"_error": f"subprocess: {e}"}
+    if proc.returncode != 0:
+        err = (proc.stderr or proc.stdout or "").strip().splitlines()
+        msg = err[-1] if err else f"exit {proc.returncode}"
+        return {"_error": msg[:200]}
+    try:
+        data = json.loads(proc.stdout or "{}")
+    except (json.JSONDecodeError, ValueError) as e:
+        return {"_error": f"JSON malformato: {e}"}
+    fp = data.get("fingerprint")
+    if not fp:
+        return {"_error": "fingerprint vuoto (audio troppo corto?)"}
+    try:
+        dur = float(data.get("duration") or 0)
+    except (TypeError, ValueError):
+        dur = 0.0
+    return {"duration": dur, "fingerprint": str(fp)}
+
+
+def compute_fingerprint(fpcalc: str, path: str) -> Optional[dict]:
+    """Chiama fpcalc e ritorna {duration, fingerprint} o {_error}.
+
+    Se il primo tentativo (full length) fallisce con "Invalid data" o simili
+    (frame audio corrotti che libav rifiuta), riprova con `-length 30`.
+    Molti file danneggiati hanno i frame corrotti nella parte finale e
+    limitando la scansione ai primi 30s si riesce a estrarre comunque
+    un fingerprint affidabile (30s bastano per l'unicità Chromaprint).
+    """
+    if not fpcalc:
+        return {"_error": "fpcalc non trovato nel bundle"}
+
+    res = _run_fpcalc(fpcalc, path)
+    if "fingerprint" in res:
+        return res
+
+    err_msg = res.get("_error", "").lower()
+
+    # Retry 1: frame audio corrotti → riduci finestra a 30s
+    corrupt_signals = ("invalid data", "decoding audio frame",
+                       "error while decoding", "invalid frame")
+    if any(sig in err_msg for sig in corrupt_signals):
+        res2 = _run_fpcalc(fpcalc, path, length=30)
+        if "fingerprint" in res2:
+            res2["_partial"] = True  # 30s soltanto
+            return res2
+
+    # Retry 2: fingerprint vuoto → prova con finestra piu' lunga (60s)
+    # nel caso l'intro sia silenzio/muto (chromaprint richiede audio "reale")
+    if "vuoto" in err_msg or "empty" in err_msg:
+        res2 = _run_fpcalc(fpcalc, path, length=60)
+        if "fingerprint" in res2:
+            res2["_partial"] = True
+            return res2
+        # Ancora vuoto → prova algoritmo differente (chromaprint algo 1)
+        # tramite subprocess diretto perche' _run_fpcalc non lo supporta
+        try:
+            proc = subprocess.run(
+                [fpcalc, "-json", "-length", "60", "-algorithm", "1", str(path)],
+                capture_output=True, text=True,
+                timeout=_FPCALC_TIMEOUT_SEC,
+                **subprocess_flags(),
+            )
+            if proc.returncode == 0:
+                data = json.loads(proc.stdout or "{}")
+                fp = data.get("fingerprint")
+                if fp:
+                    return {
+                        "duration": float(data.get("duration") or 0),
+                        "fingerprint": str(fp),
+                        "_partial": True,
+                    }
+        except Exception:
+            pass
+
+    return res
+
+
+# ------------------------------------------------------------------
+# Scan
+# ------------------------------------------------------------------
+def _iter_audio_files(directory: str, recursive: bool) -> list[Path]:
+    """Elenca tutti i file audio (estensione case-insensitive)."""
+    base = Path(directory)
+    if not base.exists() or not base.is_dir():
+        return []
+    files: list[Path] = []
+    if recursive:
+        for f in base.rglob("*"):
+            if f.is_file() and f.suffix.lower() in AUDIO_EXTENSIONS:
+                files.append(f)
+    else:
+        for f in base.iterdir():
+            if f.is_file() and f.suffix.lower() in AUDIO_EXTENSIONS:
+                files.append(f)
+    files.sort()
+    return files
+
+
+def _scan_by_filename(files: list, progress_callback: Optional[Callable],
+                       group_callback: Optional[Callable] = None,
+                       similarity_threshold: float = 0.8) -> list[list[dict]]:
+    """Raggruppa file per similarità nome (Jaccard sui token normalizzati),
+    algoritmo INCREMENTALE: per ogni nuovo file cerca match tra i gruppi già
+    formati (lookup O(K) dove K = numero gruppi). Emette streaming via
+    `group_callback` appena un gruppo raggiunge ≥ 2 file.
+    """
+    from core.upgrader import _normalize_stem  # riuso
+
+    def _pc(idx, total_n, name, status, err=""):
+        if not progress_callback:
+            return
+        try:
+            progress_callback(idx, total_n, name, status, err)
+        except TypeError:
+            progress_callback(idx, total_n, name, status)
+
+    def _gc(group_id: str, entries: list) -> None:
+        if group_callback:
+            try:
+                group_callback({"id": group_id, "entries": list(entries)})
+            except Exception:
+                pass
+
+    total = len(files)
+    # Ogni voce: {"id": str, "key_tokens": frozenset, "entries": [dict]}
+    groups: list = []
+
+    for i, fp_path in enumerate(files, start=1):
+        if is_stopped():
+            _pc(i - 1, total, "", "stopped")
+            break
+        try:
+            size = fp_path.stat().st_size
+        except OSError as e:
+            _pc(i, total, fp_path.name, "error", f"stat: {e}")
+            continue
+        tokens = frozenset(_normalize_stem(fp_path.stem))
+        if not tokens:
+            _pc(i, total, fp_path.name, "error", "nome senza token utili")
+            continue
+        try:
+            bitrate = get_bitrate(fp_path)
+        except Exception:
+            bitrate = 0
+        entry = {
+            "path": str(fp_path), "size": size, "bitrate": bitrate,
+            "duration": 0, "fingerprint": "",
+        }
+
+        # Cerca match nei gruppi già formati (lineare sui gruppi, non sui file)
+        matched = None
+        for g in groups:
+            common = len(tokens & g["key_tokens"])
+            if common == 0:
+                continue
+            union = len(tokens | g["key_tokens"])
+            if union > 0 and (common / union) >= similarity_threshold:
+                matched = g
+                break
+
+        if matched is not None:
+            was_solo = len(matched["entries"]) == 1
+            matched["entries"].append(entry)
+            matched["entries"].sort(key=lambda e: (-e["bitrate"], -e["size"]))
+            # Streaming: emit ogni volta che il gruppo diventa/rimane ≥ 2 file
+            _gc(matched["id"], matched["entries"])
+        else:
+            gid = f"fn_{len(groups)}_{fp_path.stem[:20]}"
+            groups.append({
+                "id": gid,
+                "key_tokens": set(tokens),
+                "entries": [entry],
+            })
+        _pc(i, total, fp_path.name, "cached")
+
+    # Ritorna solo i gruppi con >= 2 file
+    result = [sorted(g["entries"], key=lambda e: (-e["bitrate"], -e["size"]))
+              for g in groups if len(g["entries"]) >= 2]
+    result.sort(key=lambda g: -max(e["size"] for e in g))
+    _pc(total, total, "", "completed")
+    return result
+
+
+def scan_folder(
+    directory: str,
+    recursive: bool = True,
+    progress_callback: Optional[Callable] = None,
+    method: str = "fingerprint",
+    group_callback: Optional[Callable] = None,
+) -> list[list[dict]]:
+    """Ritorna la lista di gruppi di file duplicati (>= 2 file).
+
+    Ogni file nel gruppo e' un dict:
+        {path, size, bitrate, duration, fingerprint}
+
+    Gruppi ordinati per size del file piu' grande DESC (i gruppi che
+    occupano piu' spazio vengono prima). All'interno di ogni gruppo:
+    bitrate DESC, poi size DESC (il primo e' quello "da tenere").
+
+    `method`:
+    - "fingerprint" (default): Chromaprint via fpcalc, preciso ma lento.
+      Cache SQLite persistente. Raggruppa per fingerprint identico.
+    - "filename": similarità Jaccard sui nomi file. Veloce ma euristico.
+      Non richiede fpcalc.
+    """
+    reset_stop()
+    files = _iter_audio_files(directory, recursive)
+    total = len(files)
+    if total == 0:
+        if progress_callback:
+            progress_callback(0, 0, "", "completed")
+        return []
+
+    if method == "filename":
+        return _scan_by_filename(files, progress_callback, group_callback)
+
+    fpcalc = find_fpcalc()
+    if not fpcalc:
+        # Senza fpcalc non possiamo fare nulla. Segnaliamo errore su ogni
+        # file e ritorniamo lista vuota.
+        if progress_callback:
+            progress_callback(0, total, "", "error")
+        return []
+
+    conn = _open_cache()
+    try:
+        # {fingerprint: [entry, ...]}
+        by_fp: dict[str, list[dict]] = {}
+
+        def _pc(idx, total_n, name, status, err=""):
+            """Chiama progress_callback in modo retrocompatibile: la firma
+            legacy è a 4 args, quella nuova a 5 con `error_msg` opzionale."""
+            if not progress_callback:
+                return
+            try:
+                progress_callback(idx, total_n, name, status, err)
+            except TypeError:
+                progress_callback(idx, total_n, name, status)
+
+        for i, fp_path in enumerate(files, start=1):
+            if is_stopped():
+                _pc(i - 1, total, "", "stopped")
+                return []
+            try:
+                st = fp_path.stat()
+                size = st.st_size
+                mtime = st.st_mtime
+            except OSError as e:
+                _pc(i, total, fp_path.name, "error", f"stat: {e}")
+                continue
+
+            path_str = str(fp_path)
+            cached = _cache_get(conn, path_str, size, mtime)
+            if cached:
+                fp_hash = cached["fingerprint"]
+                duration = cached["duration"]
+                bitrate = cached["bitrate"] or get_bitrate(fp_path)
+                _pc(i, total, fp_path.name, "cached")
+            else:
+                _pc(i, total, fp_path.name, "computing")
+                res = compute_fingerprint(fpcalc, path_str)
+                if not res or not res.get("fingerprint"):
+                    err_msg = (res or {}).get("_error", "errore sconosciuto")
+                    _pc(i, total, fp_path.name, "error", err_msg)
+                    continue
+                fp_hash = res["fingerprint"]
+                duration = res["duration"]
+                try:
+                    bitrate = get_bitrate(fp_path)
+                except Exception:
+                    bitrate = 0
+                _cache_put(conn, path_str, size, mtime, duration, fp_hash, bitrate)
+
+            entry = {
+                "path": path_str,
+                "size": int(size),
+                "bitrate": int(bitrate or 0),
+                "duration": float(duration or 0),
+                "fingerprint": fp_hash,
+            }
+            grp = by_fp.setdefault(fp_hash, [])
+            grp.append(entry)
+            # Streaming: appena il gruppo raggiunge (o supera) 2 elementi,
+            # emetti update (JS accumula/aggiorna in tempo reale)
+            if group_callback and len(grp) >= 2:
+                # Ordinamento intra-gruppo prima di emit (best-to-keep primo)
+                grp.sort(key=lambda e: (-int(e.get("bitrate") or 0),
+                                        -int(e.get("size") or 0)))
+                try:
+                    group_callback({
+                        "id": f"fp_{fp_hash[:24]}",
+                        "entries": list(grp),
+                    })
+                except Exception:
+                    pass
+    finally:
+        try:
+            conn.close()
+        except Exception:
+            pass
+
+    # Filtra: solo gruppi con >= 2 file
+    groups = [g for g in by_fp.values() if len(g) >= 2]
+
+    # Sort dei file dentro il gruppo: bitrate DESC, size DESC.
+    # Sort dei gruppi: size del file piu' grande DESC (usa max del gruppo).
+    for g in groups:
+        g.sort(key=lambda e: (-int(e.get("bitrate") or 0),
+                              -int(e.get("size") or 0)))
+    groups.sort(key=lambda g: -max(int(e.get("size") or 0) for e in g))
+
+    if progress_callback:
+        progress_callback(total, total, "", "completed")
+
+    return groups
+
+
+# ------------------------------------------------------------------
+# Trash
+# ------------------------------------------------------------------
+def move_to_trash(paths: list[str]) -> dict:
+    """Sposta i file in cestino tramite send2trash.
+
+    Ritorna {moved: [...], failed: [{path, error}, ...]}. Non solleva
+    mai eccezioni: gli errori per file singolo finiscono in `failed`.
+    Aggiorna la cache SQLite rimuovendo i record dei file spostati (per
+    quelli riusciti), cosi' un re-scan non li propone piu'.
+    """
+    # Import interno per rendere il modulo importabile anche se
+    # send2trash non e' installato (i test possono mockarlo).
+    try:
+        from send2trash import send2trash
+    except Exception as e:  # pragma: no cover — solo se pacchetto mancante
+        return {
+            "moved": [],
+            "failed": [{"path": p, "error": f"send2trash non disponibile: {e}"}
+                       for p in (paths or [])],
+        }
+
+    moved: list[str] = []
+    failed: list[dict] = []
+    for p in (paths or []):
+        try:
+            send2trash(p)
+            moved.append(p)
+        except Exception as e:
+            failed.append({"path": p, "error": str(e)})
+
+    # Cache cleanup best-effort (non fatale se fallisce)
+    if moved:
+        try:
+            conn = _open_cache()
+            try:
+                for p in moved:
+                    conn.execute("DELETE FROM files WHERE path = ?", (p,))
+                conn.commit()
+            finally:
+                conn.close()
+        except Exception:
+            pass
+
+    return {"moved": moved, "failed": failed}

core/downloader.py

@@ -12,6 +12,29 @@ from typing import Callable, Optional
 from core.paths import find_ytdlp, find_ffmpeg_dir, subprocess_flags
 
 
+_ALLOWED_BROWSERS = {"chrome", "safari", "firefox", "edge", "brave", "chromium", "opera", "vivaldi"}
+
+
+def _cookie_args(cookies_path: Optional[str]) -> list:
+    """Ritorna gli argomenti yt-dlp per i cookies.
+
+    Priorità: file cookies_path se esiste → altrimenti --cookies-from-browser
+    <name> se `cookies_browser` è settato in config → altrimenti niente.
+    """
+    if cookies_path and Path(cookies_path).exists():
+        return ["--cookies", cookies_path]
+    # Fallback: legge il browser dalla config al volo (evita di cambiare
+    # firma di tutte le funzioni download_*)
+    try:
+        from core.config import load_config
+        browser = (load_config().get("cookies_browser") or "").strip().lower()
+    except Exception:
+        browser = ""
+    if browser in _ALLOWED_BROWSERS:
+        return ["--cookies-from-browser", browser]
+    return []
+
+
 # Flag globale per interruzione
 _stop_event = threading.Event()
 _current_process: Optional[subprocess.Popen] = None
@@ -99,8 +122,7 @@ def _search_youtube(query: str, cookies_path: Optional[str] = None) -> tuple[str
         "--no-warnings",
         "--flat-playlist",
     ]
-    if cookies_path and Path(cookies_path).exists():
-        cmd.extend(["--cookies", cookies_path])
+    cmd.extend(_cookie_args(cookies_path))
 
     result = subprocess.run(cmd, capture_output=True, text=True, timeout=30, **subprocess_flags())
     if result.returncode != 0:
@@ -216,8 +238,7 @@ def download_playlist(
         ffmpeg_dir = find_ffmpeg_dir()
         if ffmpeg_dir:
             cmd.extend(["--ffmpeg-location", ffmpeg_dir])
-        if cookies_path and Path(cookies_path).exists():
-            cmd.extend(["--cookies", cookies_path])
+        cmd.extend(_cookie_args(cookies_path))
 
         try:
             with _process_lock:
@@ -300,8 +321,7 @@ def download_direct_url(
         "--no-warnings",
         url,
     ]
-    if cookies_path and Path(cookies_path).exists():
-        probe_cmd.extend(["--cookies", cookies_path])
+    probe_cmd.extend(_cookie_args(cookies_path))
 
     try:
         result = subprocess.run(probe_cmd, capture_output=True, text=True, timeout=60, **subprocess_flags())
@@ -375,8 +395,7 @@ def download_direct_url(
         ffmpeg_dir = find_ffmpeg_dir()
         if ffmpeg_dir:
             cmd.extend(["--ffmpeg-location", ffmpeg_dir])
-        if cookies_path and Path(cookies_path).exists():
-            cmd.extend(["--cookies", cookies_path])
+        cmd.extend(_cookie_args(cookies_path))
 
         try:
             with _process_lock:
@@ -511,8 +530,7 @@ def download_urls(
         ffmpeg_dir = find_ffmpeg_dir()
         if ffmpeg_dir:
             cmd.extend(["--ffmpeg-location", ffmpeg_dir])
-        if cookies_path and Path(cookies_path).exists():
-            cmd.extend(["--cookies", cookies_path])
+        cmd.extend(_cookie_args(cookies_path))
 
         try:
             with _process_lock:
@@ -608,8 +626,7 @@ def download_video(
     probe_cmd = [
         ytdlp, "--dump-json", "--flat-playlist", "--no-download", "--no-warnings", url,
     ]
-    if cookies_path and Path(cookies_path).exists():
-        probe_cmd.extend(["--cookies", cookies_path])
+    probe_cmd.extend(_cookie_args(cookies_path))
 
     try:
         result = subprocess.run(probe_cmd, capture_output=True, text=True, timeout=60, **subprocess_flags())
@@ -684,8 +701,7 @@ def download_video(
         ffmpeg_dir = find_ffmpeg_dir()
         if ffmpeg_dir:
             cmd.extend(["--ffmpeg-location", ffmpeg_dir])
-        if cookies_path and Path(cookies_path).exists():
-            cmd.extend(["--cookies", cookies_path])
+        cmd.extend(_cookie_args(cookies_path))
 
         try:
             with _process_lock:

core/flatten.py

@@ -0,0 +1,156 @@
+"""Appiattisce una cartella: sposta tutti i file audio delle sotto-cartelle
+nella cartella padre. Utile come 'undo' di una catalogazione o per unire
+archivi frammentati.
+
+Non tocca i file gia' nella root della cartella padre.
+Conflitti filename: aggiunge suffisso _1, _2... (mai overwrite).
+Opzionalmente rimuove le sotto-cartelle rimaste vuote dopo il move.
+"""
+
+from __future__ import annotations
+
+import shutil
+import threading
+from pathlib import Path
+from typing import Callable, Optional
+
+from core.upgrader import AUDIO_EXTENSIONS
+
+
+_stop_event = threading.Event()
+
+
+def request_stop() -> None:
+    _stop_event.set()
+
+
+def reset_stop() -> None:
+    _stop_event.clear()
+
+
+def is_stopped() -> bool:
+    return _stop_event.is_set()
+
+
+def _iter_audio_in_subfolders(parent: Path) -> list:
+    """Enumera i file audio in TUTTE le sotto-cartelle (ricorsivo) escludendo
+    quelli gia' nella root del `parent`."""
+    if not parent.is_dir():
+        return []
+    files: list = []
+    for f in parent.rglob("*"):
+        if not f.is_file():
+            continue
+        if f.suffix.lower() not in AUDIO_EXTENSIONS:
+            continue
+        if f.parent.resolve() == parent.resolve():
+            continue  # gia' nella root
+        files.append(f)
+    files.sort()
+    return files
+
+
+def _unique_dst(dst: Path) -> Path:
+    """Restituisce un path non-esistente aggiungendo `_1`, `_2`... se serve."""
+    if not dst.exists():
+        return dst
+    stem = dst.stem
+    suffix = dst.suffix
+    i = 1
+    while True:
+        candidate = dst.parent / f"{stem}_{i}{suffix}"
+        if not candidate.exists():
+            return candidate
+        i += 1
+
+
+def _remove_empty_dirs(parent: Path) -> int:
+    """Rimuove ricorsivamente tutte le sotto-cartelle vuote di `parent`.
+    Non tocca `parent` stessa. Ritorna il numero di dir rimosse."""
+    removed = 0
+    for p in sorted(parent.rglob("*"), key=lambda x: len(str(x)), reverse=True):
+        if not p.is_dir():
+            continue
+        if p.resolve() == parent.resolve():
+            continue
+        try:
+            # rimuove .DS_Store residui che impediscono rmdir
+            for junk in p.glob(".DS_Store"):
+                try: junk.unlink()
+                except Exception: pass
+            p.rmdir()
+            removed += 1
+        except OSError:
+            pass  # non vuota o senza permessi
+    return removed
+
+
+def flatten_folder(
+    parent_dir: str,
+    remove_empty: bool = True,
+    progress_callback: Optional[Callable] = None,
+    log_callback: Optional[Callable] = None,
+) -> dict:
+    """Sposta tutti i file audio delle sotto-cartelle in `parent_dir`.
+
+    Args:
+        parent_dir: cartella padre di destinazione
+        remove_empty: se True, elimina le sotto-cartelle rimaste vuote
+        progress_callback: (idx, total, filename, status[, err]) — status:
+            'scanning' | 'moving' | 'skipped' | 'error' | 'stopped' | 'completed'
+        log_callback: chiamato con {src, dst} per ogni move riuscito
+
+    Ritorna:
+        {moved, skipped, failed: [{path, error}], operations: [{src, dst}],
+         dirs_removed}
+    """
+    reset_stop()
+    parent = Path(parent_dir)
+    result = {
+        "moved": 0,
+        "skipped": 0,
+        "failed": [],
+        "operations": [],
+        "dirs_removed": 0,
+    }
+
+    if not parent.is_dir():
+        return result
+
+    files = _iter_audio_in_subfolders(parent)
+    total = len(files)
+
+    def _pc(idx, name, status, err=""):
+        if not progress_callback:
+            return
+        try:
+            progress_callback(idx, total, name, status, err)
+        except TypeError:
+            progress_callback(idx, total, name, status)
+
+    for i, src in enumerate(files, start=1):
+        if is_stopped():
+            _pc(i - 1, "", "stopped")
+            break
+
+        dst = _unique_dst(parent / src.name)
+        try:
+            shutil.move(str(src), str(dst))
+            result["moved"] += 1
+            op = {"src": str(src), "dst": str(dst)}
+            result["operations"].append(op)
+            if log_callback:
+                try:
+                    log_callback(op)
+                except Exception:
+                    pass
+            _pc(i, src.name, "moving")
+        except Exception as e:
+            result["failed"].append({"path": str(src), "error": str(e)})
+            _pc(i, src.name, "error", str(e))
+
+    if remove_empty and not is_stopped():
+        result["dirs_removed"] = _remove_empty_dirs(parent)
+
+    _pc(total, "", "completed")
+    return result

core/paths.py

@@ -45,6 +45,13 @@ def _bundle_dirs() -> list[Path]:
                     sub_macos = frameworks / sub / "Contents" / "MacOS"
                     if sub_macos.exists():
                         dirs.append(sub_macos)
+    else:
+        # Dev: cerca in <project_root>/bundle_bin/ così `python main.py`
+        # usa gli stessi binari del bundle (aggiornati via build_*.py)
+        # invece di Homebrew/PATH che possono essere obsoleti.
+        project_bundle = Path(__file__).resolve().parent.parent / "bundle_bin"
+        if project_bundle.exists():
+            dirs.append(project_bundle)
     return dirs
 
 
@@ -145,3 +152,28 @@ def find_ffmpeg() -> Optional[str]:
 def find_ffprobe() -> Optional[str]:
     """Ritorna il path completo di ffprobe."""
     return _find_binary("ffprobe")
+
+
+def find_fpcalc() -> Optional[str]:
+    """Ritorna il path completo di fpcalc (Chromaprint), o None.
+
+    Cerca nelle stesse directory di find_ffmpeg / find_ytdlp: bundle
+    PyInstaller prima, poi percorsi noti (Homebrew su macOS, LOCALAPPDATA
+    su Windows), infine PATH generico. In dev mode aggiunge anche
+    `<project_root>/bundle_bin/` così l'app funziona con `python main.py`
+    dopo aver scaricato fpcalc via build script.
+
+    `fpcalc` viene usato dal modulo core.dedup per calcolare fingerprint
+    audio (identificazione di duplicati).
+    """
+    found = _find_binary("fpcalc")
+    if found:
+        return found
+    # Fallback dev: bundle_bin del progetto
+    if not _is_frozen():
+        exe_name = _exe("fpcalc")
+        project_bundle = Path(__file__).resolve().parent.parent / "bundle_bin"
+        cand = project_bundle / exe_name
+        if cand.exists():
+            return str(cand)
+    return None

core/traxsource.py

@@ -0,0 +1,277 @@
+"""Fetch Top 100 Traxsource per genere.
+
+Approccio: session curl_cffi (bypass CF via cookie) + BeautifulSoup HTML scraping.
+Spec: docs/superpowers/specs/2026-08-01-traxsource-charts-design.md.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass
+
+
+# Generi musicali Traxsource (slug -> (id, display_name)).
+# Aggiornato via scripts/refresh_traxsource_genres.py. Esclusi "sounds/samples/loops",
+# "acapella", "beats", "efx-dj-tools", "stems" (non generi ma tipi di prodotto).
+GENRES: dict = {
+    "afro-house": (27, "Afro House"),
+    "afro-latin-brazilian": (23, "Afro / Latin / Brazilian"),
+    "broken-beat-nu-jazz": (2, "Broken Beat / Nu Jazz"),
+    "classic-house": (12, "Classic House"),
+    "deep-house": (13, "Deep House"),
+    "drum-and-bass": (31, "Drum & Bass"),
+    "electro-house": (11, "Electro House"),
+    "electronica": (5, "Electronica"),
+    "garage": (29, "Garage"),
+    "house": (4, "House"),
+    "jackin-house": (15, "Jackin House"),
+    "leftfield": (14, "Leftfield"),
+    "lounge-chill-out": (1, "Lounge / Chill Out"),
+    "melodic-progressive-house": (19, "Melodic / Progressive House"),
+    "minimal-deep-tech": (16, "Minimal / Deep Tech"),
+    "nu-disco-indie-dance": (17, "Nu Disco / Indie Dance"),
+    "pop-dance": (32, "Pop Dance"),
+    "r-and-b-hip-hop": (6, "R&B / Hip Hop"),
+    "soul-funk-disco": (3, "Soul / Funk / Disco"),
+    "soulful-house": (24, "Soulful House"),
+    "tech-house": (18, "Tech House"),
+    "techno": (20, "Techno"),
+    "world": (30, "World"),
+}
+
+
+@dataclass(frozen=True)
+class TraxsourceTrack:
+    position: int
+    title: str
+    mix: str
+    artists: str
+    label: str
+    traxsource_id: int
+    slug: str
+    image_url: str = ""
+    cover_url_large: str = ""
+
+
+def list_genres() -> list:
+    result = [
+        {"slug": slug, "id": gid, "name": name}
+        for slug, (gid, name) in GENRES.items()
+    ]
+    result.sort(key=lambda g: g["name"].casefold())
+    return result
+
+
+class TraxsourceError(Exception):
+    """Base per errori Traxsource."""
+
+
+class TraxsourceUnreachableError(TraxsourceError):
+    """Rete / 5xx dopo retry."""
+
+
+class TraxsourceParseError(TraxsourceError):
+    """HTML ricevuto ma non conforme allo schema atteso."""
+
+
+_MIX_PAREN_RE = re.compile(r"^(.*)\s*\(([^()]+)\)\s*$")
+_SIZE_RE = re.compile(r"/\d+x\d+/")
+
+
+def _split_title_mix(full_title: str) -> tuple:
+    """Estrae mix dalle parentesi finali. 'Foo (Extended Mix)' -> ('Foo', 'Extended Mix').
+    Se non ci sono parentesi finali, mix = ''."""
+    if not full_title:
+        return ("", "")
+    m = _MIX_PAREN_RE.match(full_title.strip())
+    if m:
+        return (m.group(1).strip(), m.group(2).strip())
+    return (full_title.strip(), "")
+
+
+def _format_artists(names: list) -> str:
+    """['A', 'B', 'C'] -> 'A, B & C'. Strips whitespace."""
+    clean = [n.strip() for n in names if n and n.strip()]
+    if not clean:
+        return ""
+    if len(clean) == 1:
+        return clean[0]
+    return ", ".join(clean[:-1]) + " & " + clean[-1]
+
+
+def _large_cover(url: str) -> str:
+    """Sostituisce /NxN/ nel path con /500x500/. Se pattern assente, ritorna invariato."""
+    if not url:
+        return ""
+    return _SIZE_RE.sub("/500x500/", url)
+
+
+_TOP100_LINK_RE = re.compile(r'href="(/title/\d+/top-100-[a-z0-9-]+)"')
+
+
+def _discover_top100_url(genre_html: str) -> str:
+    """Estrae il path relativo della playlist Top 100 corrente dalla pagina di un genere."""
+    m = _TOP100_LINK_RE.search(genre_html)
+    if not m:
+        raise TraxsourceParseError("link Top 100 non trovato nella pagina genere")
+    return m.group(1)
+
+
+def _parse_tracks(html: str) -> list:
+    """Parsa la pagina Top 100 (title playlist) e ritorna list[TraxsourceTrack].
+
+    Selettori (verificati su fixture tech-house 2026-07):
+      row       = div.trk-row.play-trk (data-trid=<int>)
+      position  = div.tnum (inside div.tnum-pos)
+      title <a> = div.trk-cell.title a[href^="/track/"]
+      version   = span.version (contiene child span.duration da rimuovere)
+      artists   = a.com-artists (uno o piu)
+      label <a> = div.trk-cell.label a
+      cover img = div.trk-cell.thumb img (src /scripts/image.php/52x52/...)
+    """
+    # Lazy import — bs4 non e' hard-dep del modulo (importato solo quando serve).
+    from bs4 import BeautifulSoup
+
+    soup = BeautifulSoup(html, "html.parser")
+    rows = soup.select("div.trk-row.play-trk")
+    if not rows:
+        raise TraxsourceParseError("nessuna track (div.trk-row.play-trk) trovata")
+
+    out: list = []
+    for i, row in enumerate(rows, 1):
+        try:
+            trid = int(row.get("data-trid") or 0)
+
+            pos_el = row.select_one("div.tnum")
+            position = i  # fallback su enumerate se pos manca / non e' un numero
+            if pos_el:
+                pos_txt = pos_el.get_text(strip=True)
+                if pos_txt.isdigit():
+                    position = int(pos_txt)
+
+            title_a = row.select_one('div.trk-cell.title a[href^="/track/"]')
+            if not title_a:
+                continue
+            title = title_a.get_text(strip=True)
+            href = title_a.get("href") or ""
+            slug = href.rsplit("/", 1)[-1]
+
+            # Mix version: contenuto di span.version, escluso span.duration
+            mix = ""
+            version_el = row.select_one("span.version")
+            if version_el:
+                dur_el = version_el.select_one("span.duration")
+                if dur_el:
+                    dur_el.extract()
+                mix = version_el.get_text(strip=True)
+
+            artist_names = [a.get_text(strip=True) for a in row.select("a.com-artists")]
+            artists = _format_artists(artist_names)
+
+            label_a = row.select_one("div.trk-cell.label a")
+            label = label_a.get_text(strip=True) if label_a else ""
+
+            img = row.select_one('div.trk-cell.thumb img[src*="/scripts/image.php/"]')
+            image_url = (img.get("src") or "") if img else ""
+            cover_large = _large_cover(image_url)
+
+            out.append(TraxsourceTrack(
+                position=position,
+                title=title,
+                mix=mix,
+                artists=artists,
+                label=label,
+                traxsource_id=trid,
+                slug=slug,
+                image_url=image_url,
+                cover_url_large=cover_large,
+            ))
+        except Exception as e:
+            raise TraxsourceParseError(f"errore parse track[{i}]: {e}") from e
+    return out
+
+
+# --- fetch_top100 con session curl_cffi + retry + cache ------------------
+
+_IMPERSONATE = "chrome131"
+_REQUEST_TIMEOUT = 15
+_MAX_ATTEMPTS = 3
+_BACKOFF_SEC = [1, 3]
+_CACHE_TTL_SEC = 15 * 60
+
+_cache: dict = {}
+_session_singleton = None
+
+
+def _session():
+    """Ritorna la Session curl_cffi singleton, preriscaldata con GET a /."""
+    global _session_singleton
+    if _session_singleton is None:
+        from curl_cffi import requests as _cffi
+        _session_singleton = _cffi.Session(impersonate=_IMPERSONATE)
+        try:
+            _session_singleton.get("https://www.traxsource.com/", timeout=_REQUEST_TIMEOUT)
+        except Exception:
+            pass  # cookie CF possono arrivare comunque
+    return _session_singleton
+
+
+def _do_get(session, url: str) -> str:
+    """GET con retry + backoff. Include Referer per pagine interne."""
+    last_exc = None
+    for attempt in range(_MAX_ATTEMPTS):
+        try:
+            resp = session.get(
+                url,
+                timeout=_REQUEST_TIMEOUT,
+                headers={"Referer": "https://www.traxsource.com/"},
+            )
+            if resp.status_code >= 500 or resp.status_code == 403:
+                raise Exception(f"HTTP {resp.status_code}")
+            resp.raise_for_status()
+            return resp.text
+        except Exception as e:
+            last_exc = e
+            if attempt < _MAX_ATTEMPTS - 1:
+                time.sleep(_BACKOFF_SEC[attempt])
+    raise TraxsourceUnreachableError(
+        f"Traxsource irraggiungibile dopo {_MAX_ATTEMPTS} tentativi: {last_exc}"
+    )
+
+
+def fetch_top100(slug: str, force_refresh: bool = False) -> list:
+    """Fetches Top 100 corrente per il genere.
+
+    1. Verifica slug in GENRES
+    2. Fetch pagina genre -> _discover_top100_url
+    3. Fetch pagina Top 100 -> _parse_tracks
+    4. Cache 15 min
+
+    Raises:
+        ValueError: slug non in GENRES
+        TraxsourceUnreachableError: rete/5xx dopo retry
+        TraxsourceParseError: HTML non conforme
+    """
+    if slug not in GENRES:
+        raise ValueError(f"slug genere non valido: {slug!r}")
+
+    now = time.time()
+    if not force_refresh:
+        cached = _cache.get(slug)
+        if cached and (now - cached[0]) < _CACHE_TTL_SEC:
+            return cached[1]
+
+    gid, _name = GENRES[slug]
+    sess = _session()
+
+    genre_url = f"https://www.traxsource.com/genre/{gid}/{slug}"
+    genre_html = _do_get(sess, genre_url)
+    top100_path = _discover_top100_url(genre_html)
+
+    top100_url = "https://www.traxsource.com" + top100_path
+    top100_html = _do_get(sess, top100_url)
+    tracks = _parse_tracks(top100_html)
+
+    _cache[slug] = (now, tracks)
+    return tracks

core/upgrader.py

@@ -3,16 +3,28 @@
 from __future__ import annotations
 
 import json
+import queue
 import re
+import shutil
 import subprocess
 import threading
 from pathlib import Path
 from typing import Callable, Optional
 
-from core.paths import find_ytdlp, find_ffmpeg_dir, find_ffprobe, subprocess_flags
+from core.paths import find_ytdlp, find_ffmpeg_dir, find_ffmpeg, find_ffprobe, subprocess_flags
 
 AUDIO_EXTENSIONS = {".mp3", ".m4a", ".wav", ".flac"}
 
+# Soglia minima Jaccard per considerare un file dell'archivio come candidato.
+_ARCHIVE_MIN_SIMILARITY = 0.5
+
+# Token di lunghezza inferiore a questa vengono scartati (troppo generici).
+_MIN_TOKEN_LEN = 3
+
+# Timeout massimo per singolo download yt-dlp (secondi). Watchdog kill.
+# Serve a evitare hang su video geo-restricted, YouTube throttle o rete lenta.
+_DOWNLOAD_TIMEOUT_SEC = 300
+
 # Flag globale per interruzione
 _stop_event = threading.Event()
 _current_process: Optional[subprocess.Popen] = None
@@ -70,6 +82,143 @@ def get_bitrate(filepath: str | Path) -> int:
         return 0
 
 
+def _normalize_stem(stem: str) -> set:
+    """Ritorna il set di token normalizzati per un nome file (senza extension).
+
+    Pipeline:
+      1. Lowercase
+      2. Sostituisce caratteri non alfanumerici con spazi (mantiene split naturale)
+      3. Split su whitespace
+      4. Filtra token di lunghezza < _MIN_TOKEN_LEN (troppo generici)
+    """
+    if not stem:
+        return set()
+    lowered = stem.lower()
+    # Manteniamo spazi ma sostituiamo tutto il resto (che non è alfanumerico) con spazi
+    cleaned = re.sub(r"[^a-z0-9\s]+", " ", lowered)
+    tokens = cleaned.split()
+    return {t for t in tokens if len(t) >= _MIN_TOKEN_LEN}
+
+
+def _tokens_to_key(tokens: set) -> str:
+    """Chiave stabile per un set di token (usata come chiave del dict d'indice)."""
+    return "|".join(sorted(tokens))
+
+
+def _key_to_tokens(key: str) -> set:
+    """Inverso di _tokens_to_key."""
+    if not key:
+        return set()
+    return set(key.split("|"))
+
+
+def _scan_archive(archive_dir: str) -> dict:
+    """Indicizza recursivamente un archivio di file audio.
+
+    Ritorna dict {token_key: [Path, ...]}. La scansione è case-insensitive
+    sulle estensioni: `.MP3`, `.Mp3`, `.mp3` sono tutti riconosciuti.
+    """
+    base = Path(archive_dir)
+    index: dict = {}
+    if not base.exists() or not base.is_dir():
+        return index
+    for f in base.rglob("*"):
+        if not f.is_file():
+            continue
+        if f.suffix.lower() not in AUDIO_EXTENSIONS:
+            continue
+        tokens = _normalize_stem(f.stem)
+        if not tokens:
+            continue
+        key = _tokens_to_key(tokens)
+        index.setdefault(key, []).append(f)
+    return index
+
+
+def _find_candidates(
+    target_stem: str,
+    index: dict,
+    min_similarity: float = _ARCHIVE_MIN_SIMILARITY,
+) -> list:
+    """Cerca candidati nell'indice tramite Jaccard sui token del nome.
+
+    Ritorna lista di tuple `(path, similarity, bitrate)` ordinata per
+    bitrate DESC, poi similarity DESC.
+    """
+    target_tokens = _normalize_stem(target_stem)
+    if not target_tokens:
+        return []
+
+    results: list = []
+    for key, paths in index.items():
+        entry_tokens = _key_to_tokens(key)
+        if not entry_tokens:
+            continue
+        common = len(target_tokens & entry_tokens)
+        if common == 0:
+            continue
+        total = len(target_tokens | entry_tokens)
+        if total == 0:
+            continue
+        sim = common / total
+        if sim < min_similarity:
+            continue
+        for p in paths:
+            try:
+                br = get_bitrate(p)
+            except Exception:
+                br = 0
+            results.append((p, sim, br))
+
+    # Ordina: bitrate DESC, poi similarity DESC (stabile)
+    results.sort(key=lambda t: (-t[2], -t[1]))
+    return results
+
+
+def _copy_or_convert_to_mp3(
+    src: Path,
+    dst: Path,
+    temp_dir: Path,
+) -> bool:
+    """Copia (o converte se necessario) `src` in `dst` come MP3.
+
+    - Se src è già .mp3 → copia diretta con shutil.copy2
+    - Altrimenti → converti con ffmpeg a 320k CBR
+    Ritorna True in caso di successo.
+    """
+    try:
+        if src.suffix.lower() == ".mp3":
+            # shutil.copy (non copy2): mtime del target = ora, non quello
+            # del sorgente. Così è chiaro nel Finder che il file è stato
+            # aggiornato dall'upgrade.
+            shutil.copy(str(src), str(dst))
+            return dst.exists()
+        # Convert non-mp3 -> mp3 320k
+        ffmpeg_bin = find_ffmpeg() or "ffmpeg"
+        temp_out = temp_dir / f"_archive_convert_{dst.stem}.mp3"
+        # -y per sovrascrivere se residuo di run precedente
+        subprocess.run(
+            [
+                ffmpeg_bin, "-y",
+                "-i", str(src),
+                "-vn",  # scarta eventuali stream video/cover art (le riproviamo dopo)
+                "-c:a", "libmp3lame",
+                "-b:a", "320k",
+                "-id3v2_version", "3",
+                str(temp_out),
+            ],
+            capture_output=True,
+            timeout=300,
+            **subprocess_flags(),
+        )
+        if not temp_out.exists():
+            return False
+        temp_out.replace(dst)
+        return True
+    except Exception:
+        return False
+
+
 def _load_done_set(done_file: Path) -> set[str]:
     if done_file.exists():
         return set(done_file.read_text(encoding="utf-8").splitlines())
@@ -123,7 +272,7 @@ def update_cover_only(
         "--output", str(temp_dir / "cover"),
         video_url,
     ]
-    ffmpeg_dir = _find_ffmpeg_dir()
+    ffmpeg_dir = find_ffmpeg_dir()
     if ffmpeg_dir:
         cmd.extend(["--ffmpeg-location", ffmpeg_dir])
     if cookies_path and Path(cookies_path).exists():
@@ -180,8 +329,21 @@ def upgrade_folder(
     cookies_path: Optional[str] = None,
     recursive: bool = False,
     progress_callback: Optional[Callable] = None,
+    archive_dir: Optional[str] = None,
+    resolve_callback: Optional[Callable] = None,
 ) -> None:
-    """Logica principale di upgrade qualita."""
+    """Logica principale di upgrade qualita.
+
+    Args:
+        archive_dir: se presente, prima di scaricare da YouTube l'app cerca
+            una versione HQ del brano in questa cartella (recursive). Se ne
+            trova una la copia (o converte in mp3 320k) mantenendo il nome
+            originale.
+        resolve_callback: chiamato in caso di match multiplo nell'archivio.
+            Riceve una lista di dict {path, bitrate, size, similarity} e deve
+            ritornare bloccante un dict {'action': 'use_local'|'use_youtube'|
+            'skip', 'path': Optional[str]}.
+    """
     reset_stop()
     ytdlp = find_ytdlp()
 
@@ -195,7 +357,7 @@ def upgrade_folder(
     else:
         folders = [Path(directory)]
 
-    all_items: list[tuple[Path, Path]] = []
+    all_items: list = []
     for folder in folders:
         for ext in AUDIO_EXTENSIONS:
             for f in sorted(folder.glob(f"*{ext}")):
@@ -207,6 +369,16 @@ def upgrade_folder(
             progress_callback(0, 0, "", "no_files", 0, 0)
         return
 
+    # Pre-scan dell'archivio (una volta sola). Se archive_dir è None si salta.
+    archive_index: dict = {}
+    if archive_dir:
+        try:
+            archive_index = _scan_archive(archive_dir)
+        except Exception:
+            archive_index = {}
+        if progress_callback:
+            progress_callback(0, total, "", "scan_archive", 0, len(archive_index))
+
     processed = 0
 
     for filepath, folder in all_items:
@@ -230,6 +402,95 @@ def upgrade_folder(
 
         current_kbps = get_bitrate(filepath)
 
+        # ------------------------------------------------------------------
+        # 1) ARCHIVE LOOKUP (se archive_dir presente)
+        # ------------------------------------------------------------------
+        if archive_index:
+            try:
+                candidates = _find_candidates(filename, archive_index)
+            except Exception:
+                candidates = []
+
+            selected_path: Optional[Path] = None
+            user_chose_youtube = False
+            user_chose_skip = False
+
+            if len(candidates) == 1:
+                selected_path = candidates[0][0]
+            elif len(candidates) >= 2 and resolve_callback is not None:
+                cand_payload = []
+                for cp, csim, cbr in candidates:
+                    try:
+                        csize = cp.stat().st_size
+                    except Exception:
+                        csize = 0
+                    cand_payload.append({
+                        "path": str(cp),
+                        "bitrate": cbr,
+                        "size": csize,
+                        "similarity": csim,
+                    })
+                if progress_callback:
+                    progress_callback(processed, total, filepath.name,
+                                      "resolve_wait", current_kbps, 0)
+                try:
+                    choice = resolve_callback(str(filepath), cand_payload) or {}
+                except Exception:
+                    choice = {}
+                action = (choice.get("action") or "").strip()
+                if action == "use_local":
+                    chosen = (choice.get("path") or "").strip()
+                    if chosen:
+                        cp = Path(chosen)
+                        if cp.exists():
+                            selected_path = cp
+                elif action == "use_youtube":
+                    user_chose_youtube = True
+                elif action == "skip":
+                    user_chose_skip = True
+                else:
+                    # Risposta invalida: fallback su YouTube per non bloccare
+                    user_chose_youtube = True
+            # len(candidates) >= 2 senza callback: fallback YouTube
+            # len(candidates) == 0: fallback YouTube
+
+            if user_chose_skip:
+                _mark_done(done_file, filename)
+                processed += 1
+                if progress_callback:
+                    progress_callback(processed, total, filepath.name,
+                                      "skipped_by_user", current_kbps, 0)
+                continue
+
+            if selected_path is not None and not user_chose_youtube:
+                # Copia/converte il candidato locale come .mp3 con nome originale
+                dst = filepath.parent / f"{filename}.mp3"
+                if progress_callback:
+                    progress_callback(processed, total, filepath.name,
+                                      "local_copy", current_kbps, 0)
+                # Rimuovi originale solo se ha estensione diversa (altrimenti
+                # verrà sovrascritto dalla copia)
+                try:
+                    if filepath.exists() and filepath.resolve() != dst.resolve():
+                        filepath.unlink()
+                except Exception:
+                    pass
+                ok = _copy_or_convert_to_mp3(selected_path, dst, temp_dir)
+                if ok:
+                    new_kbps = get_bitrate(dst)
+                    _mark_done(done_file, filename)
+                    _cleanup_temp(temp_dir)
+                    processed += 1
+                    if progress_callback:
+                        progress_callback(processed, total, filepath.name,
+                                          "local_upgraded", current_kbps, new_kbps)
+                    continue
+                # Copia fallita: fallback YouTube (non marchiamo done)
+                _cleanup_temp(temp_dir)
+
+        # ------------------------------------------------------------------
+        # 2) YOUTUBE FALLBACK (comportamento originale)
+        # ------------------------------------------------------------------
         if progress_callback:
             progress_callback(processed, total, filepath.name, "searching", current_kbps, 0)
 
@@ -288,17 +549,79 @@ def upgrade_folder(
                     cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
                     **subprocess_flags(),
                 )
+            proc = _current_process
 
-            for line in _current_process.stdout:
-                if is_stopped():
-                    _current_process.terminate()
-                    return
-                pct_match = re.search(r"(\d+(?:\.\d+)?)%", line)
-                if pct_match and progress_callback:
-                    pct = int(float(pct_match.group(1)))
-                    progress_callback(processed, total, filepath.name, "downloading", current_kbps, pct)
+            # Watchdog: kill del subprocess se supera _DOWNLOAD_TIMEOUT_SEC.
+            # Previene hang indefinito su video problematici (geo-block,
+            # YouTube throttle, rete lenta).
+            def _watchdog_kill():
+                try:
+                    if proc.poll() is None:
+                        proc.kill()  # SIGKILL — SIGTERM può lasciare ffmpeg orfano che tiene aperto il pipe
+                except Exception:
+                    pass
+            watchdog = threading.Timer(_DOWNLOAD_TIMEOUT_SEC, _watchdog_kill)
+            watchdog.daemon = True
+            watchdog.start()
+
+            # Lettore stdout in thread separato + queue: il main loop polla
+            # con timeout invece di bloccare su `for line in proc.stdout`.
+            # Cosi is_stopped() e proc.poll() vengono controllati periodicamente
+            # -> il bottone Stop risponde in <1s anche se il subprocess ha
+            # figli orfani (ffmpeg) che tengono aperto il pipe.
+            output_q: queue.Queue = queue.Queue()
+
+            def _reader():
+                try:
+                    for line in proc.stdout:
+                        output_q.put(line)
+                except Exception:
+                    pass
+                finally:
+                    output_q.put(None)  # sentinel: pipe closed
+
+            reader = threading.Thread(target=_reader, daemon=True)
+            reader.start()
+
+            try:
+                while True:
+                    if is_stopped():
+                        try:
+                            proc.kill()
+                        except Exception:
+                            pass
+                        return
+                    try:
+                        line = output_q.get(timeout=0.5)
+                    except queue.Empty:
+                        # Se il subprocess e' morto e il pipe non produce piu' output
+                        # (child orfano), esci comunque.
+                        if proc.poll() is not None and output_q.empty():
+                            # Aspetta ancora un attimo per drenare
+                            try:
+                                line = output_q.get(timeout=1.0)
+                            except queue.Empty:
+                                break
+                        else:
+                            continue
+                    if line is None:
+                        break
+                    pct_match = re.search(r"(\d+(?:\.\d+)?)%", line)
+                    if pct_match and progress_callback:
+                        pct = int(float(pct_match.group(1)))
+                        progress_callback(processed, total, filepath.name, "downloading", current_kbps, pct)
+
+                try:
+                    proc.wait(timeout=10)
+                except subprocess.TimeoutExpired:
+                    try:
+                        proc.kill()
+                        proc.wait(timeout=5)
+                    except Exception:
+                        pass
+            finally:
+                watchdog.cancel()
 
-            _current_process.wait()
             with _process_lock:
                 _current_process = None
 

core/youtube_search.py

@@ -63,6 +63,14 @@ def search_youtube(query: str, limit: int = 50) -> list:
         video_id = e.get("id") or ""
         url = e.get("url") or (f"https://www.youtube.com/watch?v={video_id}" if video_id else "")
         image_url = f"https://i.ytimg.com/vi/{video_id}/mqdefault.jpg" if video_id else ""
+        # yt-dlp `upload_date` è YYYYMMDD (stringa). Lo converto in ISO YYYY-MM-DD.
+        # Con --flat-playlist può essere assente; in tal caso resta stringa vuota.
+        raw_date = str(e.get("upload_date") or "").strip()
+        release_date = ""
+        if len(raw_date) == 8 and raw_date.isdigit():
+            release_date = f"{raw_date[0:4]}-{raw_date[4:6]}-{raw_date[6:8]}"
+        elif raw_date:
+            release_date = raw_date  # forma sconosciuta, passa così
         result.append({
             "id": video_id,
             "url": url,
@@ -70,5 +78,6 @@ def search_youtube(query: str, limit: int = 50) -> list:
             "channel": e.get("uploader") or e.get("channel") or "",
             "duration_sec": int(e.get("duration") or 0),
             "image_url": image_url,
+            "release_date": release_date,
         })
     return result

docs/superpowers/specs/2026-08-01-traxsource-charts-design.md

@@ -0,0 +1,256 @@
+# Traxsource Charts — Design Spec
+
+- **Data:** 2026-08-01
+- **Autore:** LuZa + Claude
+- **Stato:** Approvato, pronto per implementation plan
+- **Target release:** MusicTools v1.9.0
+
+## Obiettivo
+
+Nuova tab "▲ Traxsource" nell'app che permette di:
+
+1. Scegliere un genere musicale da un elenco di ~15 generi Traxsource
+2. Caricare la **Top 100** ufficiale del mese corrente per quel genere
+3. Anteprima checkbox + download riusando il pipeline esistente (Spotify search → yt-dlp → tag ID3 + cover)
+
+Sostituisce l'attività manuale di copiare/incollare tracklist Traxsource.
+
+## Non-goals
+
+- Chart diverse dalla Top 100 (Must Have, Just Added, ecc.)
+- Ricerca artista/label specifica su Traxsource
+- Preview audio (Traxsource ha DRM)
+- Duration tracks (non è nell'HTML della lista; sarebbe una richiesta extra per track)
+- Login/account Traxsource
+
+## Ricognizione tecnica (fatta 2026-08-01)
+
+- **Cloudflare Managed Challenge attivo** su tutte le pagine tranne home e /top. Bypass: session-based con `curl_cffi.Session(impersonate='chrome131')`, prima GET a `/`, poi le pagine sensibili con `Referer: https://www.traxsource.com/`.
+- **Non è Next.js** → no `__NEXT_DATA__`. HTML server-rendered.
+- **Struttura URL:**
+  - Genre index: `/genre/<id>/<slug>` — es. `/genre/18/tech-house`. Contiene solo 10 top track più altri widget
+  - Top 100 corrente: `/title/<title_id>/top-100-<genre>-of-<month>-<year>` — es. `/title/2847986/top-100-tech-house-of-july-2026`. Contiene 100 track completi in un unico documento (~394KB)
+  - **Il title_id cambia ogni mese.** Non è hardcodabile. Va scoperto dinamicamente
+- **Discovery Top 100 URL:** nella pagina `/genre/<id>/<slug>` c'è (almeno un) `<a href="/title/<id>/top-100-<slug>-of-<month>-<year>">`. Estrai col regex `href="(/title/\d+/top-100-[a-z0-9-]+)"`
+- **Track markup (stabile):**
+  ```html
+  <div data-trid="14842066" class="top-item play-trk ptk-14842066">
+    <div class="ttib position">1</div>
+    <div class="image"><img src="https://.../52x52/HASH.jpg" /></div>
+    <div class="ttib info">
+      <a href="/track/14842066/badman-sound-extended-mix" class="com-title">Badman Sound (Extended Mix)</a>
+      <a href="/artist/92248/hannah-wants" class="com-artists">Hannah Wants</a>,
+      <a href="/artist/321517/trace" class="com-artists">Trace</a>
+      <a href="/label/325/nervous" class="com-label">Nervous</a>
+    </div>
+  </div>
+  ```
+  Class names sono stabili (semantici, non generati da bundler).
+- **Cover art:** URL contiene la size (`/52x52/`). Sostituendo con `/500x500/` si ottiene la versione grande per tagging ID3.
+
+## Approccio scelto
+
+- Session `curl_cffi` con `impersonate='chrome131'`. Cookie CF conservati automaticamente. Preriscaldamento con GET a `/` al primo utilizzo.
+- Parser: `BeautifulSoup4` con selettori CSS puliti — `div.top-item.play-trk` per righe, `a.com-title` per titolo, `a.com-artists` per artisti, `a.com-label` per label, `div.ttib.position` per rank, `img` per cover URL.
+- Regex sul titolo per estrarre "mix name" tra parentesi: `Song Title (Extended Mix)` → title="Song Title", mix="Extended Mix".
+- Cache in-memory 15 min per la lista, come Beatport.
+- Genere → (numeric_id, slug, display_name) map hardcoded (estratti dalla home /top).
+
+**Alternative scartate:**
+- `requests` puro: bloccato da CF, verificato
+- API interna Traxsource: non esistono API pubbliche gratuite documentate; reverse engineering rischio ban
+- Playwright: overkill (~100MB dep) quando session + BeautifulSoup basta
+
+## Architettura
+
+### Nuovo modulo `core/traxsource.py`
+
+```python
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+# Mappa slug → (numeric_id, display_name)
+# Verificati 2026-08-01 dalla home /top di Traxsource
+GENRES: dict = {
+    "afro-house": (33, "Afro House"),
+    "afro-latin-brazilian": (23, "Afro / Latin / Brazilian"),
+    "amapiano": (37, "Amapiano"),
+    "bass-club": (25, "Bass / Club"),
+    "breaks-uk-bass": (14, "Breaks / UK Bass"),
+    "classic-house": (12, "Classic House"),
+    "deep-house": (13, "Deep House"),
+    "dj-tools": (16, "DJ Tools"),
+    "downtempo-nu-disco-indie-dance": (22, "Downtempo / Nu Disco / Indie Dance"),
+    "electronica": (5, "Electronica"),
+    "electro-house": (11, "Electro House"),
+    "funky-jackin-groovy": (15, "Funky / Jackin / Groovy"),
+    "garage": (29, "Garage"),
+    "house": (1, "House"),
+    "lounge-chill-out": (10, "Lounge / Chill Out"),
+    "melodic-house-techno-progressive-house": (34, "Melodic House / Techno / Progressive House"),
+    "minimal-deep-tech": (27, "Minimal / Deep Tech"),
+    "organic-house-downtempo": (36, "Organic House / Downtempo"),
+    "progressive-house": (28, "Progressive House"),
+    "r-and-b-hip-hop": (6, "R&B / Hip Hop"),
+    "soulful-house": (24, "Soulful House"),
+    "tech-house": (18, "Tech House"),
+    "techno-peak-time-driving": (26, "Techno (Peak Time / Driving)"),
+    "techno-raw-deep-hypnotic": (32, "Techno (Raw / Deep / Hypnotic)"),
+    "trance": (30, "Trance"),
+    "world-reggae": (21, "World / Reggae"),
+}
+# NOTA: la mappa è enumerata in fase di implementazione fetchando /top con curl_cffi
+# e cercando href="/genre/<id>/<slug>". Vedi Task 1 del plan.
+
+
+@dataclass(frozen=True)
+class TraxsourceTrack:
+    position: int
+    title: str
+    mix: str
+    artists: str        # "A, B & C" formattato
+    label: str
+    traxsource_id: int
+    slug: str
+    image_url: str = ""    # URL thumbnail (per UI)
+    cover_url_large: str = ""  # URL cover 500x500 (per tagging)
+
+
+class TraxsourceError(Exception): pass
+class TraxsourceUnreachableError(TraxsourceError): pass
+class TraxsourceParseError(TraxsourceError): pass
+
+
+def list_genres() -> list:
+    """Ritorna [{slug, id, name}, ...] ordinato alfabeticamente per name."""
+
+
+def fetch_top100(slug: str, force_refresh: bool = False) -> list[TraxsourceTrack]:
+    """Fetches Top 100 corrente per il genere.
+
+    1. Scopre l'URL della playlist Top 100 del mese via GET /genre/<id>/<slug>
+    2. Fetch della playlist /title/<id>/top-100-...
+    3. Parse HTML con BeautifulSoup
+    4. Cache in-memory 15 min
+
+    Raises:
+        ValueError se slug non in GENRES
+        TraxsourceUnreachableError su rete/5xx dopo retry
+        TraxsourceParseError su HTML non conforme (title link non trovato, meno di 50 track, ecc.)
+    """
+```
+
+**Internals:**
+- `_session()` singleton — inizializza `curl_cffi.Session(impersonate='chrome131')` e fa GET a `/` una volta per riscaldare CF cookies. Riusata per tutte le fetch successive.
+- `_discover_top100_url(session, slug) → str` — fetcha `/genre/<id>/<slug>`, regex per il link Top 100
+- `_parse_tracks(html) → list[TraxsourceTrack]` — BeautifulSoup, itera `div.top-item.play-trk`, estrae campi
+- `_split_title_mix(full_title) → (title, mix)` — parsa `"Foo (Extended Mix)"` → `("Foo", "Extended Mix")`. Se no parentesi, mix = "".
+- `_format_artists(anchors) → str` — join `[a.text for a in anchors]` con formattazione "A, B & C"
+- `_large_cover(url) → str` — sostituisce `/52x52/` con `/500x500/` nel path
+
+**Retry + timeout:** riusa gli stessi pattern di `core/beatport.py`: 3 tentativi con backoff [1, 3]s, timeout 15s.
+
+### Nuovi metodi in `api/bridge.py`
+
+Paralleli ai metodi Beatport (stesso schema):
+
+- `traxsource_genres() → list[dict]`
+- `traxsource_fetch_chart(slug, force_refresh) → {ok, tracks} | {ok:false, error, message}` — salva anche `traxsource_last_genre` in config
+- `traxsource_check_existing(tracks, genre_name) → list[bool]` — check in `<output_dir>/Traxsource_<genre>/`
+- `traxsource_download_selected(tracks, genre_name) → dict` — costruisce metadata (title/artist/album=label/date=YYYY-MM/genre=display_name/cover_url) e chiama `start_tracks_download` riusando il pipeline con tagging ID3
+
+**Metadata per il tagger:**
+- title, artist: dai campi track
+- album: label Traxsource (best proxy — non c'è "album" per singole tracce)
+- date: mese/anno corrente (dato che la Top 100 è mensile)
+- genre: display_name del genere
+- cover_url: `cover_url_large` (500x500)
+
+### Frontend
+
+Nuova tab in sidebar dopo YouTube (o Beatport):
+```html
+<button class="nav-item" data-view="traxsource" data-feature="audio">
+  <span class="nav-icon">▲</span><span>Traxsource</span>
+</button>
+```
+
+Section `#view-traxsource` con struttura identica a Beatport (dropdown genere + Carica Top 100 + tabella + toolbar + log). Riusa tutte le classi `.beatport-*` per lo stile.
+
+Modulo `TraxsourceUI` in `webui/js/app.js` — copia diretta di `BeatportUI` con selettori cambiati (`traxsource-*` invece di `beatport-*`) e chiamate API alle nuove funzioni.
+
+**Ordinamento colonne** (sortable) e **cover art** già supportati riusando la stessa struttura tabella + modulo helper `_sortPairs`/`_bindSortableHeaders`/`_updateSortArrows` esistenti.
+
+### Persistenza
+
+Nuovo campo in `core/config.py::DEFAULTS`:
+```python
+"traxsource_last_genre": "tech-house",
+```
+
+### Dipendenze
+
+- `beautifulsoup4` — nuova dep runtime. Aggiungere in `requirements.txt`. Serve `--collect-data bs4` in build_windows.py + build_macos.py? Verificare — bs4 di solito no.
+
+## Testing
+
+**Unit tests `tests/test_traxsource.py` (senza rete, con fixture HTML):**
+
+Serve una fixture HTML reale della pagina Top 100 (~400KB). Task 1 la genera con `curl_cffi` come fatto per Beatport (`beatport_melodic_top100.html`).
+
+| Test | Verifica |
+|---|---|
+| `test_list_genres_shape` | Lista dict con {slug, id, name}, ordinati |
+| `test_parse_top100_extracts_100_tracks` | Fixture HTML → 100 track |
+| `test_parse_positions_sequential` | 1..100 senza buchi |
+| `test_parse_track_shape` | Ogni track ha title, artists, label, cover URLs non vuoti |
+| `test_split_title_mix_with_parens` | `"Foo (Extended Mix)"` → `("Foo", "Extended Mix")` |
+| `test_split_title_mix_no_parens` | `"Foo"` → `("Foo", "")` |
+| `test_format_artists_multi` | `["A", "B", "C"]` → `"A, B & C"` |
+| `test_large_cover_url_substitution` | `.../52x52/x.jpg` → `.../500x500/x.jpg` |
+| `test_discover_top100_url_returns_playlist_link` | HTML genre stub → estrae `/title/N/top-100-...` |
+| `test_fetch_top100_invalid_slug_raises_value_error` | slug non in GENRES → ValueError early |
+
+Mock HTTP con `unittest.mock.patch("core.traxsource._session")` (patch della session singleton).
+
+**Test manuale end-to-end:**
+1. Avvia app → tab Traxsource
+2. Selezione "Tech House" → Carica Top 100 → tabella 100 righe in <5s
+3. Verifica cover art (thumbnail nella tabella)
+4. Deseleziona 90, tieni 10 → Scarica selezionati
+5. File in `MUSICA/Traxsource_Tech House/` con tag ID3 completi (title, artist, album=label, genre=Tech House, cover 500x500)
+6. Ricarica stesso genere → cache hit
+7. Riavvio → ultimo genere ricordato
+
+## Rollout
+
+1. Branch `feat/traxsource-charts`
+2. Bump `core/config.py::VERSION` → `v1.9.0` (minor: nuova tab visibile)
+3. Note release `/tmp/notes-v1.9.0.md`
+4. Merge → tag → CI → server DB update (stesso flusso di sempre)
+
+## Struttura file impattati
+
+**Nuovi:**
+- `core/traxsource.py` (~250 LOC)
+- `tests/test_traxsource.py` (~200 LOC)
+- `tests/fixtures/traxsource_tech_house_top100.html` (~400KB)
+- `scripts/refresh_traxsource_genres.py` (~50 LOC, opzionale)
+
+**Modificati:**
+- `requirements.txt` — `beautifulsoup4>=4.12.0`
+- `build_windows.py` + `build_macos.py` — verificare se serve `--collect-data bs4`
+- `core/config.py` — VERSION bump + `traxsource_last_genre`
+- `api/bridge.py` — 4 metodi Api `traxsource_*` (~150 LOC)
+- `webui/index.html` — nav-item + section (~90 LOC)
+- `webui/js/app.js` — modulo `TraxsourceUI` (~250 LOC, copia BeatportUI adattata)
+
+## Considerazioni operative
+
+- **Fragility scraping:** i class name di Traxsource (`com-title`, `com-artists`, `top-item`, ecc.) sono usati anche nel JS del sito → stabili nel tempo. Rischio: se Traxsource migra a un framework nuovo (React/Next), parser va rifatto.
+- **Rate limiting:** un solo GET per la genre + un GET per la playlist Top 100 = 2 richieste per caricare la chart. Cache 15 min. Zero rischio ban in uso normale.
+- **Legal:** stesso perimetro di Beatport — lettura di pagine pubbliche, no ToS violation esplicito.
+- **Comparabilità con Beatport:** un utente power potrebbe usare entrambe le tab per triangolare le release del mese. UX consistente = curva apprendimento zero.

main.py

@@ -4,6 +4,17 @@ import os
 import sys
 from pathlib import Path
 
+# ============================================================
+# Logging persistente su file (rotazione giornaliera, 7 giorni).
+# Chiamato SUBITO cosi' ogni traceback o print da qui in poi
+# finisce nel file, anche in modalita' windowed.
+# ============================================================
+try:
+    from core.applog import setup as _setup_log
+    _setup_log()
+except Exception as _e:
+    print(f"[bootstrap] log setup failed: {_e}")
+
 # ============================================================
 # Fix SSL CA bundle: quando l'app e' frozen (PyInstaller) i moduli
 # ssl e requests non trovano nessun CA bundle di default -> tutte

requirements.txt

@@ -10,6 +10,8 @@ pyobjc-framework-AVFoundation>=10.0 ; sys_platform == "darwin"
 pythonnet==3.0.5 ; sys_platform == "win32"
 clr-loader==0.2.7.post0 ; sys_platform == "win32"
 curl_cffi>=0.9.0
+beautifulsoup4>=4.12.0
+send2trash>=1.8.0
 
 # --- dev only ---
 pytest>=8.0.0

scripts/refresh_traxsource_genres.py

@@ -0,0 +1,34 @@
+"""Estrae la lista dei generi Traxsource dalla pagina /top.
+Uso: python3 scripts/refresh_traxsource_genres.py > /tmp/tx_genres.txt
+Poi copia manualmente in core/traxsource.py::GENRES."""
+
+from __future__ import annotations
+
+import re
+import sys
+from curl_cffi import requests
+
+
+def main() -> int:
+    s = requests.Session(impersonate="chrome131")
+    s.get("https://www.traxsource.com/", timeout=15)
+    r = s.get("https://www.traxsource.com/top", timeout=15,
+              headers={"Referer": "https://www.traxsource.com/"})
+    if r.status_code != 200:
+        print(f"HTTP {r.status_code}", file=sys.stderr)
+        return 1
+    # href="/genre/<id>/<slug>"
+    hits = re.findall(r'href="/genre/(\d+)/([a-z0-9-]+)"', r.text)
+    seen = set()
+    for gid, slug in hits:
+        if slug in seen:
+            continue
+        seen.add(slug)
+        # Display name = slug con capitalizzazione euristica (l'utente lo raffina a mano)
+        name = " ".join(w.capitalize() for w in slug.replace("-", " ").split())
+        print(f'    "{slug}": ({gid}, "{name}"),')
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/test_acoustid.py

@@ -0,0 +1,204 @@
+"""Test per core.acoustid — lookup AcoustID + cache SQLite.
+
+Mock su `requests.get` in modo che i test siano offline. Ogni test
+isola la cache SQLite in tmp_path via monkeypatch di
+`_cache_db_path`.
+"""
+
+from __future__ import annotations
+
+from unittest import mock
+
+import pytest
+
+from core import acoustid
+
+
+# ------------------------------------------------------------------
+# Fixture: cache isolata + reset del rate-limit
+# ------------------------------------------------------------------
+@pytest.fixture
+def patched_cache(tmp_path, monkeypatch):
+    db = tmp_path / "acoustid_cache_test.db"
+    monkeypatch.setattr(acoustid, "_cache_db_path", lambda: db)
+    # Rate-limit: azzera cosi' i test non aspettano throttle
+    monkeypatch.setattr(acoustid, "_RATE_LIMIT_SEC", 0.0)
+    monkeypatch.setattr(acoustid, "_last_request_at", [0.0])
+    return db
+
+
+def _mock_resp(status_code: int = 200, json_data: dict = None):
+    """Costruisce un mock di response `requests`."""
+    m = mock.Mock()
+    m.status_code = status_code
+    m.json.return_value = json_data or {}
+    return m
+
+
+# ------------------------------------------------------------------
+# lookup — cache
+# ------------------------------------------------------------------
+class TestLookupCache:
+    def test_lookup_uses_cache(self, patched_cache):
+        """Seconda chiamata con lo stesso fingerprint riusa la cache."""
+        payload = {
+            "status": "ok",
+            "results": [{
+                "score": 0.99,
+                "recordings": [{
+                    "title": "Some Song",
+                    "artists": [{"name": "Artist X"}],
+                    "releases": [
+                        {"date": {"year": 2005},
+                         "releasegroup": {"tags": [{"name": "House", "count": 5}]}},
+                    ],
+                }],
+            }],
+        }
+        with mock.patch.object(acoustid.requests, "get",
+                                return_value=_mock_resp(200, payload)) as m:
+            r1 = acoustid.lookup("FP-1", 180.0)
+            r2 = acoustid.lookup("FP-1", 180.0)
+
+        assert m.call_count == 1, "la seconda chiamata deve venire dalla cache"
+        assert r1 == r2
+        assert r1["matched"] is True
+        assert r1["year"] == 2005
+        assert r1["genre"].lower() == "house"
+        assert r1["title"] == "Some Song"
+        assert r1["artist"] == "Artist X"
+
+
+# ------------------------------------------------------------------
+# lookup — no results / errori
+# ------------------------------------------------------------------
+class TestLookupNoResults:
+    def test_lookup_no_results_returns_unmatched(self, patched_cache):
+        payload = {"status": "ok", "results": []}
+        with mock.patch.object(acoustid.requests, "get",
+                                return_value=_mock_resp(200, payload)):
+            r = acoustid.lookup("FP-NORESULT", 100.0)
+
+        assert r["matched"] is False
+        # deve essere cacheato
+        with mock.patch.object(acoustid.requests, "get") as m:
+            r2 = acoustid.lookup("FP-NORESULT", 100.0)
+            assert m.call_count == 0
+        assert r2 == r
+
+    def test_lookup_no_recordings_returns_unmatched(self, patched_cache):
+        """results presenti ma senza recordings -> matched=False."""
+        payload = {
+            "status": "ok",
+            "results": [{"score": 0.5, "recordings": []}],
+        }
+        with mock.patch.object(acoustid.requests, "get",
+                                return_value=_mock_resp(200, payload)):
+            r = acoustid.lookup("FP-EMPTYREC", 200)
+        assert r["matched"] is False
+
+
+# ------------------------------------------------------------------
+# lookup — anno minimo
+# ------------------------------------------------------------------
+class TestLookupYearExtraction:
+    def test_lookup_extracts_min_year(self, patched_cache):
+        """3 releases (2003, 1998, 2010) -> year=1998."""
+        payload = {
+            "status": "ok",
+            "results": [{
+                "score": 0.95,
+                "recordings": [{
+                    "title": "Classic",
+                    "artists": [{"name": "Artist"}],
+                    "releases": [
+                        {"date": {"year": 2003}},
+                        {"date": {"year": 1998}},
+                        {"date": {"year": 2010}},
+                    ],
+                }],
+            }],
+        }
+        with mock.patch.object(acoustid.requests, "get",
+                                return_value=_mock_resp(200, payload)):
+            r = acoustid.lookup("FP-YEAR", 180)
+
+        assert r["matched"] is True
+        assert r["year"] == 1998
+
+    def test_lookup_missing_year_becomes_none(self, patched_cache):
+        """Nessuna release con year valido -> year=None (matched se ha titolo)."""
+        payload = {
+            "status": "ok",
+            "results": [{
+                "score": 0.9,
+                "recordings": [{
+                    "title": "T",
+                    "artists": [{"name": "A"}],
+                    "releases": [{"date": {}}, {"other": 1}],
+                }],
+            }],
+        }
+        with mock.patch.object(acoustid.requests, "get",
+                                return_value=_mock_resp(200, payload)):
+            r = acoustid.lookup("FP-NOY", 100)
+        # matched puo' essere True se ha almeno un titolo
+        assert r["year"] is None
+        assert r["title"] == "T"
+
+
+# ------------------------------------------------------------------
+# lookup — errori HTTP / rete
+# ------------------------------------------------------------------
+class TestLookupErrors:
+    def test_lookup_returns_error_on_http_failure(self, patched_cache):
+        with mock.patch.object(acoustid.requests, "get",
+                                return_value=_mock_resp(500, {})):
+            r = acoustid.lookup("FP-HTTP", 100)
+        assert r["matched"] is False
+        assert "HTTP 500" in r.get("error", "")
+
+    def test_lookup_returns_error_on_network_failure(self, patched_cache):
+        with mock.patch.object(acoustid.requests, "get",
+                                side_effect=acoustid.requests.ConnectionError("boom")):
+            r = acoustid.lookup("FP-NET", 100)
+        assert r["matched"] is False
+        assert "network" in r.get("error", "").lower() or "boom" in r.get("error", "")
+
+    def test_lookup_empty_fingerprint_returns_unmatched(self, patched_cache):
+        r = acoustid.lookup("", 100)
+        assert r["matched"] is False
+        assert "fingerprint" in r.get("error", "").lower()
+
+    def test_lookup_api_status_error(self, patched_cache):
+        payload = {"status": "error",
+                    "error": {"message": "invalid fingerprint"}}
+        with mock.patch.object(acoustid.requests, "get",
+                                return_value=_mock_resp(200, payload)):
+            r = acoustid.lookup("FP-BAD", 100)
+        assert r["matched"] is False
+        assert "invalid" in r.get("error", "").lower()
+
+
+# ------------------------------------------------------------------
+# helper: _extract_top_genre
+# ------------------------------------------------------------------
+class TestGenreExtraction:
+    def test_top_genre_picks_highest_count(self):
+        releases = [{
+            "releasegroup": {
+                "tags": [
+                    {"name": "electronic", "count": 3},
+                    {"name": "house", "count": 12},
+                    {"name": "dance", "count": 7},
+                ]
+            }
+        }]
+        assert acoustid._extract_top_genre(releases).lower() == "house"
+
+    def test_top_genre_no_tags_returns_empty(self):
+        releases = [{"releasegroup": {"tags": []}}]
+        assert acoustid._extract_top_genre(releases) == ""
+
+    def test_top_genre_no_releasegroup_returns_empty(self):
+        assert acoustid._extract_top_genre([{}]) == ""

tests/test_catalog.py

@@ -0,0 +1,205 @@
+"""Test per core.catalog — sanitize + move_files + scan_folder.
+
+Focus principale sui casi in cui il piano ha promesso comportamento
+esplicito: sanitize dei chars vietati, struttura year/genre, gestione
+di anno/genere mancanti, conflitto di filename.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest import mock
+
+import pytest
+
+from core import catalog
+
+
+# ------------------------------------------------------------------
+# Sanitize
+# ------------------------------------------------------------------
+class TestSanitizeFolder:
+    def test_sanitize_folder_removes_forbidden_chars(self):
+        # `/` (dai tag musicbrainz), `:` (Windows), `?`, `*`, `|`, ecc.
+        s = catalog._sanitize_folder("electronic/house")
+        assert "/" not in s
+        assert "electronic" in s and "house" in s
+
+        s2 = catalog._sanitize_folder("prog:rock?")
+        for ch in '<>:"|?*\\/':
+            assert ch not in s2
+
+    def test_sanitize_folder_collapses_spaces(self):
+        assert catalog._sanitize_folder("  tech  house  ") == "tech house"
+
+    def test_sanitize_folder_empty_returns_empty(self):
+        assert catalog._sanitize_folder("") == ""
+        assert catalog._sanitize_folder(None) == ""
+
+    def test_sanitize_folder_truncates_long(self):
+        s = catalog._sanitize_folder("a" * 300)
+        assert len(s) <= 100
+
+
+# ------------------------------------------------------------------
+# move_files
+# ------------------------------------------------------------------
+def _touch(path: Path, size: int = 8) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(b"\x00" * size)
+    return path
+
+
+class TestMoveFiles:
+    def test_move_files_creates_year_genre_structure(self, tmp_path):
+        """Un file matched → finisce in <target>/<year>/<genre>/<filename>."""
+        src = _touch(tmp_path / "source" / "song.mp3")
+        target = tmp_path / "cat"
+        entries = [{
+            "path": str(src), "size": src.stat().st_size,
+            "matched": True, "year": 2005, "genre": "House",
+            "artist": "X", "title": "T", "fingerprint": "FP",
+        }]
+
+        res = catalog.move_files(entries, str(target))
+
+        assert res["moved"] == 1
+        assert res["failed"] == []
+        dst = target / "2005" / "House" / "song.mp3"
+        assert dst.exists()
+        assert not src.exists()
+        # Log operations popolato
+        assert res["operations"] and res["operations"][0]["src"] == str(src)
+        assert res["operations"][0]["dst"] == str(dst)
+
+    def test_move_files_handles_missing_year_or_genre(self, tmp_path):
+        """Year/genre mancanti → Unknown Year / Unknown Genre."""
+        no_year = _touch(tmp_path / "src" / "no_year.mp3")
+        no_genre = _touch(tmp_path / "src" / "no_genre.mp3")
+        no_both = _touch(tmp_path / "src" / "no_both.mp3")
+
+        target = tmp_path / "cat"
+        entries = [
+            {"path": str(no_year), "matched": True, "year": None,
+             "genre": "House"},
+            {"path": str(no_genre), "matched": True, "year": 2010,
+             "genre": ""},
+            {"path": str(no_both), "matched": False, "year": None,
+             "genre": ""},
+        ]
+
+        res = catalog.move_files(entries, str(target))
+        assert res["moved"] == 3
+        assert (target / "Unknown Year" / "House" / "no_year.mp3").exists()
+        assert (target / "2010" / "Unknown Genre" / "no_genre.mp3").exists()
+        assert (target / "Unknown Year" / "Unknown Genre"
+                / "no_both.mp3").exists()
+
+    def test_move_files_dedup_conflicting_filenames(self, tmp_path):
+        """Se un file con lo stesso nome esiste gia' nel target, aggiungi
+        suffisso _1, _2, ... (mai overwrite)."""
+        src1 = _touch(tmp_path / "srcA" / "song.mp3", size=10)
+        src2 = _touch(tmp_path / "srcB" / "song.mp3", size=20)
+        target = tmp_path / "cat"
+
+        entries = [
+            {"path": str(src1), "matched": True, "year": 2000,
+             "genre": "Rock"},
+            {"path": str(src2), "matched": True, "year": 2000,
+             "genre": "Rock"},
+        ]
+        res = catalog.move_files(entries, str(target))
+        assert res["moved"] == 2
+        d1 = target / "2000" / "Rock" / "song.mp3"
+        d2 = target / "2000" / "Rock" / "song_1.mp3"
+        assert d1.exists() and d2.exists()
+        # Contenuto preservato dal move (src1 = 10 byte, src2 = 20 byte).
+        # L'ordine di iterazione garantisce che song.mp3 = src1.
+        assert d1.stat().st_size == 10
+        assert d2.stat().st_size == 20
+
+    def test_move_files_sanitizes_forbidden_genre(self, tmp_path):
+        """Genere con `/` (tipico di musicbrainz) va sanitizzato in `_`."""
+        src = _touch(tmp_path / "src" / "song.mp3")
+        target = tmp_path / "cat"
+        entries = [{
+            "path": str(src), "matched": True, "year": 2020,
+            "genre": "electronic/house",
+        }]
+
+        res = catalog.move_files(entries, str(target))
+        assert res["moved"] == 1
+        # NON deve creare "electronic" e dentro "house": e' un solo nome.
+        assert not (target / "2020" / "electronic").is_dir()
+        # La cartella deve contenere entrambe le parti sanitizzate
+        year_dir = target / "2020"
+        subdirs = [p.name for p in year_dir.iterdir() if p.is_dir()]
+        assert len(subdirs) == 1
+        assert "/" not in subdirs[0]
+        assert "electronic" in subdirs[0] and "house" in subdirs[0]
+
+    def test_move_files_missing_source_reports_failed(self, tmp_path):
+        """File che non esiste piu' → finisce in failed, non alza."""
+        target = tmp_path / "cat"
+        entries = [{
+            "path": str(tmp_path / "does_not_exist.mp3"),
+            "matched": True, "year": 2000, "genre": "X",
+        }]
+        res = catalog.move_files(entries, str(target))
+        assert res["moved"] == 0
+        assert len(res["failed"]) == 1
+        assert "non esiste" in res["failed"][0]["error"].lower()
+
+    def test_move_files_empty_list_returns_zero(self, tmp_path):
+        res = catalog.move_files([], str(tmp_path / "cat"))
+        assert res["moved"] == 0
+        assert res["failed"] == []
+        assert res["operations"] == []
+
+
+# ------------------------------------------------------------------
+# scan_folder — smoke integration test (mock fpcalc + lookup)
+# ------------------------------------------------------------------
+class TestScanFolder:
+    def test_scan_folder_empty_directory(self, tmp_path):
+        # Cartella senza file audio → lista vuota, no crash
+        with mock.patch.object(catalog, "find_fpcalc",
+                                return_value="/fake/fpcalc"):
+            entries = catalog.scan_folder(str(tmp_path), recursive=False)
+        assert entries == []
+
+    def test_scan_folder_processes_files(self, tmp_path):
+        # Un file audio fake + mock di fpcalc + lookup
+        (tmp_path / "a.mp3").write_bytes(b"\x00" * 100)
+        (tmp_path / "readme.txt").write_text("hi")
+
+        with mock.patch.object(catalog, "find_fpcalc",
+                                return_value="/fake/fpcalc"), \
+             mock.patch.object(catalog, "compute_fingerprint",
+                                return_value={"fingerprint": "FP", "duration": 100}), \
+             mock.patch.object(catalog, "lookup",
+                                return_value={
+                                    "matched": True, "year": 2018,
+                                    "genre": "House", "artist": "A",
+                                    "title": "T",
+                                }):
+            entries = catalog.scan_folder(str(tmp_path), recursive=False)
+
+        assert len(entries) == 1
+        e = entries[0]
+        assert e["matched"] is True
+        assert e["year"] == 2018
+        assert e["genre"] == "House"
+        assert e["fingerprint"] == "FP"
+
+    def test_scan_folder_records_fpcalc_error(self, tmp_path):
+        """fpcalc fallito → entry con matched=False + error."""
+        (tmp_path / "broken.mp3").write_bytes(b"\x00" * 10)
+        with mock.patch.object(catalog, "find_fpcalc",
+                                return_value="/fake/fpcalc"), \
+             mock.patch.object(catalog, "compute_fingerprint",
+                                return_value={"_error": "fingerprint vuoto"}):
+            entries = catalog.scan_folder(str(tmp_path), recursive=False)
+        assert len(entries) == 1
+        assert entries[0]["matched"] is False
+        assert "vuoto" in entries[0]["error"]

tests/test_converter.py

@@ -0,0 +1,104 @@
+"""Test per core.converter — file scanning + stop event.
+
+I test evitano di invocare ffmpeg reale (che potrebbe non essere in PATH
+in CI). La funzione di conversione vera e propria e' coperta manualmente.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from core import converter
+
+
+class TestListWavFiles:
+    def test_scans_recursively(self, tmp_path: Path):
+        # Struttura:
+        #   root/a.wav
+        #   root/b.WAV  (case insensitive: glob su POSIX distingue,
+        #                quindi controllo esplicito che almeno i .wav
+        #                minuscoli siano restituiti)
+        #   root/c.mp3
+        #   root/sub/d.wav
+        (tmp_path / "a.wav").write_bytes(b"RIFF")
+        (tmp_path / "c.mp3").write_bytes(b"ID3")
+        sub = tmp_path / "sub"
+        sub.mkdir()
+        (sub / "d.wav").write_bytes(b"RIFF")
+
+        got = converter.list_wav_files(str(tmp_path), recursive=True)
+
+        assert len(got) == 2
+        names = {Path(p).name for p in got}
+        assert names == {"a.wav", "d.wav"}
+        # Ordinamento stabile
+        assert got == sorted(got)
+
+    def test_non_recursive_ignores_subfolders(self, tmp_path: Path):
+        (tmp_path / "a.wav").write_bytes(b"RIFF")
+        sub = tmp_path / "sub"
+        sub.mkdir()
+        (sub / "b.wav").write_bytes(b"RIFF")
+
+        got = converter.list_wav_files(str(tmp_path), recursive=False)
+
+        assert len(got) == 1
+        assert Path(got[0]).name == "a.wav"
+
+    def test_empty_dir_returns_empty(self, tmp_path: Path):
+        assert converter.list_wav_files(str(tmp_path)) == []
+
+    def test_missing_dir_returns_empty(self, tmp_path: Path):
+        missing = tmp_path / "does-not-exist"
+        assert converter.list_wav_files(str(missing)) == []
+
+    def test_ignores_non_wav_files(self, tmp_path: Path):
+        (tmp_path / "song.mp3").write_bytes(b"ID3")
+        (tmp_path / "song.flac").write_bytes(b"fLaC")
+        (tmp_path / "notes.txt").write_text("hello")
+
+        assert converter.list_wav_files(str(tmp_path)) == []
+
+
+class TestStopEvent:
+    def setup_method(self):
+        # Ogni test parte con lo stop event pulito.
+        converter.reset_stop()
+
+    def teardown_method(self):
+        converter.reset_stop()
+
+    def test_reset_initially_not_stopped(self):
+        converter.reset_stop()
+        assert converter.is_stopped() is False
+
+    def test_request_stop_sets_flag(self):
+        converter.request_stop()
+        assert converter.is_stopped() is True
+
+    def test_reset_after_stop_clears_flag(self):
+        converter.request_stop()
+        assert converter.is_stopped() is True
+        converter.reset_stop()
+        assert converter.is_stopped() is False
+
+
+class TestConvertWavToMp3Errors:
+    def test_missing_input_raises(self, tmp_path: Path):
+        missing = tmp_path / "nope.wav"
+        out = tmp_path / "out.mp3"
+        with pytest.raises(FileNotFoundError):
+            converter.convert_wav_to_mp3(str(missing), str(out))
+
+
+class TestVbrQualityMap:
+    def test_all_bitrates_have_mapping(self):
+        for br in (128, 192, 256, 320):
+            assert br in converter._VBR_QUALITY
+
+    def test_higher_bitrate_lower_or_equal_quality_number(self):
+        # -q:a: piu' basso = migliore. Coerenza monotona sulle chiavi.
+        vals = [converter._VBR_QUALITY[br] for br in (128, 192, 256, 320)]
+        assert vals == sorted(vals, reverse=True)

tests/test_dedup.py

@@ -0,0 +1,193 @@
+"""Test per core.dedup — audio fingerprinting via fpcalc + cache SQLite.
+
+Tutti gli unit test usano mock per fpcalc / send2trash: nessuna
+integrazione reale, nessun file audio necessario.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from unittest import mock
+
+import pytest
+
+from core import dedup
+
+
+# ------------------------------------------------------------------
+# Fixture: dedup con cache DB isolato in tmp_path
+# ------------------------------------------------------------------
+@pytest.fixture
+def patched_cache(tmp_path, monkeypatch):
+    """Isola la cache SQLite in tmp_path per non toccare il config dir."""
+    db = tmp_path / "dedup_cache_test.db"
+    monkeypatch.setattr(dedup, "_cache_db_path", lambda: db)
+    return db
+
+
+def _make_fake_audio(tmp_path: Path, name: str, size: int = 1024) -> Path:
+    """Crea un file 'audio' fake (byte casuali con estensione .mp3)."""
+    f = tmp_path / name
+    f.write_bytes(b"\x00" * size)
+    return f
+
+
+# ------------------------------------------------------------------
+# scan_folder
+# ------------------------------------------------------------------
+class TestScanFolder:
+    def test_no_audio_files(self, tmp_path, patched_cache):
+        """Cartella senza audio -> gruppi vuoti, nessuna eccezione."""
+        # Solo un file .txt (non audio)
+        (tmp_path / "readme.txt").write_text("hello")
+
+        # Anche senza fpcalc disponibile, con 0 audio file ritorna [].
+        with mock.patch.object(dedup, "find_fpcalc", return_value="/fake/fpcalc"):
+            groups = dedup.scan_folder(str(tmp_path), recursive=False)
+
+        assert groups == []
+
+    def test_uses_cache_on_second_scan(self, tmp_path, patched_cache):
+        """Prima scan chiama fpcalc; seconda scan riusa la cache."""
+        _make_fake_audio(tmp_path, "song.mp3", size=2048)
+
+        calls: list[str] = []
+
+        def fake_compute(fpcalc, path):
+            calls.append(path)
+            return {"duration": 180.5, "fingerprint": "FP-A"}
+
+        with mock.patch.object(dedup, "find_fpcalc", return_value="/fake/fpcalc"), \
+             mock.patch.object(dedup, "compute_fingerprint", side_effect=fake_compute), \
+             mock.patch.object(dedup, "get_bitrate", return_value=320):
+            # Prima invocazione: fpcalc DEVE essere chiamato
+            groups1 = dedup.scan_folder(str(tmp_path), recursive=False)
+            first_calls = len(calls)
+
+            # Seconda invocazione (stesso file, stesso mtime/size):
+            # cache HIT, fpcalc NON viene richiamato
+            groups2 = dedup.scan_folder(str(tmp_path), recursive=False)
+            second_calls = len(calls)
+
+        assert first_calls == 1, "prima scan deve chiamare fpcalc una volta"
+        assert second_calls == 1, "seconda scan deve riusare la cache"
+        # Con un solo file, nessun gruppo di duplicati
+        assert groups1 == []
+        assert groups2 == []
+
+    def test_groups_duplicates(self, tmp_path, patched_cache):
+        """3 file con lo stesso fingerprint -> 1 gruppo di 3, ordinato per bitrate DESC."""
+        _make_fake_audio(tmp_path, "a.mp3", size=1000)
+        _make_fake_audio(tmp_path, "b.mp3", size=3000)  # size maggiore
+        _make_fake_audio(tmp_path, "c.mp3", size=2000)
+
+        # Tutti stesso fingerprint. Bitrate differente per verificare
+        # l'ordinamento: b=320 (top), a=192, c=128.
+        bitrate_by_name = {"a.mp3": 192, "b.mp3": 320, "c.mp3": 128}
+
+        with mock.patch.object(dedup, "find_fpcalc", return_value="/fake/fpcalc"), \
+             mock.patch.object(dedup, "compute_fingerprint",
+                               return_value={"duration": 200, "fingerprint": "SAME-FP"}), \
+             mock.patch.object(dedup, "get_bitrate",
+                               side_effect=lambda p: bitrate_by_name[Path(p).name]):
+            groups = dedup.scan_folder(str(tmp_path), recursive=False)
+
+        assert len(groups) == 1, "esattamente un gruppo di duplicati"
+        g = groups[0]
+        assert len(g) == 3, "tre file nel gruppo"
+        # Ordine: bitrate DESC -> b (320), a (192), c (128)
+        assert [Path(e["path"]).name for e in g] == ["b.mp3", "a.mp3", "c.mp3"]
+        # Ogni entry ha i campi attesi
+        for e in g:
+            assert set(e.keys()) >= {"path", "size", "bitrate", "duration", "fingerprint"}
+            assert e["fingerprint"] == "SAME-FP"
+
+    def test_ignores_singletons(self, tmp_path, patched_cache):
+        """File con fingerprint unico non compaiono nei gruppi."""
+        _make_fake_audio(tmp_path, "dup1.mp3")
+        _make_fake_audio(tmp_path, "dup2.mp3")
+        _make_fake_audio(tmp_path, "unique.mp3")
+
+        fp_by_name = {"dup1.mp3": "FP-X", "dup2.mp3": "FP-X", "unique.mp3": "FP-Y"}
+
+        def fake_compute(fpcalc, path):
+            return {"duration": 100, "fingerprint": fp_by_name[Path(path).name]}
+
+        with mock.patch.object(dedup, "find_fpcalc", return_value="/fake/fpcalc"), \
+             mock.patch.object(dedup, "compute_fingerprint", side_effect=fake_compute), \
+             mock.patch.object(dedup, "get_bitrate", return_value=256):
+            groups = dedup.scan_folder(str(tmp_path), recursive=False)
+
+        # Solo il gruppo con dup1/dup2
+        assert len(groups) == 1
+        names = {Path(e["path"]).name for e in groups[0]}
+        assert names == {"dup1.mp3", "dup2.mp3"}
+        # unique.mp3 non appare in nessun gruppo
+        for g in groups:
+            for e in g:
+                assert Path(e["path"]).name != "unique.mp3"
+
+
+# ------------------------------------------------------------------
+# move_to_trash
+# ------------------------------------------------------------------
+class TestMoveToTrash:
+    def test_returns_moved_and_failed_summary(self, tmp_path, patched_cache):
+        """Verifica che il summary contenga moved/failed correttamente."""
+        # 2 path OK + 1 path che alza eccezione
+        ok1 = str(tmp_path / "ok1.mp3")
+        ok2 = str(tmp_path / "ok2.mp3")
+        bad = str(tmp_path / "bad.mp3")
+
+        def fake_send(p):
+            if p == bad:
+                raise OSError("simulated failure")
+            # ok: no-op
+
+        # Il modulo importa send2trash *dentro* la funzione, quindi
+        # dobbiamo patchare il modulo importato.
+        with mock.patch("send2trash.send2trash", side_effect=fake_send):
+            res = dedup.move_to_trash([ok1, bad, ok2])
+
+        assert set(res["moved"]) == {ok1, ok2}
+        assert len(res["failed"]) == 1
+        assert res["failed"][0]["path"] == bad
+        assert "simulated failure" in res["failed"][0]["error"]
+
+
+# ------------------------------------------------------------------
+# compute_fingerprint
+# ------------------------------------------------------------------
+class TestComputeFingerprint:
+    def test_timeout_returns_error(self):
+        """Timeout di fpcalc -> dict con _error, no fingerprint."""
+        with mock.patch("core.dedup.subprocess.run",
+                        side_effect=subprocess.TimeoutExpired(cmd="fpcalc", timeout=30)):
+            result = dedup.compute_fingerprint("/fake/fpcalc", "/some/file.mp3")
+        assert result and "_error" in result and "timeout" in result["_error"]
+        assert "fingerprint" not in result
+
+    def test_success_returns_dict(self):
+        """Output JSON valido -> {duration, fingerprint}."""
+        fake_proc = mock.Mock()
+        fake_proc.returncode = 0
+        fake_proc.stdout = '{"duration": 123.4, "fingerprint": "ABCDEF"}'
+        with mock.patch("core.dedup.subprocess.run", return_value=fake_proc):
+            result = dedup.compute_fingerprint("/fake/fpcalc", "/some/file.mp3")
+        assert result == {"duration": 123.4, "fingerprint": "ABCDEF"}
+
+    def test_bad_json_returns_error(self):
+        fake_proc = mock.Mock()
+        fake_proc.returncode = 0
+        fake_proc.stdout = "not json at all"
+        with mock.patch("core.dedup.subprocess.run", return_value=fake_proc):
+            result = dedup.compute_fingerprint("/fake/fpcalc", "/some/file.mp3")
+        assert result and "_error" in result and "JSON" in result["_error"]
+        assert "fingerprint" not in result
+
+    def test_missing_fpcalc_returns_error(self):
+        # Nessuna chiamata subprocess se fpcalc e' vuoto
+        result = dedup.compute_fingerprint("", "/some/file.mp3")
+        assert result and "_error" in result and "fpcalc" in result["_error"]
+        assert "fingerprint" not in result

tests/test_traxsource.py

@@ -0,0 +1,217 @@
+"""Test per core.traxsource."""
+
+from __future__ import annotations
+
+import pytest
+
+from core import traxsource
+
+
+class TestListGenres:
+    def test_returns_list_of_dicts(self):
+        result = traxsource.list_genres()
+        assert isinstance(result, list)
+        assert len(result) >= 10
+        for g in result:
+            assert set(g.keys()) == {"slug", "id", "name"}
+            assert isinstance(g["slug"], str) and g["slug"]
+            assert isinstance(g["id"], int) and g["id"] > 0
+            assert isinstance(g["name"], str) and g["name"]
+
+    def test_sorted_alphabetically_by_name(self):
+        result = traxsource.list_genres()
+        names = [g["name"] for g in result]
+        assert names == sorted(names, key=str.casefold)
+
+    def test_tech_house_present(self):
+        result = traxsource.list_genres()
+        slugs = [g["slug"] for g in result]
+        assert "tech-house" in slugs
+
+
+class TestTraxsourceTrack:
+    def test_frozen(self):
+        t = traxsource.TraxsourceTrack(
+            position=1, title="X", mix="Y", artists="A", label="L",
+            traxsource_id=1, slug="x",
+        )
+        with pytest.raises(Exception):
+            t.title = "Z"
+
+    def test_defaults(self):
+        t = traxsource.TraxsourceTrack(
+            position=1, title="X", mix="", artists="A", label="",
+            traxsource_id=1, slug="x",
+        )
+        assert t.image_url == ""
+        assert t.cover_url_large == ""
+
+
+class TestSplitTitleMix:
+    def test_with_parens(self):
+        assert traxsource._split_title_mix("Foo (Extended Mix)") == ("Foo", "Extended Mix")
+
+    def test_without_parens(self):
+        assert traxsource._split_title_mix("Foo") == ("Foo", "")
+
+    def test_multiple_parens_takes_last(self):
+        # es. "Foo (feat. Bar) (Original Mix)" -> mix = "Original Mix"
+        assert traxsource._split_title_mix("Foo (feat. Bar) (Original Mix)") == ("Foo (feat. Bar)", "Original Mix")
+
+    def test_empty(self):
+        assert traxsource._split_title_mix("") == ("", "")
+
+
+class TestFormatArtists:
+    def test_single(self):
+        assert traxsource._format_artists(["Kapuchon"]) == "Kapuchon"
+
+    def test_two(self):
+        assert traxsource._format_artists(["A", "B"]) == "A & B"
+
+    def test_three(self):
+        assert traxsource._format_artists(["A", "B", "C"]) == "A, B & C"
+
+    def test_empty(self):
+        assert traxsource._format_artists([]) == ""
+
+    def test_strips_whitespace(self):
+        assert traxsource._format_artists(["  A  ", " B "]) == "A & B"
+
+
+class TestLargeCover:
+    def test_substitutes_52x52_with_500x500(self):
+        url = "https://www.traxsource.com/scripts/image.php/52x52/abc.jpg"
+        assert traxsource._large_cover(url) == "https://www.traxsource.com/scripts/image.php/500x500/abc.jpg"
+
+    def test_no_change_when_no_pattern(self):
+        assert traxsource._large_cover("https://example.com/x.jpg") == "https://example.com/x.jpg"
+
+    def test_empty(self):
+        assert traxsource._large_cover("") == ""
+
+
+class TestExceptions:
+    def test_exceptions_are_subclasses(self):
+        assert issubclass(traxsource.TraxsourceUnreachableError, traxsource.TraxsourceError)
+        assert issubclass(traxsource.TraxsourceParseError, traxsource.TraxsourceError)
+
+
+class TestDiscoverTop100Url:
+    def test_extracts_link_from_genre_page(self, fixtures_dir):
+        html = (fixtures_dir / "traxsource_tech_house_genre.html").read_text()
+        url = traxsource._discover_top100_url(html)
+        assert url.startswith("/title/")
+        assert "top-100" in url
+
+    def test_raises_when_no_link(self):
+        with pytest.raises(traxsource.TraxsourceParseError, match="Top 100"):
+            traxsource._discover_top100_url("<html>nulla</html>")
+
+
+class TestParseTracks:
+    def test_parses_100_tracks(self, fixtures_dir):
+        html = (fixtures_dir / "traxsource_tech_house_top100.html").read_text()
+        tracks = traxsource._parse_tracks(html)
+        assert len(tracks) == 100
+
+    def test_positions_sequential_1_to_100(self, fixtures_dir):
+        html = (fixtures_dir / "traxsource_tech_house_top100.html").read_text()
+        tracks = traxsource._parse_tracks(html)
+        positions = [t.position for t in tracks]
+        assert positions == list(range(1, 101))
+
+    def test_track_shape(self, fixtures_dir):
+        html = (fixtures_dir / "traxsource_tech_house_top100.html").read_text()
+        tracks = traxsource._parse_tracks(html)
+        first = tracks[0]
+        assert first.title
+        assert first.artists
+        assert first.traxsource_id > 0
+        assert first.slug
+        assert first.image_url.startswith("https://")
+        assert first.cover_url_large.startswith("https://")
+        assert "500x500" in first.cover_url_large
+
+    def test_raises_when_no_tracks(self):
+        with pytest.raises(traxsource.TraxsourceParseError, match="track"):
+            traxsource._parse_tracks("<html>vuoto</html>")
+
+
+from unittest.mock import patch, MagicMock
+
+
+def _mock_response(text: str, status_code: int = 200) -> MagicMock:
+    resp = MagicMock()
+    resp.text = text
+    resp.status_code = status_code
+
+    def _raise():
+        if status_code >= 400:
+            raise Exception(f"HTTP {status_code}")
+    resp.raise_for_status = _raise
+    return resp
+
+
+class TestFetchTop100:
+    @pytest.fixture
+    def genre_html(self, fixtures_dir):
+        return (fixtures_dir / "traxsource_tech_house_genre.html").read_text()
+
+    @pytest.fixture
+    def top100_html(self, fixtures_dir):
+        return (fixtures_dir / "traxsource_tech_house_top100.html").read_text()
+
+    def test_success_returns_100_tracks(self, genre_html, top100_html):
+        traxsource._cache.clear()
+        mock_sess = MagicMock()
+        mock_sess.get.side_effect = [
+            _mock_response(genre_html, 200),
+            _mock_response(top100_html, 200),
+        ]
+        with patch("core.traxsource._session", return_value=mock_sess):
+            tracks = traxsource.fetch_top100("tech-house")
+        assert len(tracks) == 100
+
+    def test_invalid_slug_raises_value_error(self):
+        with pytest.raises(ValueError, match="slug"):
+            traxsource.fetch_top100("not-a-genre")
+
+    def test_5xx_retries_and_raises_unreachable(self):
+        traxsource._cache.clear()
+        mock_sess = MagicMock()
+        mock_sess.get.return_value = _mock_response("", 503)
+        with patch("core.traxsource._session", return_value=mock_sess), \
+             patch("core.traxsource.time.sleep"):
+            with pytest.raises(traxsource.TraxsourceUnreachableError):
+                traxsource.fetch_top100("tech-house")
+        # 3 tentativi
+        assert mock_sess.get.call_count == 3
+
+    def test_cache_hit_within_ttl(self, genre_html, top100_html):
+        traxsource._cache.clear()
+        mock_sess = MagicMock()
+        mock_sess.get.side_effect = [
+            _mock_response(genre_html, 200),
+            _mock_response(top100_html, 200),
+        ]
+        with patch("core.traxsource._session", return_value=mock_sess):
+            traxsource.fetch_top100("tech-house")
+            traxsource.fetch_top100("tech-house")
+        # 2 chiamate al primo fetch (genre + top100), 0 al secondo
+        assert mock_sess.get.call_count == 2
+
+    def test_force_refresh_bypasses_cache(self, genre_html, top100_html):
+        traxsource._cache.clear()
+        mock_sess = MagicMock()
+        # 4 risposte (2 fetch x 2 richieste ciascuno)
+        mock_sess.get.side_effect = [
+            _mock_response(genre_html, 200),
+            _mock_response(top100_html, 200),
+            _mock_response(genre_html, 200),
+            _mock_response(top100_html, 200),
+        ]
+        with patch("core.traxsource._session", return_value=mock_sess):
+            traxsource.fetch_top100("tech-house")
+            traxsource.fetch_top100("tech-house", force_refresh=True)
+        assert mock_sess.get.call_count == 4

tests/test_upgrader_archive.py

@@ -0,0 +1,169 @@
+"""Test unitari per le funzioni di archive-lookup in core.upgrader.
+
+Focalizzati su _normalize_stem, _scan_archive, _find_candidates.
+Non testiamo il flow end-to-end di upgrade_folder (richiederebbe mock
+di subprocess/yt-dlp/ffmpeg — out of scope, coperto da smoke test manuale).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from core import upgrader
+
+
+# ============================================================
+# _normalize_stem
+# ============================================================
+class TestNormalizeStem:
+    def test_lowercase_and_dedup(self):
+        # "Hot" e "hot" → un solo token; token duplicati collassano nel set
+        got = upgrader._normalize_stem("Hot Sauce hot sauce")
+        assert got == {"hot", "sauce"}
+
+    def test_filters_short_tokens(self):
+        # Token di lunghezza < 3 vengono scartati (di, il, a, b, cd...)
+        got = upgrader._normalize_stem("A B cd Boombox")
+        assert "a" not in got
+        assert "b" not in got
+        assert "cd" not in got
+        assert "boombox" in got
+
+    def test_removes_punctuation(self):
+        # Trattini, virgole, parentesi, apostrofi → tutti sostituiti con spazi
+        got = upgrader._normalize_stem("Artist - Title (Extended Mix)")
+        assert got == {"artist", "title", "extended", "mix"}
+
+    def test_empty_input(self):
+        assert upgrader._normalize_stem("") == set()
+        assert upgrader._normalize_stem("   ") == set()
+
+    def test_only_short_tokens_returns_empty(self):
+        assert upgrader._normalize_stem("a b c d") == set()
+
+
+# ============================================================
+# _scan_archive
+# ============================================================
+class TestScanArchive:
+    def test_recursive_scan(self, tmp_path: Path):
+        # Crea albero: top-level + sub/ + sub/sub2/
+        (tmp_path / "Artist - Song.mp3").touch()
+        (tmp_path / "sub").mkdir()
+        (tmp_path / "sub" / "Second Track.mp3").touch()
+        (tmp_path / "sub" / "sub2").mkdir()
+        (tmp_path / "sub" / "sub2" / "Deep One.m4a").touch()
+        # File non-audio devono essere ignorati
+        (tmp_path / "readme.txt").touch()
+
+        index = upgrader._scan_archive(str(tmp_path))
+        # 3 entries totali (una per ogni file audio, ognuna con token distinti)
+        assert len(index) == 3
+        # Verifica che le path siano riferite ai file corretti
+        all_paths = [p for paths in index.values() for p in paths]
+        names = sorted(p.name for p in all_paths)
+        assert names == ["Artist - Song.mp3", "Deep One.m4a", "Second Track.mp3"]
+
+    def test_case_insensitive_extensions(self, tmp_path: Path):
+        (tmp_path / "one.MP3").touch()
+        (tmp_path / "two.Mp3").touch()
+        (tmp_path / "three.WAV").touch()
+        (tmp_path / "four.FLAC").touch()
+        (tmp_path / "five.txt").touch()  # non-audio: ignorato
+        index = upgrader._scan_archive(str(tmp_path))
+        all_paths = [p for paths in index.values() for p in paths]
+        assert len(all_paths) == 4  # 4 file audio, 1 skippato
+
+    def test_duplicates_appended(self, tmp_path: Path):
+        # Due file con stesso token set → stessa key, due path
+        (tmp_path / "sub1").mkdir()
+        (tmp_path / "sub2").mkdir()
+        (tmp_path / "sub1" / "Hot Sauce.mp3").touch()
+        (tmp_path / "sub2" / "Hot Sauce.mp3").touch()
+        index = upgrader._scan_archive(str(tmp_path))
+        assert len(index) == 1
+        # Una sola chiave, con 2 path
+        paths = list(index.values())[0]
+        assert len(paths) == 2
+
+    def test_nonexistent_dir_returns_empty(self, tmp_path: Path):
+        assert upgrader._scan_archive(str(tmp_path / "nope")) == {}
+
+    def test_empty_stems_skipped(self, tmp_path: Path):
+        # File il cui stem produce zero token utili (solo caratteri corti) → skip
+        (tmp_path / "a.mp3").touch()
+        (tmp_path / "Real Track Name.mp3").touch()
+        index = upgrader._scan_archive(str(tmp_path))
+        # Solo "Real Track Name.mp3" ha token >=3 chars
+        all_paths = [p for paths in index.values() for p in paths]
+        assert len(all_paths) == 1
+        assert all_paths[0].name == "Real Track Name.mp3"
+
+
+# ============================================================
+# _find_candidates
+# ============================================================
+class TestFindCandidates:
+    def _fake_index(self, tmp_path: Path, entries: list) -> dict:
+        """Helper: crea file (touch) e ritorna un index manuale."""
+        index: dict = {}
+        for name in entries:
+            p = tmp_path / name
+            p.touch()
+            tokens = upgrader._normalize_stem(p.stem)
+            key = upgrader._tokens_to_key(tokens)
+            index.setdefault(key, []).append(p)
+        return index
+
+    def test_ranking_bitrate_desc_then_similarity_desc(self, tmp_path: Path):
+        # 3 candidati: variamo bitrate + similarity per verificare l'ordine
+        #   a: sim alta (0.75), bitrate basso (128)
+        #   b: sim media (0.5), bitrate alto (320)
+        #   c: sim alta (0.75), bitrate medio (192)
+        # Ordine atteso: b(320) > c(192, sim 0.75) > a(128)
+        idx = self._fake_index(tmp_path, [
+            "Artist - Hot Sauce.mp3",             # a: 3 token comuni su 4 = 0.75
+            "Different Song Boombox.mp3",         # b: 1 su 5 = 0.2  (troppo bassa, filtrato)
+            "Artist Hot Sauce Extended.mp3",      # c: 3 su 4 = 0.75
+        ])
+        # Target: "Artist Hot Sauce" → tokens = {artist, hot, sauce}
+        target = "Artist Hot Sauce"
+
+        # Mock bitrate: mappa nome → kbps
+        def fake_bitrate(p):
+            n = Path(p).name
+            if n == "Artist - Hot Sauce.mp3":       return 128
+            if n == "Different Song Boombox.mp3":   return 320
+            if n == "Artist Hot Sauce Extended.mp3": return 192
+            return 0
+
+        with patch.object(upgrader, "get_bitrate", side_effect=fake_bitrate):
+            results = upgrader._find_candidates(target, idx, min_similarity=0.3)
+
+        # "b" viene filtrato (sim 1/5 = 0.2 < 0.3 min); restano a e c
+        assert len(results) == 2
+        # c (bitrate 192) prima di a (bitrate 128)
+        assert results[0][0].name == "Artist Hot Sauce Extended.mp3"
+        assert results[1][0].name == "Artist - Hot Sauce.mp3"
+
+    def test_below_threshold_filtered(self, tmp_path: Path):
+        # Un solo candidato con similarity ~ 1/5 = 0.2 → sotto default 0.5 → escluso
+        idx = self._fake_index(tmp_path, [
+            "Foo Bar Baz Qux Extra.mp3",
+        ])
+        with patch.object(upgrader, "get_bitrate", return_value=320):
+            results = upgrader._find_candidates("Hot Sauce", idx)  # solo "hot"/"sauce"
+        assert results == []
+
+    def test_exact_match_returned(self, tmp_path: Path):
+        idx = self._fake_index(tmp_path, [
+            "Hot Sauce Extended.mp3",
+        ])
+        with patch.object(upgrader, "get_bitrate", return_value=320):
+            results = upgrader._find_candidates("Hot Sauce Extended", idx)
+        assert len(results) == 1
+        assert results[0][1] == 1.0  # perfect Jaccard
+        assert results[0][2] == 320

webui/css/style.css

@@ -151,6 +151,9 @@ button, input, select, textarea { font-family: inherit; font-size: inherit; }
   flex-direction: column;
   padding: 24px 12px;
   border-right: 1px solid var(--border);
+  height: 100vh;
+  min-height: 0;  /* consente ai flex children di rimpicciolirsi sotto il contenuto */
+  overflow: hidden;
 }
 
 .brand {
@@ -192,7 +195,17 @@ button, input, select, textarea { font-family: inherit; font-size: inherit; }
   flex-direction: column;
   gap: 2px;
   flex: 1;
+  min-height: 0;    /* per far funzionare overflow su flex child */
+  overflow-y: auto; /* scrolla se ci sono troppi tab e la finestra è corta */
+  overflow-x: hidden;
+  scrollbar-width: thin;
 }
+.nav::-webkit-scrollbar { width: 6px; }
+.nav::-webkit-scrollbar-thumb {
+  background: var(--bg-input);
+  border-radius: 3px;
+}
+.nav::-webkit-scrollbar-thumb:hover { background: var(--bg-input-hover); }
 
 .nav-item {
   display: flex;
@@ -687,6 +700,7 @@ input[type="number"]::-webkit-inner-spin-button {
 .percent.green { color: var(--green-text); }
 .percent.blue { color: var(--blue-text); }
 .percent.pink { color: var(--pink-hover); }
+.percent.purple { color: var(--purple-text); }
 
 .progress {
   width: 100%;
@@ -715,6 +729,10 @@ input[type="number"]::-webkit-inner-spin-button {
   background: linear-gradient(90deg, var(--pink), var(--pink-hover));
 }
 
+.progress-fill.purple {
+  background: linear-gradient(90deg, var(--purple), var(--purple-hover));
+}
+
 /* ===============================
    LOG BOX
    =============================== */
@@ -1680,8 +1698,21 @@ input[type="number"]::-webkit-inner-spin-button {
 }
 .beatport-table .col-pos   { width: 40px; color: var(--text-3); font-variant-numeric: tabular-nums; }
 .beatport-table .col-dur   { width: 70px; color: var(--text-2); font-variant-numeric: tabular-nums; text-align: right; }
+.beatport-table .col-date  { width: 100px; color: var(--text-2); font-variant-numeric: tabular-nums; font-size: 12px; white-space: nowrap; }
 .beatport-table .col-state { width: 130px; font-size: 12px; }
 
+.beatport-table thead th.sortable {
+  cursor: pointer;
+  user-select: none;
+  transition: color 0.15s ease;
+}
+.beatport-table thead th.sortable:hover { color: var(--text); }
+.beatport-table thead th .sort-arrow {
+  font-size: 10px;
+  margin-left: 4px;
+  color: var(--indigo-text);
+}
+
 .beatport-table input[type="checkbox"] {
   width: 16px;
   height: 16px;
@@ -1708,3 +1739,380 @@ input[type="number"]::-webkit-inner-spin-button {
   .hint-inline { margin-left: 0; }
   .beatport-table .col-state { width: 110px; }
 }
+
+/* ===============================
+   UPGRADE — picker modal (match locale)
+   =============================== */
+.modal-body.upgrade-picker-body {
+  /* Override del default .modal-body (mono + pre-wrap): qui è UI, non log */
+  font-family: inherit;
+  font-size: 13px;
+  color: var(--text);
+  white-space: normal;
+  user-select: none;
+}
+
+/* Modal picker: più largo dei modal standard + footer con wrap
+   per far entrare i 4 bottoni senza troncare */
+#upgradePickerModal .modal {
+  min-width: 620px;
+  max-width: 780px;
+}
+#upgradePickerModal .modal-foot {
+  flex-wrap: wrap;
+  justify-content: flex-end;
+}
+.modal-sub {
+  font-size: 12px;
+  color: var(--text-2);
+  margin-bottom: 12px;
+  word-break: break-word;
+}
+.upgrade-picker-list {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  max-height: 380px;
+  overflow-y: auto;
+}
+.upgrade-picker-row {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  padding: 10px 12px;
+  border: 1px solid var(--border);
+  border-radius: var(--r-md, 10px);
+  cursor: pointer;
+  transition: border-color 0.15s ease, background 0.15s ease;
+  background: var(--bg-input, transparent);
+}
+.upgrade-picker-row:hover { border-color: var(--text-2); }
+.upgrade-picker-row.selected {
+  border-color: var(--blue, #3b82f6);
+  background: rgba(59, 130, 246, 0.08);
+}
+.upgrade-picker-row input[type="radio"] {
+  margin-top: 3px;
+  cursor: pointer;
+}
+.upgrade-picker-info {
+  flex: 1;
+  min-width: 0;
+}
+.upgrade-picker-play {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+.upgrade-preview-btn {
+  width: 34px;
+  height: 34px;
+  border-radius: 50%;
+  border: 1px solid var(--border);
+  background: var(--bg-input, transparent);
+  color: var(--text);
+  font-size: 13px;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  margin-left: 6px;
+  transition: background 0.15s ease, transform 0.1s ease;
+}
+.upgrade-preview-btn:hover { background: var(--bg-input-hover, rgba(255,255,255,0.05)); }
+.upgrade-preview-btn.playing {
+  background: var(--green, #1DB954);
+  color: #000;
+  border-color: var(--green, #1DB954);
+}
+.upgrade-picker-title {
+  font-weight: 600;
+  color: var(--text);
+  word-break: break-word;
+}
+.upgrade-picker-meta {
+  font-size: 12px;
+  color: var(--text-2);
+  margin-top: 3px;
+  font-variant-numeric: tabular-nums;
+}
+.upgrade-picker-path {
+  font-size: 11px;
+  color: var(--text-3);
+  margin-top: 2px;
+  word-break: break-all;
+  font-family: "SF Mono", Menlo, Consolas, monospace;
+}
+
+/* ===============================
+   DEDUP tab (audio duplicati)
+   =============================== */
+.dedup-summary {
+  font-size: 14px;
+  color: var(--text-2);
+  font-weight: 600;
+}
+
+.dedup-group-card {
+  padding: 14px 16px;
+}
+
+.dedup-group-header {
+  font-size: 13px;
+  color: var(--text-2);
+  margin-bottom: 10px;
+  padding-bottom: 8px;
+  border-bottom: 1px solid var(--border);
+}
+.dedup-group-header strong {
+  color: var(--text-1);
+  font-size: 14px;
+}
+.dedup-fp {
+  font-family: "SF Mono", Menlo, Consolas, monospace;
+  color: var(--text-3);
+  font-size: 11px;
+}
+
+.dedup-file-list {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.dedup-file-row {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 8px 10px;
+  border-radius: 8px;
+  background: var(--bg-elev);
+  transition: background 0.15s ease;
+}
+.dedup-file-row:hover {
+  background: var(--bg-elev-hover, var(--bg-elev));
+}
+
+.dedup-file-check {
+  flex-shrink: 0;
+  width: 16px;
+  height: 16px;
+  cursor: pointer;
+  accent-color: var(--red);
+}
+.dedup-file-check:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+.dedup-file-info {
+  flex: 1;
+  min-width: 0;
+}
+
+.dedup-file-title {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--text-1);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.dedup-file-meta {
+  font-size: 11px;
+  color: var(--text-3);
+  margin-top: 2px;
+  font-variant-numeric: tabular-nums;
+}
+
+.dedup-file-path {
+  font-size: 10px;
+  color: var(--text-3);
+  margin-top: 2px;
+  font-family: "SF Mono", Menlo, Consolas, monospace;
+  word-break: break-all;
+  opacity: 0.6;
+}
+
+.dedup-file-play {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+}
+
+/* File "da tenere" (bitrate massimo del gruppo) — verde */
+.dedup-keep {
+  background: var(--green-dim);
+  border-left: 3px solid var(--green);
+}
+.dedup-keep .dedup-file-title {
+  color: var(--green-text);
+}
+
+.dedup-keep-badge {
+  display: inline-block;
+  padding: 2px 8px;
+  border-radius: 6px;
+  background: var(--green);
+  color: white;
+  font-size: 10px;
+  font-weight: 800;
+  letter-spacing: 0.5px;
+  margin-right: 6px;
+  vertical-align: middle;
+}
+
+.dedup-footer-bar {
+  position: sticky;
+  bottom: 0;
+  z-index: 5;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 12px;
+  padding: 12px 16px;
+  margin-top: 12px;
+  border-radius: var(--r-md);
+  background: var(--bg-card);
+  box-shadow: 0 -4px 12px rgba(0, 0, 0, 0.15);
+  border: 1px solid var(--border);
+}
+
+/* Lista risultati Dedup con scroll interno: l'header (hero sticky) e il
+   footer restano visibili anche se ci sono centinaia di gruppi. */
+.dedup-groups-scroll {
+  max-height: 55vh;
+  overflow-y: auto;
+  padding-right: 6px;  /* spazio per la scrollbar sul bordo */
+}
+
+/* ===============================
+   CATALOGA tab
+   =============================== */
+.catalog-summary {
+  font-size: 14px;
+  color: var(--text-2);
+  font-weight: 600;
+}
+
+/* Scroll container per la tabella (analogo a dedup-groups-scroll) */
+.catalog-scroll {
+  max-height: 55vh;
+  overflow-y: auto;
+  overflow-x: auto;
+  padding-right: 6px;
+  border: 1px solid var(--border);
+  border-radius: var(--r-md);
+  background: var(--bg-card);
+}
+
+.catalog-table {
+  width: 100%;
+  border-collapse: separate;
+  border-spacing: 0;
+  font-size: 12px;
+  color: var(--text-2);
+}
+
+.catalog-table thead th {
+  position: sticky;
+  top: 0;
+  z-index: 2;
+  background: var(--bg-card-2);
+  color: var(--text-1);
+  font-weight: 700;
+  padding: 10px 8px;
+  text-align: left;
+  font-size: 11px;
+  letter-spacing: 0.3px;
+  text-transform: uppercase;
+  border-bottom: 1px solid var(--border);
+  white-space: nowrap;
+}
+
+.catalog-table tbody td {
+  padding: 8px;
+  border-bottom: 1px solid var(--border);
+  vertical-align: middle;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 260px;
+}
+
+.catalog-table tbody tr:hover {
+  background: var(--bg-elev);
+}
+
+/* Righe senza match AcoustID: sfondo rosa tenue */
+.catalog-table tbody tr.catalog-row-unmatched {
+  background: rgba(236, 72, 153, 0.06);
+}
+.catalog-table tbody tr.catalog-row-unmatched:hover {
+  background: rgba(236, 72, 153, 0.12);
+}
+
+.catalog-col-check { width: 30px; text-align: center; }
+.catalog-col-year { width: 60px; text-align: center; font-variant-numeric: tabular-nums; }
+.catalog-col-status { width: 110px; }
+
+.catalog-file-cell {
+  display: block;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--text-1);
+  font-weight: 500;
+}
+
+.catalog-check {
+  width: 16px;
+  height: 16px;
+  cursor: pointer;
+  accent-color: var(--purple);
+}
+
+.catalog-status-badge {
+  display: inline-block;
+  padding: 2px 8px;
+  border-radius: 10px;
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 0.3px;
+  text-transform: uppercase;
+}
+.catalog-status-badge.ok {
+  background: var(--purple-dim);
+  color: var(--purple-text);
+}
+.catalog-status-badge.warn {
+  background: var(--amber-dim, rgba(245, 158, 11, 0.15));
+  color: var(--amber-text);
+}
+.catalog-status-badge.err {
+  background: rgba(220, 38, 38, 0.15);
+  color: var(--red);
+}
+.catalog-status-badge.busy {
+  background: var(--bg-input);
+  color: var(--text-3);
+}
+
+.catalog-footer-bar {
+  position: sticky;
+  bottom: 0;
+  z-index: 5;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 12px;
+  padding: 12px 16px;
+  margin-top: 12px;
+  border-radius: var(--r-md);
+  background: var(--bg-card);
+  box-shadow: 0 -4px 12px rgba(0, 0, 0, 0.15);
+  border: 1px solid var(--border);
+}
+

webui/index.html

@@ -33,6 +33,10 @@
           <span class="nav-icon">🎧</span>
           <span>Beatport</span>
         </button>
+        <button class="nav-item" data-view="traxsource" data-feature="audio">
+          <span class="nav-icon">▲</span>
+          <span>Traxsource</span>
+        </button>
         <button class="nav-item" data-view="spotify" data-feature="audio">
           <span class="nav-icon">🟢</span>
           <span>Spotify</span>
@@ -41,6 +45,22 @@
           <span class="nav-icon">▶</span>
           <span>YouTube</span>
         </button>
+        <button class="nav-item" data-view="convert" data-feature="audio">
+          <span class="nav-icon">🔄</span>
+          <span>Converti</span>
+        </button>
+        <button class="nav-item" data-view="dedup" data-feature="audio">
+          <span class="nav-icon">🗑</span>
+          <span>Dedup</span>
+        </button>
+        <button class="nav-item" data-view="catalog" data-feature="audio">
+          <span class="nav-icon">📅</span>
+          <span>Cataloga</span>
+        </button>
+        <button class="nav-item" data-view="flatten" data-feature="audio">
+          <span class="nav-icon">📤</span>
+          <span>Appiattisci</span>
+        </button>
         <button class="nav-item" data-view="upgrade" data-feature="upgrade">
           <span class="nav-icon">⚡</span>
           <span>Upgrade</span>
@@ -264,6 +284,23 @@
             <label class="field-label">Soglia HQ (kbps)</label>
             <input type="number" id="upThreshold" class="input pill input-sm" value="310" />
           </div>
+
+          <div class="field">
+            <label class="field-label">Cartella archivio (opzionale)</label>
+            <div class="row">
+              <div class="path-display empty" id="upArchivePathDisplay">Nessuna cartella</div>
+              <button class="btn btn-ghost pill btn-sm" id="upArchiveBrowseBtn">📂 Sfoglia</button>
+              <button class="btn btn-ghost pill btn-sm" id="upArchiveClearBtn" hidden>Rimuovi</button>
+            </div>
+            <label style="display:flex;gap:6px;align-items:center;margin-top:8px;font-size:13px;color:var(--text-2);">
+              <input type="checkbox" id="upArchiveAutoPick"/>
+              <span>Scelta automatica se ci sono più match (usa quello a bitrate più alto)</span>
+            </label>
+            <div class="hint">
+              <span class="hint-ico">ⓘ</span>
+              <div>Se selezionata, l'app cerca versioni HQ del brano nella tua libreria locale prima di scaricare da YouTube. In caso di match multipli scegli tu quale usare — oppure attiva "Scelta automatica" per non fermarti.</div>
+            </div>
+          </div>
         </div>
 
         <div class="card actions">
@@ -534,6 +571,24 @@
             </div>
           </div>
 
+          <div class="field">
+            <label class="field-label">Cookies da browser (bypass 403 YouTube)</label>
+            <div class="row">
+              <select id="cookiesBrowserSelect" class="input pill" style="max-width:220px;">
+                <option value="">Nessuno</option>
+                <option value="chrome">Chrome</option>
+                <option value="safari">Safari</option>
+                <option value="firefox">Firefox</option>
+                <option value="edge">Edge</option>
+                <option value="brave">Brave</option>
+              </select>
+            </div>
+            <div class="hint">
+              <span class="hint-ico">ⓘ</span>
+              <div>Alcuni video YouTube (musica protetta, region-lock, età) danno HTTP 403 senza cookies autenticati. Selezionando un browser, l'app legge i cookies dal tuo profilo — richiede che tu sia loggato su YouTube in quel browser. Se hai anche cookies.txt sopra, ha priorità il file.</div>
+            </div>
+          </div>
+
           <div class="field">
             <label class="field-label">Cartella output predefinita</label>
             <div class="row">
@@ -543,6 +598,24 @@
           </div>
         </div>
 
+        <h2 class="section-label">Log</h2>
+        <div class="card">
+          <div class="field">
+            <label class="field-label">Cartella dei log</label>
+            <div class="row">
+              <div class="path-display" id="logPathDisplay" style="flex:1;">—</div>
+              <button class="btn btn-ghost pill btn-sm" id="openLogFolderBtn">📁 Apri cartella</button>
+            </div>
+            <div class="hint">
+              <span class="hint-ico">ⓘ</span>
+              <div>
+                L'app scrive un log giornaliero (<code>app.log</code>) con rotazione automatica (7 giorni).
+                Utile per debug: incluide stdout, stderr, log delle tab e traceback.
+              </div>
+            </div>
+          </div>
+        </div>
+
         <h2 class="section-label">Aspetto</h2>
         <div class="card">
           <div class="field">
@@ -892,10 +965,11 @@
                 <tr>
                   <th class="col-check"><input type="checkbox" id="beatport-select-all" /></th>
                   <th class="col-cover"></th>
-                  <th class="col-pos">#</th>
-                  <th>Artista</th>
-                  <th>Titolo (Mix)</th>
-                  <th class="col-dur">Durata</th>
+                  <th class="col-pos sortable" data-sort="position">#</th>
+                  <th class="sortable" data-sort="artists">Artista</th>
+                  <th class="sortable" data-sort="title">Titolo (Mix)</th>
+                  <th class="col-dur sortable" data-sort="duration_sec">Durata</th>
+                  <th class="col-date sortable" data-sort="release_date">Data</th>
                   <th class="col-state">Stato</th>
                 </tr>
               </thead>
@@ -919,6 +993,64 @@
         </div>
       </section>
 
+      <!-- ===== VIEW: TRAXSOURCE ===== -->
+      <section class="view" id="view-traxsource">
+        <header class="hero hero-purple">
+          <div class="hero-content">
+            <div class="hero-eyebrow purple">TRAXSOURCE CHARTS</div>
+            <h1 class="hero-title">Top 100 Traxsource per genere</h1>
+            <p class="hero-subtitle">La classifica mensile ufficiale. Scarica in un click con tag ID3 completi (label, cover art, genere).</p>
+          </div>
+          <div class="hero-deco">▲</div>
+        </header>
+
+        <h2 class="section-label">Genere</h2>
+        <div class="card">
+          <div class="beatport-header">
+            <select id="traxsource-genre" class="input pill"></select>
+            <button class="btn btn-primary pill" id="traxsource-load-btn">
+              <span class="ico">↓</span> Carica Top 100
+            </button>
+            <span class="hint-inline">Shift+click per bypassare la cache</span>
+          </div>
+          <div id="traxsource-status" class="beatport-status"></div>
+          <div id="traxsource-output-info" class="beatport-output-info"></div>
+        </div>
+
+        <div class="card beatport-table-card">
+          <div class="beatport-table-wrap">
+            <table id="traxsource-table" class="beatport-table" hidden>
+              <thead>
+                <tr>
+                  <th class="col-check"><input type="checkbox" id="traxsource-select-all" /></th>
+                  <th class="col-cover"></th>
+                  <th class="col-pos sortable" data-sort="position">#</th>
+                  <th class="sortable" data-sort="artists">Artista</th>
+                  <th class="sortable" data-sort="title">Titolo (Mix)</th>
+                  <th class="sortable" data-sort="label">Label</th>
+                  <th class="col-state">Stato</th>
+                </tr>
+              </thead>
+              <tbody></tbody>
+            </table>
+          </div>
+          <div class="beatport-toolbar" id="traxsource-toolbar" hidden>
+            <span class="counter" id="traxsource-selected-count">0/0 selezionati</span>
+            <button class="btn btn-primary pill" id="traxsource-download-btn" disabled>
+              <span class="ico">▶</span> Scarica selezionati
+            </button>
+            <button class="btn btn-danger pill" id="traxsource-stop-btn" hidden>
+              <span class="ico">◼</span> Interrompi
+            </button>
+          </div>
+        </div>
+
+        <h2 class="section-label">Log</h2>
+        <div class="card log-card">
+          <div class="log" id="traxsource-log"></div>
+        </div>
+      </section>
+
       <!-- ===== VIEW: SPOTIFY SEARCH ===== -->
       <section class="view" id="view-spotify">
         <header class="hero hero-indigo">
@@ -953,11 +1085,12 @@
                 <tr>
                   <th class="col-check"><input type="checkbox" id="spotify-select-all" checked /></th>
                   <th class="col-cover"></th>
-                  <th class="col-pos">#</th>
-                  <th>Artista</th>
-                  <th>Titolo</th>
-                  <th>Album</th>
-                  <th class="col-dur">Durata</th>
+                  <th class="col-pos sortable" data-sort="position">#</th>
+                  <th class="sortable" data-sort="artists">Artista</th>
+                  <th class="sortable" data-sort="name">Titolo</th>
+                  <th class="sortable" data-sort="album">Album</th>
+                  <th class="col-dur sortable" data-sort="duration_sec">Durata</th>
+                  <th class="col-date sortable" data-sort="release_date">Data</th>
                   <th class="col-state"></th>
                 </tr>
               </thead>
@@ -1011,10 +1144,11 @@
                 <tr>
                   <th class="col-check"><input type="checkbox" id="youtube-select-all" checked /></th>
                   <th class="col-cover"></th>
-                  <th class="col-pos">#</th>
-                  <th>Titolo video</th>
-                  <th>Canale</th>
-                  <th class="col-dur">Durata</th>
+                  <th class="col-pos sortable" data-sort="position">#</th>
+                  <th class="sortable" data-sort="title">Titolo video</th>
+                  <th class="sortable" data-sort="channel">Canale</th>
+                  <th class="col-dur sortable" data-sort="duration_sec">Durata</th>
+                  <th class="col-date sortable" data-sort="release_date">Data</th>
                   <th class="col-state"></th>
                 </tr>
               </thead>
@@ -1038,6 +1172,331 @@
         </div>
       </section>
 
+      <!-- ===== VIEW: CONVERTI (WAV -> MP3) ===== -->
+      <section class="view" id="view-convert">
+        <header class="hero hero-purple">
+          <div class="hero-content">
+            <div class="hero-eyebrow purple">WAV → MP3</div>
+            <h1 class="hero-title">Converti file WAV in MP3</h1>
+            <p class="hero-subtitle">Bitrate configurabile, CBR o VBR, output accanto al file o in cartella custom.</p>
+          </div>
+          <div class="hero-deco">🔄</div>
+        </header>
+
+        <h2 class="section-label">Sorgente</h2>
+        <div class="card">
+          <div class="beatport-header">
+            <button id="convert-pick-files" class="btn btn-primary pill">📄 Scegli file .wav</button>
+            <button id="convert-pick-folder" class="btn btn-ghost pill">📁 Scegli cartella</button>
+            <button id="convert-clear" class="btn btn-ghost pill">Svuota</button>
+          </div>
+
+          <div class="beatport-header" style="margin-top:12px;gap:16px;">
+            <label style="display:flex;gap:6px;align-items:center;color:var(--text-2);font-size:13px;">
+              Bitrate:
+              <select id="convert-bitrate" class="input pill input-sm">
+                <option value="128">128 kbps</option>
+                <option value="192">192 kbps</option>
+                <option value="256">256 kbps</option>
+                <option value="320" selected>320 kbps</option>
+              </select>
+            </label>
+            <label style="display:flex;gap:6px;align-items:center;color:var(--text-2);font-size:13px;">
+              <input type="checkbox" id="convert-vbr" />
+              <span>VBR (qualità variabile)</span>
+            </label>
+          </div>
+
+          <div class="beatport-header" style="margin-top:12px;gap:12px;">
+            <label style="display:flex;gap:6px;align-items:center;color:var(--text-2);font-size:13px;">
+              <input type="radio" name="convert-out" id="convert-out-same" checked />
+              <span>Accanto al file originale</span>
+            </label>
+            <label style="display:flex;gap:6px;align-items:center;color:var(--text-2);font-size:13px;">
+              <input type="radio" name="convert-out" id="convert-out-custom" />
+              <span>Cartella custom:</span>
+            </label>
+            <button id="convert-out-browse" class="btn btn-ghost pill btn-sm" disabled>Sfoglia…</button>
+            <span id="convert-out-path" class="beatport-output-info" style="margin:0;"></span>
+          </div>
+
+          <div id="convert-status" class="beatport-status"></div>
+        </div>
+
+        <div class="card beatport-table-card" id="convert-table-wrap" hidden>
+          <div class="beatport-table-wrap">
+            <table class="beatport-table" id="convert-table">
+              <thead>
+                <tr>
+                  <th class="col-check"><input type="checkbox" id="convert-select-all" checked /></th>
+                  <th class="col-pos">#</th>
+                  <th>File</th>
+                  <th class="col-state">Stato</th>
+                </tr>
+              </thead>
+              <tbody id="convert-tbody"></tbody>
+            </table>
+          </div>
+          <div class="beatport-toolbar" id="convert-toolbar">
+            <span class="counter" id="convert-selected-count">0/0 selezionati</span>
+            <button id="convert-run-btn" class="btn btn-primary pill" disabled>
+              <span class="ico">▶</span> Converti selezionati
+            </button>
+            <button id="convert-stop-btn" class="btn btn-danger pill" hidden>
+              <span class="ico">◼</span> Interrompi
+            </button>
+          </div>
+        </div>
+
+        <h2 class="section-label">Log</h2>
+        <div class="card log-card">
+          <div class="log" id="convert-log"></div>
+        </div>
+      </section>
+
+      <!-- ===== VIEW: DEDUP (audio duplicati via Chromaprint) ===== -->
+      <section class="view" id="view-dedup">
+        <header class="hero hero-red">
+          <div class="hero-content">
+            <div class="hero-eyebrow red">DEDUP AUDIO</div>
+            <h1 class="hero-title">Trova e rimuovi duplicati audio</h1>
+            <p class="hero-subtitle">Audio fingerprinting via Chromaprint: riconosce brani identici indipendentemente dal bitrate, dal formato o dai tag.</p>
+          </div>
+          <div class="hero-deco">🗑</div>
+        </header>
+
+        <h2 class="section-label">Cartella</h2>
+        <div class="card">
+          <div class="beatport-header">
+            <button id="dedup-pick-folder" class="btn btn-primary pill">📁 Scegli cartella</button>
+            <button id="dedup-start-btn" class="btn btn-primary pill" disabled>
+              <span class="ico">▶</span> Scansiona
+            </button>
+            <button id="dedup-stop-btn" class="btn btn-danger pill" hidden>
+              <span class="ico">◼</span> Interrompi
+            </button>
+          </div>
+          <div class="beatport-header" style="margin-top:12px;gap:16px;">
+            <span id="dedup-path-display" class="beatport-output-info" style="margin:0;">Nessuna cartella selezionata</span>
+          </div>
+          <div class="beatport-header" style="margin-top:12px;gap:16px;">
+            <label style="display:flex;gap:6px;align-items:center;color:var(--text-2);font-size:13px;">
+              <input type="checkbox" id="dedup-recursive" checked />
+              <span>Ricerca ricorsiva (include sottocartelle)</span>
+            </label>
+          </div>
+          <div class="beatport-header" style="margin-top:12px;gap:16px;">
+            <label style="display:flex;gap:8px;align-items:center;color:var(--text-2);font-size:13px;">
+              <span>Metodo:</span>
+              <select id="dedup-method" class="input" style="padding:4px 8px;font-size:13px;">
+                <option value="fingerprint">Audio fingerprint (preciso, lento)</option>
+                <option value="filename">Nome file (veloce, meno preciso)</option>
+              </select>
+            </label>
+          </div>
+          <div id="dedup-status" class="beatport-status"></div>
+        </div>
+
+        <h2 class="section-label">Progresso</h2>
+        <div class="card">
+          <div class="progress">
+            <div class="progress-bar"><div id="dedupProgressFill" class="progress-fill pink"></div></div>
+            <div class="progress-meta">
+              <span id="dedupPercent" class="percent pink">0%</span>
+              <span id="dedupCounter">In attesa</span>
+            </div>
+          </div>
+        </div>
+
+        <h2 class="section-label">Risultati</h2>
+        <div class="card" id="dedup-summary-card" hidden>
+          <div class="dedup-summary" id="dedup-summary-line"></div>
+        </div>
+        <div id="dedup-groups-wrap" class="dedup-groups-scroll"></div>
+
+        <div class="dedup-footer-bar" id="dedup-footer-bar" hidden>
+          <span class="counter" id="dedup-selected-count">0 file da cancellare</span>
+          <button id="dedup-select-suggested-btn" class="btn btn-ghost pill">
+            ✓ Seleziona tutti i consigliati
+          </button>
+          <button id="dedup-trash-btn" class="btn btn-danger pill" disabled>
+            <span class="ico">🗑</span> Sposta in cestino
+          </button>
+        </div>
+
+        <h2 class="section-label">Log</h2>
+        <div class="card log-card">
+          <div class="log" id="dedup-log"></div>
+        </div>
+      </section>
+
+      <!-- ===== VIEW: CATALOGA (AcoustID -> <Anno>/<Genere>/) ===== -->
+      <section class="view" id="view-catalog">
+        <header class="hero hero-purple">
+          <div class="hero-content">
+            <div class="hero-eyebrow purple">CATALOGA</div>
+            <h1 class="hero-title">Organizza per anno e genere</h1>
+            <p class="hero-subtitle">Identifica ogni brano via audio fingerprint (Chromaprint + AcoustID) e sposta i file in <code>&lt;Anno&gt;/&lt;Genere&gt;/</code>.</p>
+          </div>
+          <div class="hero-deco">📅</div>
+        </header>
+
+        <h2 class="section-label">Sorgente</h2>
+        <div class="card">
+          <div class="beatport-header">
+            <button id="catalog-pick-source" class="btn btn-primary pill">📁 Cartella input</button>
+            <button id="catalog-start-btn" class="btn btn-primary pill" disabled>
+              <span class="ico">▶</span> Scansiona
+            </button>
+            <button id="catalog-stop-btn" class="btn btn-danger pill" hidden>
+              <span class="ico">◼</span> Interrompi
+            </button>
+          </div>
+          <div class="beatport-header" style="margin-top:12px;gap:16px;">
+            <span id="catalog-source-display" class="beatport-output-info" style="margin:0;">Nessuna cartella selezionata</span>
+          </div>
+          <div class="beatport-header" style="margin-top:12px;gap:16px;">
+            <label style="display:flex;gap:6px;align-items:center;color:var(--text-2);font-size:13px;">
+              <input type="checkbox" id="catalog-recursive" checked />
+              <span>Ricerca ricorsiva (include sottocartelle)</span>
+            </label>
+          </div>
+        </div>
+
+        <h2 class="section-label">Destinazione</h2>
+        <div class="card">
+          <div class="beatport-header">
+            <button id="catalog-pick-target" class="btn btn-ghost pill">📁 Cartella destinazione</button>
+            <button id="catalog-clear-target" class="btn btn-ghost pill btn-sm">Usa la stessa della sorgente</button>
+          </div>
+          <div class="beatport-header" style="margin-top:12px;gap:16px;">
+            <span id="catalog-target-display" class="beatport-output-info" style="margin:0;">Uguale alla sorgente (in-place)</span>
+          </div>
+          <div class="beatport-header" style="margin-top:12px;gap:12px;">
+            <label style="display:flex;gap:8px;align-items:center;color:var(--text-2);font-size:13px;">
+              <span>Struttura cartelle:</span>
+              <select id="catalog-layout" class="input" style="padding:4px 8px;font-size:13px;">
+                <option value="year_genre">&lt;Anno&gt;/&lt;Genere&gt;/</option>
+                <option value="genre_year">&lt;Genere&gt;/&lt;Anno&gt;/</option>
+              </select>
+            </label>
+          </div>
+          <div class="hint" style="margin-top:10px;">
+            <span class="hint-ico">ⓘ</span>
+            <div>
+              Se lasci vuota la destinazione i file vengono organizzati <strong>in-place</strong> nella cartella sorgente.
+              Le sottocartelle vengono create automaticamente in base allo schema scelto.
+              File senza match finiscono in <code>Unknown Year</code> / <code>Unknown Genre</code>.
+            </div>
+          </div>
+          <div id="catalog-status" class="beatport-status"></div>
+        </div>
+
+        <h2 class="section-label">Progresso</h2>
+        <div class="card">
+          <div class="progress">
+            <div class="progress-bar"><div id="catalogProgressFill" class="progress-fill purple"></div></div>
+            <div class="progress-meta">
+              <span id="catalogPercent" class="percent purple">0%</span>
+              <span id="catalogCounter">In attesa</span>
+            </div>
+          </div>
+        </div>
+
+        <h2 class="section-label">Risultati</h2>
+        <div class="card" id="catalog-summary-card" hidden>
+          <div class="catalog-summary" id="catalog-summary-line"></div>
+        </div>
+        <div id="catalog-table-wrap" class="catalog-scroll" hidden>
+          <table class="catalog-table">
+            <thead>
+              <tr>
+                <th class="catalog-col-check">
+                  <input type="checkbox" id="catalog-select-all" title="Seleziona/deseleziona tutti"/>
+                </th>
+                <th class="catalog-col-file">File</th>
+                <th class="catalog-col-artist">Artista</th>
+                <th class="catalog-col-title">Titolo</th>
+                <th class="catalog-col-year">Anno</th>
+                <th class="catalog-col-genre">Genere</th>
+                <th class="catalog-col-status">Stato</th>
+              </tr>
+            </thead>
+            <tbody id="catalog-table-body"></tbody>
+          </table>
+        </div>
+
+        <div class="catalog-footer-bar" id="catalog-footer-bar" hidden>
+          <span class="counter" id="catalog-selected-count">0 file selezionati</span>
+          <button id="catalog-move-btn" class="btn btn-danger pill" disabled>
+            <span class="ico">📦</span> Sposta selezionati
+          </button>
+        </div>
+
+        <h2 class="section-label">Log</h2>
+        <div class="card log-card">
+          <div class="log" id="catalog-log"></div>
+        </div>
+      </section>
+
+      <!-- ===== VIEW: FLATTEN ===== -->
+      <section class="view" id="view-flatten">
+        <header class="hero hero-blue">
+          <div class="hero-content">
+            <div class="hero-eyebrow blue">APPIATTISCI</div>
+            <h1 class="hero-title">Sposta tutti i brani nella cartella padre</h1>
+            <p class="hero-subtitle">
+              Scansiona ricorsivamente ogni sotto-cartella e sposta i file audio nella root.
+              Utile come "undo" della catalogazione o per unire archivi frammentati.
+            </p>
+          </div>
+          <div class="hero-deco">📤</div>
+        </header>
+
+        <h2 class="section-label">Cartella</h2>
+        <div class="card">
+          <div class="beatport-header">
+            <button id="flatten-pick-folder" class="btn btn-primary pill">📁 Scegli cartella</button>
+            <button id="flatten-start-btn" class="btn btn-blue pill" disabled>▶ Sposta tutto nella root</button>
+            <button id="flatten-stop-btn" class="btn btn-danger pill" hidden>■ Interrompi</button>
+          </div>
+          <div class="beatport-header" style="margin-top:12px;">
+            <span id="flatten-path-display" class="beatport-output-info" style="margin:0;">Nessuna cartella selezionata</span>
+          </div>
+          <div class="beatport-header" style="margin-top:12px;">
+            <label style="display:flex;gap:6px;align-items:center;color:var(--text-2);font-size:13px;">
+              <input type="checkbox" id="flatten-remove-empty" checked />
+              <span>Elimina le sotto-cartelle rimaste vuote dopo lo spostamento</span>
+            </label>
+          </div>
+          <div class="hint" style="margin-top:10px;">
+            <span class="hint-ico">ⓘ</span>
+            <div>
+              Ogni file con estensione audio (mp3, m4a, wav, flac...) nelle sotto-cartelle
+              verrà spostato nella cartella padre. In caso di nomi duplicati viene aggiunto
+              suffisso <code>_1</code>, <code>_2</code>... (nessun overwrite).
+            </div>
+          </div>
+          <div id="flatten-status" class="beatport-status"></div>
+        </div>
+
+        <h2 class="section-label">Progresso</h2>
+        <div class="card">
+          <div class="progress">
+            <div class="progress-bar"><div id="flattenProgressFill" class="progress-fill blue"></div></div>
+            <div class="progress-meta">
+              <span id="flattenPercent" class="percent blue">0%</span>
+              <span id="flattenCounter">In attesa</span>
+            </div>
+          </div>
+        </div>
+
+        <h2 class="section-label">Log</h2>
+        <div class="card log-card">
+          <div class="log" id="flatten-log"></div>
+        </div>
+      </section>
+
     </main>
   </div>
 
@@ -1111,6 +1570,49 @@
     </div>
   </div>
 
+  <!-- ============== MODAL: Match locale Upgrade ============== -->
+  <div class="modal-backdrop" id="upgradePickerModal" hidden>
+    <div class="modal">
+      <div class="modal-head">
+        <h2>Match locali trovati</h2>
+        <button class="modal-close" id="upgradePickerCloseBtn">×</button>
+      </div>
+      <div class="modal-body upgrade-picker-body">
+        <div class="modal-sub" id="upgradePickerFilename"></div>
+        <div id="upgradePickerList" class="upgrade-picker-list"></div>
+      </div>
+      <div class="modal-foot">
+        <button class="btn btn-primary pill" id="upgradePickerUseBtn" disabled>Usa selezionato</button>
+        <button class="btn btn-ghost pill" id="upgradePickerYoutubeBtn">Cerca su YouTube</button>
+        <button class="btn btn-ghost pill" id="upgradePickerSkipBtn">Salta</button>
+        <button class="btn btn-danger pill" id="upgradePickerCancelAllBtn">■ Annulla tutto</button>
+      </div>
+    </div>
+  </div>
+
+  <!-- ============== MODAL: Cataloga — conferma spostamento ============== -->
+  <div class="modal-backdrop" id="catalogConfirmModal" hidden>
+    <div class="modal">
+      <div class="modal-head">
+        <h2>Conferma spostamento</h2>
+        <button class="modal-close" id="catalogConfirmCloseBtn">×</button>
+      </div>
+      <div class="modal-body">
+        <p id="catalogConfirmMsg">Stai per spostare N file. Procedi?</p>
+        <p class="modal-hint">
+          L'operazione riorganizza i file in sottocartelle
+          <code>&lt;Anno&gt;/&lt;Genere&gt;/</code>. E' reversibile
+          manualmente dal log ma puo' richiedere tempo su cartelle
+          grandi.
+        </p>
+      </div>
+      <div class="modal-foot">
+        <button class="btn btn-ghost pill" id="catalogConfirmCancelBtn">Annulla</button>
+        <button class="btn btn-danger pill" id="catalogConfirmProceedBtn">Sposta</button>
+      </div>
+    </div>
+  </div>
+
   <!-- ============== TOAST ============== -->
   <div class="toast" id="toast"></div>