Keep set membership across the analysis round trip

Staging a track for Platinum Notes / Mixed In Key moves it out of the folder it
was curated in, and it returns renamed and relocated. As written, that silently
dropped the track from its set or vibe playlist - the exact curation this tool
exists to protect.

Staging now captures the folder as a playlist first and records the playlists
each staged track owed a place in. Filing it back out of 'Processed' re-adds it
at its new location, then clears the record.

Matching survives the round trip in both directions it can change: Platinum
Notes appends _PN, and a track with no artist tag stages as
'Unknown Artist - Title', which reads back as a real artist. Entries therefore
carry both an artist+title key and a title-only key, precise one tried first.
Because matching is on tags rather than file content, a staged MP3 that returns
as FLAC still rejoins its set - verified end to end with a real conversion.

Also passes the full library into staging, without which a rebuilt playlist
would have contained only the returned track instead of the whole set.

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

Author: sparkly-quasar

README.md

@@ -60,6 +60,14 @@ loop:
 3. Run that folder through Platinum Notes and Mixed In Key, saving into `Processed`.
 4. **Import → "Sort the 'Processed' folder"** files them by genre automatically.
 
+Staging a track out of a set or vibe folder does **not** cost you that
+curation. Before anything moves, Sortero writes the folder out as a playlist
+and records which playlists each staged track belonged to. When the track is
+filed back out of `Processed`, it rejoins exactly those playlists at its new
+location. Matching is on artist and title, so it survives Platinum Notes
+renaming the file *and* changing its format — an MP3 that comes back as FLAC
+still lands back in its set.
+
 ## Streaming playlists
 
 Paste a Spotify or TIDAL playlist link on the **Playlists** tab and Sortero

sortero/app.py

@@ -808,8 +808,13 @@ def stage(self):
             return
         root = self.app.root_dir.get()
 
+        all_recs = self.app.recs
+
         def work(progress, log):
-            return organize.stage_for_analysis(root, recs, log=log, progress=progress)
+            # all_recs matters: the folder's *other* tracks are what the
+            # playlist is rebuilt from before these ones leave.
+            return organize.stage_for_analysis(root, recs, all_recs=all_recs,
+                                               log=log, progress=progress)
 
         def done(res):
             path, n = res

sortero/importer.py

@@ -13,6 +13,8 @@
 from .dupes import _sig, ident
 from .journal import Journal
 from .tagio import Track
+from . import membership
+from . import playlists as pl
 
 TO_PROCESS = "To Be Processed"
 PROCESSED = "Processed"
@@ -122,6 +124,7 @@ def apply(root, results, move=True, clean_spam=True, log=print, progress=None):
     todo = [x for x in results if x["dest"]]
     total = len(todo) or 1
     n = 0
+    restored = []
     for i, x in enumerate(todo):
         if progress and i % 10 == 0:
             progress(i, total)
@@ -151,10 +154,22 @@ def apply(root, results, move=True, clean_spam=True, log=print, progress=None):
                             t.set(field, None)
                     if ch and t.save():
                         j.tagged(final, ch)
+
+            # If this track was staged out of a set/vibe folder, put it back
+            # into the playlists it came from - now pointing at its new home.
+            owed = membership.claim(x["rec"])
+            for name in owed:
+                pl.append(root, name, [final])
+            if owed:
+                restored.append(x["rec"])
+                log(f"  restored to {len(owed)} playlist(s): {os.path.basename(final)}")
         except Exception as e:
             log(f"  ! {os.path.basename(src)}: {e}")
     if progress:
         progress(total, total)
+    if restored:
+        membership.release(restored)
+        log(f"restored {len(restored)} tracks to their original playlists")
     path = j.save()
     log(f"imported {n} files | journal: {path}")
     return path, n

sortero/membership.py

@@ -0,0 +1,106 @@
+"""Remember which playlists a track belonged to while it is away being analysed.
+
+Staging a track for Platinum Notes / Mixed In Key moves it out of the folder it
+was curated in, and it comes back renamed, in a different place. Without a
+record of where it came from, that track would quietly fall out of the set or
+vibe playlist it belonged to.
+
+Matching has to survive the round trip, and the name is not stable: Platinum
+Notes appends '_PN', and a track with no artist tag is staged as
+'Unknown Artist - Title', which then reads back as a real artist. So each entry
+carries two keys - artist+title, and title alone - and a claim tries the precise
+one first.
+"""
+import json, os, re
+
+from . import paths
+from .dupes import ident, norm_title
+
+PENDING = "pending-membership.json"
+PLACEHOLDER = re.compile(r"(?i)^(unknown artist|unknown|various artists|va)$")
+
+
+def _file():
+    return os.path.join(paths.data_dir(), PENDING)
+
+
+def _load():
+    try:
+        with open(_file()) as fh:
+            data = json.load(fh)
+        return data if isinstance(data, list) else []
+    except (OSError, json.JSONDecodeError):
+        return []
+
+
+def _save(data):
+    with open(_file(), "w") as fh:
+        json.dump(data, fh, indent=1)
+
+
+def _keys(rec):
+    """(precise key, loose key). The loose key ignores the artist entirely."""
+    artist = rec.artist or ""
+    precise = ident(rec) if not PLACEHOLDER.match(artist.strip()) else None
+    loose = norm_title(rec.title or "") or None
+    return precise, loose
+
+
+def remember(pairs):
+    """pairs: iterable of (Rec, [playlist name, ...])."""
+    data = _load()
+    for rec, names in pairs:
+        if not names:
+            continue
+        precise, loose = _keys(rec)
+        found = None
+        for e in data:
+            if (precise and e.get("ident") == precise) or \
+               (loose and e.get("title") == loose):
+                found = e
+                break
+        if found is None:
+            found = {"ident": precise, "title": loose,
+                     "display": rec.display, "playlists": []}
+            data.append(found)
+        for n in names:
+            if n not in found["playlists"]:
+                found["playlists"].append(n)
+    _save(data)
+    return len(data)
+
+
+def claim(rec):
+    """Playlists this track owes a place in. Does not clear the entry."""
+    precise, loose = _keys(rec)
+    data = _load()
+    if precise:
+        for e in data:
+            if e.get("ident") == precise:
+                return e["playlists"]
+    if loose:
+        for e in data:
+            if e.get("title") == loose:
+                return e["playlists"]
+    return []
+
+
+def release(recs):
+    """Forget the entries for these tracks, once they are back in playlists."""
+    data = _load()
+    drop = []
+    for r in recs:
+        precise, loose = _keys(r)
+        for e in data:
+            if (precise and e.get("ident") == precise) or \
+               (loose and e.get("title") == loose):
+                drop.append(id(e))
+    _save([e for e in data if id(e) not in drop])
+
+
+def pending_count():
+    return len(_load())
+
+
+def pending():
+    return _load()

sortero/organize.py

@@ -276,11 +276,11 @@ def playlists_from_current(root, recs):
     return dict(pls)
 
 
-def write_playlists(root, playlists, journal=None, dry=False):
+def write_playlists(root, playlists, journal=None, dry=False, min_tracks=2):
     out = os.path.join(root, PLAYLIST_DIR)
     written = []
     for name, paths in sorted(playlists.items()):
-        if len(paths) < 2:
+        if len(paths) < min_tracks:
             continue
         fp = os.path.join(out, f"{name}.m3u8")
         written.append(fp)
@@ -296,10 +296,47 @@ def write_playlists(root, playlists, journal=None, dry=False):
     return written
 
 
-def stage_for_analysis(root, recs, log=print, progress=None):
-    """Move chosen tracks into 'To Be Processed' for Platinum Notes / Mixed In Key."""
+def folder_playlist_name(rec):
+    """The playlist name a track's current folder maps to, or None at the root."""
+    folder = os.path.dirname(rec.rel)
+    if not folder:
+        return None
+    return safe(folder.replace(os.sep, " - "), 100)
+
+
+def stage_for_analysis(root, recs, all_recs=None, log=print, progress=None):
+    """Move chosen tracks into 'To Be Processed' for Platinum Notes / Mixed In Key.
+
+    Their current folder membership is written to playlists first and recorded
+    as pending, so filing them back out of 'Processed' restores them to the
+    sets and vibe playlists they were curated into.
+    """
+    from . import membership
+
     j = Journal("stage-for-analysis", root)
     dest_dir = os.path.join(root, "To Be Processed")
+
+    # Capture curation before anything moves.
+    staged_paths = {r.path for r in recs}
+    owed = [(r, [n]) for r in recs if (n := folder_playlist_name(r))]
+    if owed:
+        pool = all_recs if all_recs is not None else recs
+        by_name = collections.defaultdict(list)
+        for r in pool:
+            if r.protected or r.path in staged_paths:
+                continue
+            n = folder_playlist_name(r)
+            if n:
+                by_name[n].append(r.path)
+        affected = {n for _, names in owed for n in names}
+        # min_tracks=1: keep even a nearly-empty playlist alive so the staged
+        # track has something to rejoin.
+        write_playlists(root, {n: by_name.get(n, []) for n in affected},
+                        journal=j, min_tracks=1)
+        membership.remember(owed)
+        log(f"recorded playlist membership for {len(owed)} tracks "
+            f"across {len(affected)} playlists")
+
     total = len(recs) or 1
     n = 0
     for i, r in enumerate(recs):