rekordbox-edit 0.13.0.dev7__tar.gz → 0.13.0.dev9__tar.gz

{rekordbox_edit-0.13.0.dev7 → rekordbox_edit-0.13.0.dev9}/CHANGELOG.md

@@ -1,6 +1,19 @@
-## v0.13.0.dev7 (2026-09-08)
-
-
+## v0.13.0.dev9 (2026-09-08)
+
+
+- fix: preserve unreadable ANLZ tags when rewriting a track's path
+- The PPTH rewrite went through AnlzFile.save(), which rebuilds a file from
+the tags pyrekordbox parsed and discards the rest. PVB2, the seek index
+Rekordbox writes for every analysed FLAC, is one it has no structure for,
+so every edit and convert that changed a filename dropped it. Across a
+24,698-file library, 1,787 files lost an 8,032-byte PVB2, and 10 more
+could not be parsed at all, leaving a stale path behind a successful write.
+- _anlz.py rewrites the tag by splicing bytes and correcting len_file. Tags
+are walked by declared length instead of being parsed, so a tag with no
+reader here survives and an unparseable file is still rewritten. Each
+analysis file is handled on its own, so one malformed file no longer
+abandons the rest of a track's analysis.
+- docs(research): investigate integrating rekordbox-edit with beets
 - fix(edit): give the records an edit creates and collects their USNs
 - An edit that reassigned a relational field left the record it created
 unstamped and the one it collected outside the counter, so a syncing peer

{rekordbox_edit-0.13.0.dev7 → rekordbox_edit-0.13.0.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rekordbox-edit
-Version: 0.13.0.dev7
+Version: 0.13.0.dev9
 Summary: Tools for managing and modifying a RekordBox library en-masse
 Project-URL: Homepage, https://github.com/jviall/rekordbox-edit
 Project-URL: Repository, https://github.com/jviall/rekordbox-edit

{rekordbox_edit-0.13.0.dev7 → rekordbox_edit-0.13.0.dev9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rekordbox-edit"
-version = "0.13.0.dev7"
+version = "0.13.0.dev9"
 description = "Tools for managing and modifying a RekordBox library en-masse"
 authors = [{ name = "James Viall", email= "jamesviall@pm.me"}]
 license = "MIT"

rekordbox_edit-0.13.0.dev9/rekordbox_edit/api/_anlz.py

@@ -0,0 +1,86 @@
+"""Byte-level reading and rewriting of the path tag in ANLZ analysis files.
+
+An ANLZ file is a 28-byte header followed by a flat run of tags, each carrying
+its own length and none referring to another's position. Rewriting the stored
+path is therefore a splice: replace the PPTH tag, correct the file length, and
+every other byte survives.
+
+That byte preservation is the point. `pyrekordbox`'s `AnlzFile.save()` rebuilds
+a file from the tags its parser recognized and silently discards the rest, which
+loses `PVB2`, the seek index Rekordbox writes for FLAC tracks.
+"""
+
+import struct
+
+#: type, len_header, len_file, then four values this module does not interpret.
+_FILE_HEADER = struct.Struct(">4sIIIIII")
+#: type, len_header, len_tag. Every tag starts with these, whatever follows.
+_TAG_HEADER = struct.Struct(">4sII")
+_MAGIC = b"PMAI"
+_PATH_TAG = b"PPTH"
+#: PPTH holds its path after the tag header and a 4-byte character count.
+_PATH_OFFSET = _TAG_HEADER.size + 4
+#: The path is stored UTF-16 big-endian with a terminating null character.
+_TERMINATOR = b"\x00\x00"
+
+
+class AnlzFormatError(ValueError):
+    """The bytes given are not a well-formed ANLZ file."""
+
+
+def _walk_tags(data: bytes):
+    """Yield `(offset, tag_type, len_tag)` per tag, without reading contents.
+
+    Walking by declared length rather than by parsing means a tag this codebase
+    has no structure for is still traversable.
+    """
+    if len(data) < _FILE_HEADER.size:
+        raise AnlzFormatError("shorter than an ANLZ file header")
+    magic, len_header = _FILE_HEADER.unpack_from(data, 0)[:2]
+    if magic != _MAGIC:
+        raise AnlzFormatError(f"expected {_MAGIC!r} magic, found {magic!r}")
+
+    offset = len_header
+    while offset + _TAG_HEADER.size <= len(data):
+        tag_type, _len_tag_header, len_tag = _TAG_HEADER.unpack_from(data, offset)
+        if len_tag <= 0 or offset + len_tag > len(data):
+            raise AnlzFormatError(
+                f"tag {tag_type!r} at offset {offset} declares length {len_tag}, "
+                f"which overruns the {len(data)}-byte file"
+            )
+        yield offset, tag_type, len_tag
+        offset += len_tag
+
+
+def _find_path_tag(data: bytes) -> tuple[int, int]:
+    for offset, tag_type, len_tag in _walk_tags(data):
+        if tag_type == _PATH_TAG:
+            return offset, len_tag
+    raise AnlzFormatError(f"no {_PATH_TAG.decode()} tag in this file")
+
+
+def _build_path_tag(path: str) -> bytes:
+    encoded = path.encode("utf-16-be") + _TERMINATOR
+    content = struct.pack(">I", len(encoded)) + encoded
+    return (
+        _TAG_HEADER.pack(_PATH_TAG, _PATH_OFFSET, _TAG_HEADER.size + len(content))
+        + content
+    )
+
+
+def read_path(data: bytes) -> str:
+    """The path held in the file's PPTH tag."""
+    offset, _len_tag = _find_path_tag(data)
+    (len_path,) = struct.unpack_from(">I", data, offset + _TAG_HEADER.size)
+    start = offset + _PATH_OFFSET
+    return data[start : start + len_path - len(_TERMINATOR)].decode("utf-16-be")
+
+
+def set_path(data: bytes, path: str) -> bytes:
+    """Return `data` with its PPTH tag holding `path`, all other bytes kept."""
+    offset, len_tag = _find_path_tag(data)
+    spliced = data[:offset] + _build_path_tag(path) + data[offset + len_tag :]
+
+    magic, len_header, _stale_len, *trailing = _FILE_HEADER.unpack_from(spliced, 0)
+    header = _FILE_HEADER.pack(magic, len_header, len(spliced), *trailing)
+    return header + spliced[_FILE_HEADER.size :]

{rekordbox_edit-0.13.0.dev7 → rekordbox_edit-0.13.0.dev9}/rekordbox_edit/api/_utils.py

@@ -9,6 +9,8 @@ from pyrekordbox.utils import get_rekordbox_pid
 from sqlalchemy import text
 
 from rekordbox_edit._tag_fields import TAG_FIELDS
+from rekordbox_edit.api._anlz import AnlzFormatError
+from rekordbox_edit.api._anlz import set_path as set_anlz_path
 from rekordbox_edit.errors import RekordboxRunningError
 from rekordbox_edit.locking import SCRIPTED_TIMEOUT, database_lock
 from rekordbox_edit.models import Track
@@ -81,15 +83,29 @@ def _update_anlz_paths(
     """Rewrite the PPTH path tag in a track's ANLZ files to the given file
     name, in rekordbox's device-relative ``?/<name>`` form.
 
-    No-op for tracks without an analysis.
+    Splices the tag into the file's existing bytes rather than rebuilding it
+    from parsed structures, so tags this codebase has no reader for survive.
+    Rebuilding drops them, and one of them is `PVB2`, the seek index Rekordbox
+    writes for every analysed FLAC.
+
+    Each file is handled on its own: a malformed one is reported and skipped
+    rather than abandoning the rest of the track's analysis. No-op for tracks
+    without an analysis.
     """
     if not content.AnalysisDataPath:
         return
     new_ppth = f"?/{new_filename}"
-    anlz_files = db.read_anlz_files(content.ID)
-    for anlz_path, anlz in anlz_files.items():
-        anlz.set_path(new_ppth)
-        anlz.save(anlz_path)
+    for anlz_path in db.get_anlz_paths(content.ID).values():
+        if anlz_path is None:
+            continue
+        try:
+            with open(anlz_path, "rb") as fh:
+                updated = set_anlz_path(fh.read(), new_ppth)
+            with open(anlz_path, "wb") as fh:
+                fh.write(updated)
+        except (AnlzFormatError, OSError) as e:
+            _logger.warning(f"Could not rewrite the path tag in {anlz_path}: {e}")
+            continue
         _logger.debug(f"Updated PPTH of {anlz_path} to {new_ppth}")
 
 

{rekordbox_edit-0.13.0.dev7 → rekordbox_edit-0.13.0.dev9}/research/README.md

@@ -47,6 +47,14 @@ formal and terse, and states findings as the evidence supports them.
   command deliberately diverges from that behavior.
 - **`file-types/`** — how `convert` and the display layer should treat Rekordbox
   `FileType` codes the tool does not map.
+- **`beets-plugin-integration/`** — what beets' plugin architecture permits a
+  rekordbox-edit integration to do: where events fire relative to database
+  inserts and file moves, which events the autotagger gates off, why beets item
+  identifiers do not survive a reimport, and what that forces about how the two
+  databases are joined. Also what it takes for a beets library to follow an
+  `rbe convert`, why the converted file usually needs no move, and why keeping
+  the original leaves the two libraries unable to agree — which is what settles
+  the plugin deleting originals by default where the CLI does not.
 - **`import-track-row-shape/`** — what a `DjmdContent` row holds immediately after
   Rekordbox imports a track and before analysis runs, which columns come from
   tags rather than the audio, and where `pyrekordbox.add_content` diverges from