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

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

@@ -1,6 +1,18 @@
-## v0.13.0.dev8 (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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rekordbox-edit
-Version: 0.13.0.dev8
+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.dev8 → rekordbox_edit-0.13.0.dev9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rekordbox-edit"
-version = "0.13.0.dev8"
+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.dev8 → 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.dev9/tests/anlz_helpers.py

@@ -0,0 +1,38 @@
+"""Assemble ANLZ bytes for tests.
+
+An ANLZ file is a 28-byte PMAI header followed by a flat run of tags. Building
+that layout here lets a test place a tag no parser in this codebase understands,
+which is the case the path rewrite has to survive.
+"""
+
+import struct
+
+FILE_HEADER = struct.Struct(">4sIIIIII")
+_TAG_HEADER = struct.Struct(">4sII")
+
+
+def tag(tag_type: bytes, content: bytes) -> bytes:
+    """One tag: type, header length, total length, then content."""
+    return (
+        _TAG_HEADER.pack(tag_type, _TAG_HEADER.size, _TAG_HEADER.size + len(content))
+        + content
+    )
+
+
+def path_tag(path: str) -> bytes:
+    """A PPTH tag holding `path`, in Rekordbox's UTF-16 big-endian layout."""
+    encoded = path.encode("utf-16-be") + b"\x00\x00"
+    content = struct.pack(">I", len(encoded)) + encoded
+    return _TAG_HEADER.pack(b"PPTH", 16, _TAG_HEADER.size + len(content)) + content
+
+
+def anlz(*tags: bytes) -> bytes:
+    """A complete ANLZ file wrapping `tags`."""
+    body = b"".join(tags)
+    return FILE_HEADER.pack(b"PMAI", 28, 28 + len(body), 0, 0, 0, 0) + body
+
+
+#: Stands in for PVB2, which pyrekordbox has no structure for and drops on a
+#: parse-and-rebuild. The contents are recognizable so a test can assert they
+#: came through untouched.
+UNPARSED_TAG = tag(b"PVB2", b"\xde\xad\xbe\xef" * 8)

rekordbox_edit-0.13.0.dev9/tests/api/test_anlz.py

@@ -0,0 +1,76 @@
+"""Byte-level ANLZ path rewriting."""
+
+import struct
+
+import pytest
+from pyrekordbox.anlz.file import AnlzFile
+
+from tests.anlz_helpers import FILE_HEADER, UNPARSED_TAG, anlz, path_tag, tag
+
+from rekordbox_edit.api._anlz import AnlzFormatError, read_path, set_path
+
+
+class TestSetPath:
+    def test_writes_a_path_rekordbox_can_read_back(self):
+        data = anlz(path_tag("?/old name.flac"))
+
+        result = set_path(data, "?/new name.mp3")
+
+        # Verified through pyrekordbox's own parser, not our reader, so this
+        # asserts the output is well-formed rather than merely self-consistent.
+        assert AnlzFile.parse(result).get("path") == "?/new name.mp3"
+
+    def test_preserves_tags_the_parser_does_not_understand(self):
+        data = anlz(path_tag("?/old.flac"), UNPARSED_TAG)
+
+        result = set_path(data, "?/new.mp3")
+
+        assert UNPARSED_TAG in result
+
+    def test_writing_the_same_path_leaves_bytes_unchanged(self):
+        data = anlz(path_tag("?/song.flac"), UNPARSED_TAG)
+
+        assert set_path(data, "?/song.flac") == data
+
+    def test_updates_len_file_when_the_path_length_changes(self):
+        data = anlz(path_tag("?/short.flac"), UNPARSED_TAG)
+
+        result = set_path(data, "?/a considerably longer name.flac")
+
+        assert FILE_HEADER.unpack_from(result, 0)[2] == len(result)
+
+    def test_rewrites_a_file_pyrekordbox_cannot_parse(self):
+        # A PQTZ tag whose content is too short for its struct: pyrekordbox
+        # raises, but the tag run is still walkable by declared length.
+        data = anlz(path_tag("?/old.flac"), tag(b"PQTZ", b"\x00"))
+        with pytest.raises(Exception):
+            AnlzFile.parse(data)
+
+        result = set_path(data, "?/new.mp3")
+
+        assert read_path(result) == "?/new.mp3"
+
+    def test_rejects_a_file_that_is_not_anlz(self):
+        with pytest.raises(AnlzFormatError):
+            set_path(b"NOPE" + b"\x00" * 40, "?/new.mp3")
+
+    def test_rejects_a_file_with_no_path_tag(self):
+        with pytest.raises(AnlzFormatError):
+            set_path(anlz(UNPARSED_TAG), "?/new.mp3")
+
+    def test_rejects_a_tag_that_overruns_the_file(self):
+        good = anlz(path_tag("?/old.flac"))
+        # Declare a tag length past the end of the buffer.
+        corrupt = bytearray(good)
+        struct.pack_into(">I", corrupt, 28 + 8, 9999)
+        with pytest.raises(AnlzFormatError):
+            set_path(bytes(corrupt), "?/new.mp3")
+
+
+class TestReadPath:
+    def test_returns_the_stored_path(self):
+        assert read_path(anlz(path_tag("?/song.flac"))) == "?/song.flac"
+
+    def test_rejects_a_file_with_no_path_tag(self):
+        with pytest.raises(AnlzFormatError):
+            read_path(anlz(UNPARSED_TAG))

{rekordbox_edit-0.13.0.dev8 → rekordbox_edit-0.13.0.dev9}/tests/api/test_convert.py

@@ -27,7 +27,6 @@ from rekordbox_edit.api._convert import (
     _run_ffmpeg,
     _sweep_orphan_temp_files,
     _temp_output_path,
-    _update_anlz_paths,
     convert,
 )
 from sqlalchemy import text
@@ -2578,33 +2577,6 @@ class TestApplyConvertedRecord:
         assert content.SampleRate == 48000
 
 
-class TestUpdateAnlzPaths:
-    def test_rewrites_ppth_to_device_relative_form(self, make_djmd_content_item):
-        mock_db = Mock()
-        content = make_djmd_content_item(ID=7)
-        content.AnalysisDataPath = "share/PIONEER/USBANLZ/x/ANLZ0000.DAT"
-        dat, ext = Mock(), Mock()
-        mock_db.read_anlz_files.return_value = {
-            "/a/ANLZ0000.DAT": dat,
-            "/a/ANLZ0000.EXT": ext,
-        }
-
-        _update_anlz_paths(mock_db, content, "new song.aiff")
-
-        dat.set_path.assert_called_once_with("?/new song.aiff")
-        dat.save.assert_called_once_with("/a/ANLZ0000.DAT")
-        ext.set_path.assert_called_once_with("?/new song.aiff")
-        ext.save.assert_called_once_with("/a/ANLZ0000.EXT")
-
-    def test_skips_track_without_analysis(self, make_djmd_content_item):
-        mock_db = Mock()
-        content = make_djmd_content_item(ID=7)  # AnalysisDataPath defaults to None
-
-        _update_anlz_paths(mock_db, content, "new.aiff")
-
-        mock_db.read_anlz_files.assert_not_called()
-
-
 class TestRollbackSession:
     def test_rolls_back_session(self, mock_db):
         _rollback_session(mock_db)

{rekordbox_edit-0.13.0.dev8 → rekordbox_edit-0.13.0.dev9}/tests/api/test_utils.py

@@ -9,9 +9,12 @@ from filelock import FileLock, Timeout
 from pyrekordbox import Rekordbox6Database
 from sqlalchemy import text
 
+from tests.anlz_helpers import UNPARSED_TAG, anlz, path_tag
 from tests.api.conftest import close_database
 
+from rekordbox_edit.api._anlz import read_path
 from rekordbox_edit.api._utils import (
+    _update_anlz_paths,
     reserve_usns,
     stamp_usns,
     track_from_content,
@@ -261,3 +264,63 @@ class TestWriting:
                         pass
         finally:
             foreign.release()
+
+
+class TestUpdateAnlzPaths:
+    """The path rewrite must not disturb anything else in the file: these are
+    the only copy of a track's analysis, and tags this codebase cannot parse
+    still belong to Rekordbox."""
+
+    @pytest.fixture()
+    def analysed(self, tmp_path, make_djmd_content_item):
+        """A track whose DAT and EXT files exist on disk, the EXT carrying a
+        tag no parser here understands."""
+        dat = tmp_path / "ANLZ0000.DAT"
+        ext = tmp_path / "ANLZ0000.EXT"
+        dat.write_bytes(anlz(path_tag("?/old name.flac")))
+        ext.write_bytes(anlz(path_tag("?/old name.flac"), UNPARSED_TAG))
+
+        db = Mock()
+        db.get_anlz_paths.return_value = {"DAT": dat, "EXT": ext}
+        content = make_djmd_content_item(ID=7)
+        content.AnalysisDataPath = "share/PIONEER/USBANLZ/x/ANLZ0000.DAT"
+        return db, content, dat, ext
+
+    def test_rewrites_the_path_in_every_analysis_file(self, analysed):
+        db, content, dat, ext = analysed
+
+        _update_anlz_paths(db, content, "new song.mp3")
+
+        assert read_path(dat.read_bytes()) == "?/new song.mp3"
+        assert read_path(ext.read_bytes()) == "?/new song.mp3"
+
+    def test_preserves_tags_the_parser_does_not_understand(self, analysed):
+        db, content, _dat, ext = analysed
+
+        _update_anlz_paths(db, content, "new song.mp3")
+
+        assert UNPARSED_TAG in ext.read_bytes()
+
+    def test_leaves_other_files_alone_when_one_is_malformed(self, analysed):
+        db, content, dat, ext = analysed
+        ext.write_bytes(b"not an anlz file at all")
+
+        _update_anlz_paths(db, content, "new song.mp3")
+
+        assert read_path(dat.read_bytes()) == "?/new song.mp3"
+
+    def test_skips_a_track_without_analysis(self, make_djmd_content_item):
+        db = Mock()
+        content = make_djmd_content_item(ID=7)  # AnalysisDataPath defaults to None
+
+        _update_anlz_paths(db, content, "new.mp3")
+
+        db.get_anlz_paths.assert_not_called()
+
+    def test_skips_an_analysis_file_that_does_not_exist(self, analysed, tmp_path):
+        db, content, dat, _ext = analysed
+        db.get_anlz_paths.return_value = {"DAT": dat, "EXT": tmp_path / "absent.EXT"}
+
+        _update_anlz_paths(db, content, "new song.mp3")
+
+        assert read_path(dat.read_bytes()) == "?/new song.mp3"

{rekordbox_edit-0.13.0.dev8 → rekordbox_edit-0.13.0.dev9}/uv.lock

@@ -1277,7 +1277,7 @@ wheels = [
 
 [[package]]
 name = "rekordbox-edit"
-version = "0.13.0.dev8"
+version = "0.13.0.dev9"
 source = { editable = "." }
 dependencies = [
     { name = "click" },