beets-musefs 0.0.1__tar.gz

beets_musefs-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Conor Futro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

beets_musefs-0.0.1/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: beets-musefs
+Version: 0.0.1
+Summary: Sync beets metadata into the musefs SQLite store
+Author: Conor Futro
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Sohex/musefs
+Project-URL: Repository, https://github.com/Sohex/musefs
+Project-URL: Issues, https://github.com/Sohex/musefs/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-musefs>=0.1.0
+Requires-Dist: beets>=1.6
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# beets-musefs
+
+A [beets](https://beets.io) plugin that syncs your beets metadata (tags + cover
+art) into a [musefs](../../README.md) SQLite store, so a live musefs mount shows
+a re-tagged view of your library without rewriting any audio.
+
+## How it fits together
+
+- The plugin owns the **tags** (and **cover art**, when beets has it) of each
+  track, keyed by the file's canonical real path.
+- The structural columns (audio offsets, size, mtime) can only come from musefs
+  probing the file, so the plugin runs `musefs scan` for you (via the `bin`
+  config) before syncing — it never tries to compute those itself.
+- `beet musefs` scans the library and then syncs; the import/write hooks scan
+  just the touched file and then sync. musefs's auto-refresh shows changes live —
+  no remount, and **no separate scan step**.
+
+## Install (local / development)
+
+No install needed — point beets at the plugin's `beetsplug` directory. beets adds
+`pluginpath` entries directly to the `beetsplug` package path, so it must be the
+`beetsplug` dir itself (not its parent). In your beets `config.yaml`:
+
+The plugin depends on the shared `python-musefs` library, which is unpublished
+and lives in this repo. Install it from the working tree **before** the plugin:
+
+```bash
+pip install -e contrib/python-musefs
+pip install -e "contrib/beets[test]"
+```
+
+```yaml
+pluginpath: /path/to/musefs/contrib/beets/beetsplug
+plugins: musefs
+musefs:
+  db: ~/musefs.db          # path to the musefs SQLite store (required)
+  bin: musefs              # musefs executable for auto-scan; use a full path if
+                           # not on $PATH, e.g. /path/to/musefs/target/release/musefs
+  # autoscan: yes          # default; runs `musefs scan` for you. Set `no` to
+  #                        # manage scanning yourself (hooks then best-effort).
+  # fields:                # optional: map extra beets fields to musefs keys
+  #   comments: comment
+```
+
+## Workflow (test drive)
+
+```bash
+# Sync beets metadata into the store. Auto-scans the library first (creating the
+# DB if needed) — no separate `musefs scan` step.
+beet musefs                      # everything
+beet musefs albumartist:"Boards of Canada"   # a subset (scans just those files)
+beet musefs -n                   # dry run: report counts, write nothing
+
+# Mount the re-tagged view.
+musefs mount ~/mnt --db ~/musefs.db \
+    --template '$albumartist/$album/$tracknumber - $title'
+
+# ...or mirror your beets library layout exactly, via the computed beets_path tag.
+musefs mount ~/mnt --db ~/musefs.db --template '$!{beets_path}'
+```
+
+Imports and tag write-backs auto-sync via event hooks: `beet import` and
+`beet modify -w …` record the touched items and reconcile them once the command
+finishes — when each file's path is final (beets has no move event, and a write
+fires *before* its move). The reconcile scans the new path and prunes the row
+left behind at the old one. A metadata-only `beet modify` (no `-w`) doesn't fire
+a hook — re-run `beet musefs`. With `autoscan: no`, run `musefs scan` yourself
+first; the hooks then skip gracefully if the DB is missing.
+
+## Notes
+
+- **Cover art:** taken from the album's `artpath` (beets' external cover file).
+  beets art wins when present; otherwise any art `musefs scan` ingested from
+  embedded pictures is preserved.
+- **Computed path (`beets_path`):** each sync also writes a `beets_path` text tag
+  holding the track's beets library-relative path (from your `paths:` config, via
+  `item.destination`), with the file extension removed — musefs re-appends it. Mount
+  with `--template '$!{beets_path}'` (the `$!{}` path field keeps `/` as directory
+  separators) to mirror your beets layout, including layouts musefs's own template
+  engine can't express. Set `write_path: no` in the `musefs:` config to skip it.
+  Do not add an extension in a template that consumes `beets_path`. See the
+  computed-tag workflow in [ARCHITECTURE.md](../../ARCHITECTURE.md).
+- **Moves & deletes:** every sync (the command and the end-of-command reconcile)
+  prunes track rows whose backing file is no longer present, so renames/moves
+  don't leave stale entries. Caveat: a file that's merely offline at sync time
+  (e.g. an unmounted network share) is also pruned — sync while the library is
+  available.
+- **Orphaned art:** replacing art can orphan old blobs; `musefs scan --revalidate`
+  garbage-collects them.
+- **Schema version:** the plugin refuses to run if the DB's `user_version` differs
+  from the version it targets — rebuild after upgrading musefs.
+
+## Tests
+
+The tests live under `tests/` and use a local virtualenv with beets + pytest.
+
+```bash
+cd contrib/beets
+uv venv                                   # create .venv (once)
+source .venv/bin/activate
+uv pip install -e ../python-musefs        # shared library (unpublished; install first)
+uv pip install -r requirements.txt        # beets + pytest
+
+python -m pytest                          # unit + integration (no Rust binary)
+python -m pytest -m musefs_bin            # path-matching gate vs the real `musefs` binary
+python -m pytest -m e2e                   # full beets -> mount -> playback end-to-end
+```
+
+The `musefs_bin` gate shells out to the real `musefs` binary, so build it first
+from the repo root (`cargo build`) and run it against a fresh build. The `e2e`
+tier additionally needs `ffmpeg` and `/dev/fuse` + `fusermount`: it generates
+audio, imports it with beets, retags, syncs, mounts via FUSE, and verifies the
+mount's tags and byte-identical audio (including a move-reconcile case). Both
+tiers are deselected from the default run and skip cleanly if their tools are
+absent.

beets_musefs-0.0.1/README.md

@@ -0,0 +1,115 @@
+# beets-musefs
+
+A [beets](https://beets.io) plugin that syncs your beets metadata (tags + cover
+art) into a [musefs](../../README.md) SQLite store, so a live musefs mount shows
+a re-tagged view of your library without rewriting any audio.
+
+## How it fits together
+
+- The plugin owns the **tags** (and **cover art**, when beets has it) of each
+  track, keyed by the file's canonical real path.
+- The structural columns (audio offsets, size, mtime) can only come from musefs
+  probing the file, so the plugin runs `musefs scan` for you (via the `bin`
+  config) before syncing — it never tries to compute those itself.
+- `beet musefs` scans the library and then syncs; the import/write hooks scan
+  just the touched file and then sync. musefs's auto-refresh shows changes live —
+  no remount, and **no separate scan step**.
+
+## Install (local / development)
+
+No install needed — point beets at the plugin's `beetsplug` directory. beets adds
+`pluginpath` entries directly to the `beetsplug` package path, so it must be the
+`beetsplug` dir itself (not its parent). In your beets `config.yaml`:
+
+The plugin depends on the shared `python-musefs` library, which is unpublished
+and lives in this repo. Install it from the working tree **before** the plugin:
+
+```bash
+pip install -e contrib/python-musefs
+pip install -e "contrib/beets[test]"
+```
+
+```yaml
+pluginpath: /path/to/musefs/contrib/beets/beetsplug
+plugins: musefs
+musefs:
+  db: ~/musefs.db          # path to the musefs SQLite store (required)
+  bin: musefs              # musefs executable for auto-scan; use a full path if
+                           # not on $PATH, e.g. /path/to/musefs/target/release/musefs
+  # autoscan: yes          # default; runs `musefs scan` for you. Set `no` to
+  #                        # manage scanning yourself (hooks then best-effort).
+  # fields:                # optional: map extra beets fields to musefs keys
+  #   comments: comment
+```
+
+## Workflow (test drive)
+
+```bash
+# Sync beets metadata into the store. Auto-scans the library first (creating the
+# DB if needed) — no separate `musefs scan` step.
+beet musefs                      # everything
+beet musefs albumartist:"Boards of Canada"   # a subset (scans just those files)
+beet musefs -n                   # dry run: report counts, write nothing
+
+# Mount the re-tagged view.
+musefs mount ~/mnt --db ~/musefs.db \
+    --template '$albumartist/$album/$tracknumber - $title'
+
+# ...or mirror your beets library layout exactly, via the computed beets_path tag.
+musefs mount ~/mnt --db ~/musefs.db --template '$!{beets_path}'
+```
+
+Imports and tag write-backs auto-sync via event hooks: `beet import` and
+`beet modify -w …` record the touched items and reconcile them once the command
+finishes — when each file's path is final (beets has no move event, and a write
+fires *before* its move). The reconcile scans the new path and prunes the row
+left behind at the old one. A metadata-only `beet modify` (no `-w`) doesn't fire
+a hook — re-run `beet musefs`. With `autoscan: no`, run `musefs scan` yourself
+first; the hooks then skip gracefully if the DB is missing.
+
+## Notes
+
+- **Cover art:** taken from the album's `artpath` (beets' external cover file).
+  beets art wins when present; otherwise any art `musefs scan` ingested from
+  embedded pictures is preserved.
+- **Computed path (`beets_path`):** each sync also writes a `beets_path` text tag
+  holding the track's beets library-relative path (from your `paths:` config, via
+  `item.destination`), with the file extension removed — musefs re-appends it. Mount
+  with `--template '$!{beets_path}'` (the `$!{}` path field keeps `/` as directory
+  separators) to mirror your beets layout, including layouts musefs's own template
+  engine can't express. Set `write_path: no` in the `musefs:` config to skip it.
+  Do not add an extension in a template that consumes `beets_path`. See the
+  computed-tag workflow in [ARCHITECTURE.md](../../ARCHITECTURE.md).
+- **Moves & deletes:** every sync (the command and the end-of-command reconcile)
+  prunes track rows whose backing file is no longer present, so renames/moves
+  don't leave stale entries. Caveat: a file that's merely offline at sync time
+  (e.g. an unmounted network share) is also pruned — sync while the library is
+  available.
+- **Orphaned art:** replacing art can orphan old blobs; `musefs scan --revalidate`
+  garbage-collects them.
+- **Schema version:** the plugin refuses to run if the DB's `user_version` differs
+  from the version it targets — rebuild after upgrading musefs.
+
+## Tests
+
+The tests live under `tests/` and use a local virtualenv with beets + pytest.
+
+```bash
+cd contrib/beets
+uv venv                                   # create .venv (once)
+source .venv/bin/activate
+uv pip install -e ../python-musefs        # shared library (unpublished; install first)
+uv pip install -r requirements.txt        # beets + pytest
+
+python -m pytest                          # unit + integration (no Rust binary)
+python -m pytest -m musefs_bin            # path-matching gate vs the real `musefs` binary
+python -m pytest -m e2e                   # full beets -> mount -> playback end-to-end
+```
+
+The `musefs_bin` gate shells out to the real `musefs` binary, so build it first
+from the repo root (`cargo build`) and run it against a fresh build. The `e2e`
+tier additionally needs `ffmpeg` and `/dev/fuse` + `fusermount`: it generates
+audio, imports it with beets, retags, syncs, mounts via FUSE, and verifies the
+mount's tags and byte-identical audio (including a move-reconcile case). Both
+tiers are deselected from the default run and skip cleanly if their tools are
+absent.

beets_musefs-0.0.1/beets_musefs.egg-info/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: beets-musefs
+Version: 0.0.1
+Summary: Sync beets metadata into the musefs SQLite store
+Author: Conor Futro
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Sohex/musefs
+Project-URL: Repository, https://github.com/Sohex/musefs
+Project-URL: Issues, https://github.com/Sohex/musefs/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-musefs>=0.1.0
+Requires-Dist: beets>=1.6
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# beets-musefs
+
+A [beets](https://beets.io) plugin that syncs your beets metadata (tags + cover
+art) into a [musefs](../../README.md) SQLite store, so a live musefs mount shows
+a re-tagged view of your library without rewriting any audio.
+
+## How it fits together
+
+- The plugin owns the **tags** (and **cover art**, when beets has it) of each
+  track, keyed by the file's canonical real path.
+- The structural columns (audio offsets, size, mtime) can only come from musefs
+  probing the file, so the plugin runs `musefs scan` for you (via the `bin`
+  config) before syncing — it never tries to compute those itself.
+- `beet musefs` scans the library and then syncs; the import/write hooks scan
+  just the touched file and then sync. musefs's auto-refresh shows changes live —
+  no remount, and **no separate scan step**.
+
+## Install (local / development)
+
+No install needed — point beets at the plugin's `beetsplug` directory. beets adds
+`pluginpath` entries directly to the `beetsplug` package path, so it must be the
+`beetsplug` dir itself (not its parent). In your beets `config.yaml`:
+
+The plugin depends on the shared `python-musefs` library, which is unpublished
+and lives in this repo. Install it from the working tree **before** the plugin:
+
+```bash
+pip install -e contrib/python-musefs
+pip install -e "contrib/beets[test]"
+```
+
+```yaml
+pluginpath: /path/to/musefs/contrib/beets/beetsplug
+plugins: musefs
+musefs:
+  db: ~/musefs.db          # path to the musefs SQLite store (required)
+  bin: musefs              # musefs executable for auto-scan; use a full path if
+                           # not on $PATH, e.g. /path/to/musefs/target/release/musefs
+  # autoscan: yes          # default; runs `musefs scan` for you. Set `no` to
+  #                        # manage scanning yourself (hooks then best-effort).
+  # fields:                # optional: map extra beets fields to musefs keys
+  #   comments: comment
+```
+
+## Workflow (test drive)
+
+```bash
+# Sync beets metadata into the store. Auto-scans the library first (creating the
+# DB if needed) — no separate `musefs scan` step.
+beet musefs                      # everything
+beet musefs albumartist:"Boards of Canada"   # a subset (scans just those files)
+beet musefs -n                   # dry run: report counts, write nothing
+
+# Mount the re-tagged view.
+musefs mount ~/mnt --db ~/musefs.db \
+    --template '$albumartist/$album/$tracknumber - $title'
+
+# ...or mirror your beets library layout exactly, via the computed beets_path tag.
+musefs mount ~/mnt --db ~/musefs.db --template '$!{beets_path}'
+```
+
+Imports and tag write-backs auto-sync via event hooks: `beet import` and
+`beet modify -w …` record the touched items and reconcile them once the command
+finishes — when each file's path is final (beets has no move event, and a write
+fires *before* its move). The reconcile scans the new path and prunes the row
+left behind at the old one. A metadata-only `beet modify` (no `-w`) doesn't fire
+a hook — re-run `beet musefs`. With `autoscan: no`, run `musefs scan` yourself
+first; the hooks then skip gracefully if the DB is missing.
+
+## Notes
+
+- **Cover art:** taken from the album's `artpath` (beets' external cover file).
+  beets art wins when present; otherwise any art `musefs scan` ingested from
+  embedded pictures is preserved.
+- **Computed path (`beets_path`):** each sync also writes a `beets_path` text tag
+  holding the track's beets library-relative path (from your `paths:` config, via
+  `item.destination`), with the file extension removed — musefs re-appends it. Mount
+  with `--template '$!{beets_path}'` (the `$!{}` path field keeps `/` as directory
+  separators) to mirror your beets layout, including layouts musefs's own template
+  engine can't express. Set `write_path: no` in the `musefs:` config to skip it.
+  Do not add an extension in a template that consumes `beets_path`. See the
+  computed-tag workflow in [ARCHITECTURE.md](../../ARCHITECTURE.md).
+- **Moves & deletes:** every sync (the command and the end-of-command reconcile)
+  prunes track rows whose backing file is no longer present, so renames/moves
+  don't leave stale entries. Caveat: a file that's merely offline at sync time
+  (e.g. an unmounted network share) is also pruned — sync while the library is
+  available.
+- **Orphaned art:** replacing art can orphan old blobs; `musefs scan --revalidate`
+  garbage-collects them.
+- **Schema version:** the plugin refuses to run if the DB's `user_version` differs
+  from the version it targets — rebuild after upgrading musefs.
+
+## Tests
+
+The tests live under `tests/` and use a local virtualenv with beets + pytest.
+
+```bash
+cd contrib/beets
+uv venv                                   # create .venv (once)
+source .venv/bin/activate
+uv pip install -e ../python-musefs        # shared library (unpublished; install first)
+uv pip install -r requirements.txt        # beets + pytest
+
+python -m pytest                          # unit + integration (no Rust binary)
+python -m pytest -m musefs_bin            # path-matching gate vs the real `musefs` binary
+python -m pytest -m e2e                   # full beets -> mount -> playback end-to-end
+```
+
+The `musefs_bin` gate shells out to the real `musefs` binary, so build it first
+from the repo root (`cargo build`) and run it against a fresh build. The `e2e`
+tier additionally needs `ffmpeg` and `/dev/fuse` + `fusermount`: it generates
+audio, imports it with beets, retags, syncs, mounts via FUSE, and verifies the
+mount's tags and byte-identical audio (including a move-reconcile case). Both
+tiers are deselected from the default run and skip cleanly if their tools are
+absent.

beets_musefs-0.0.1/beets_musefs.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+beets_musefs.egg-info/PKG-INFO
+beets_musefs.egg-info/SOURCES.txt
+beets_musefs.egg-info/dependency_links.txt
+beets_musefs.egg-info/requires.txt
+beets_musefs.egg-info/top_level.txt
+beetsplug/__init__.py
+beetsplug/_core.py
+beetsplug/musefs.py
+tests/test_build_records.py
+tests/test_contract.py
+tests/test_e2e.py
+tests/test_map_fields.py
+tests/test_path_gate.py
+tests/test_paths.py
+tests/test_plugin.py
+tests/test_reconcile.py
+tests/test_smoke.py

beets_musefs-0.0.1/beets_musefs.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

beets_musefs-0.0.1/beets_musefs.egg-info/requires.txt

@@ -0,0 +1,5 @@
+python-musefs>=0.1.0
+beets>=1.6
+
+[test]
+pytest>=7

beets_musefs-0.0.1/beets_musefs.egg-info/top_level.txt

@@ -0,0 +1 @@
+beetsplug

beets_musefs-0.0.1/beetsplug/__init__.py

@@ -0,0 +1,4 @@
+# beetsplug is a namespace package shared by all beets plugins.
+from pkgutil import extend_path
+
+__path__ = extend_path(__path__, __name__)

beets_musefs-0.0.1/beetsplug/_core.py

@@ -0,0 +1,198 @@
+"""beets-specific mapping for the musefs sync plugin: no beets imports here.
+
+The shared store/scan/sync contract lives in the ``musefs_common`` package
+(python-musefs); this module only maps beets items to musefs tag pairs and reads
+album cover art into ``Record``s. ``musefs.py`` holds the BeetsPlugin adapter.
+"""
+
+import os
+
+from musefs_common import MAX_ART_BYTES, ArtImage, Record, realpath_key, sniff_mime
+
+# beets field name -> musefs (Vorbis-lowercase) tag key, for direct copies.
+# beets 2.x exposes genre/composer as the multi-valued `genres`/`composers`
+# (lists); the singular keys are kept for simpler/older items. List values are
+# expanded into one tag per element by _values().
+DIRECT_FIELDS = {
+    "title": "title",
+    "artist": "artist",
+    "albumartist": "albumartist",
+    "album": "album",
+}
+
+# (list_field, scalar_field, store_key): beets carries some tags as both a list
+# (genres/composers, beets 2.x) and a joined scalar (genre/composer). Emitting
+# both duplicates rows, so prefer the list when present, else the scalar. The
+# per-twin dedup below is scoped to one twin: if a user maps an extra_field onto
+# the "genre"/"composer" store key, that row is emitted in the direct-fields
+# loop and won't be deduped against these — an unlikely config we don't guard.
+TWIN_FIELDS = (
+    ("genres", "genre", "genre"),
+    ("composers", "composer", "composer"),
+)
+
+
+def _values(value):
+    """Normalize a beets field value to a list of non-empty string values.
+    Multi-valued beets fields (genres, composers) arrive as lists; scalars
+    become a single-element list. Avoids stringifying a list as ``['Rock']``."""
+    if value is None:
+        return []
+    items = value if isinstance(value, (list, tuple)) else [value]
+    return [text for v in items if (text := str(v).strip())]
+
+
+def _to_int(value):
+    """Coerce a beets field to int, tolerating None and non-numeric strings
+    (e.g. a malformed ``"1/12"`` track-of-total) so a bad tag can't abort sync."""
+    try:
+        return int(value or 0)
+    except (ValueError, TypeError):
+        return 0
+
+
+def _format_date(item):
+    year = _to_int(getattr(item, "year", 0))
+    if not year:
+        return None
+    month = _to_int(getattr(item, "month", 0))
+    day = _to_int(getattr(item, "day", 0))
+    if month and day:
+        return f"{year:04d}-{month:02d}-{day:02d}"
+    return f"{year:04d}"
+
+
+def map_fields(item, extra_fields=None):
+    """Map a beets item to a list of (musefs_key, value) pairs.
+
+    Empty strings and zero numerics are omitted. ``extra_fields`` merges into
+    (and can override) the direct-copy table.
+    """
+    fields = dict(DIRECT_FIELDS)
+    if extra_fields:
+        fields.update(extra_fields)
+
+    pairs = []
+    for beets_field, key in fields.items():
+        for text in _values(getattr(item, beets_field, None)):
+            pairs.append((key, text))
+
+    for list_field, scalar_field, key in TWIN_FIELDS:
+        values = _values(getattr(item, list_field, None)) or _values(
+            getattr(item, scalar_field, None)
+        )
+        seen = set()
+        for text in values:
+            if text not in seen:
+                seen.add(text)
+                pairs.append((key, text))
+
+    track = _to_int(getattr(item, "track", 0))
+    if track:
+        pairs.append(("tracknumber", str(track)))
+    disc = _to_int(getattr(item, "disc", 0))
+    if disc:
+        pairs.append(("discnumber", str(disc)))
+    date = _format_date(item)
+    if date:
+        pairs.append(("date", date))
+
+    return pairs
+
+
+def _album_art_path(item):
+    """Return the album cover path (bytes/str) for an item, or None."""
+    get_album = getattr(item, "get_album", None)
+    album = get_album() if get_album else None
+    if album is None:
+        return None
+    artpath = getattr(album, "artpath", None)
+    return artpath or None
+
+
+def _read_album_art(item, cache, stats):
+    """Return ``(data, mime)`` for the item's album cover, or None. Reads each
+    distinct cover once (cached by realpath). An unreadable or over-cap cover is
+    counted into ``stats.skipped_art`` once and cached as None (matches the
+    legacy ``_prepare_art`` counting before the python-musefs split).
+
+    Also size-capped here (not only in sync_one) so a shared over-cap cover is
+    counted once per distinct file — the double enforcement is intentional, not
+    dead code."""
+    artpath = _album_art_path(item)
+    if not artpath:
+        return None
+    key = realpath_key(artpath)
+    if key in cache:
+        return cache[key]
+    # Use the raw realpath, not realpath_key's lossy U+FFFD form: the file is
+    # only opened and extension-sniffed, not matched against the DB.
+    real = os.path.realpath(artpath)
+    try:
+        with open(real, "rb") as fh:
+            data = fh.read()
+    except OSError:
+        stats.skipped_art += 1
+        cache[key] = None
+        return None
+    if len(data) > MAX_ART_BYTES:
+        stats.skipped_art += 1
+        cache[key] = None
+        return None
+    art = (data, sniff_mime(data, os.fsdecode(real)))
+    cache[key] = art
+    return art
+
+
+def _computed_path(item):
+    """Beets' library-relative path for ``item``, decoded to a SQLite-safe str
+    with the file extension removed (musefs re-appends it at render time).
+
+    Mirrors ``realpath_key``'s lossy normalization (U+FFFD for undecodable
+    bytes) so the value is always valid UTF-8, but without realpath's on-disk
+    resolution. Returns "" when beets yields no usable path.
+    """
+    raw = item.destination(relative_to_libdir=True)
+    decoded = os.fsdecode(raw)
+    safe = decoded.encode("utf-8", "surrogateescape").decode("utf-8", "replace")
+    return os.path.splitext(safe)[0].lstrip("/")
+
+
+def _computed_path_or_skip(item, log):
+    """``_computed_path`` guarded so a bad destination never aborts a sync.
+
+    Returns "" (skip the tag) on any failure, warning through ``log`` if given.
+    """
+    try:
+        return _computed_path(item)
+    except Exception as exc:
+        if log is not None:
+            # beets' plugin logger is a StrFormatLogger ({}-style, not %-style).
+            log.warning("musefs: skipping beets_path for {!r}: {}", item.path, exc)
+        return ""
+
+
+def build_records(items, *, fields=None, stats, write_path=True, log=None):
+    """Build ``Record``s for beets items: map tags and resolve album art (with a
+    per-run cache; unreadable/over-cap covers counted into ``stats.skipped_art``).
+    When ``write_path`` is set, also emit a ``beets_path`` tag with the track's
+    beets library-relative path (extension stripped); a failed computation is
+    skipped and warned through ``log``. ``stats`` is mutated and must be the same
+    instance passed to ``sync_files``."""
+    records = []
+    art_cache = {}
+    for item in items:
+        cover = _read_album_art(item, art_cache, stats)
+        pairs = map_fields(item, fields)
+        if write_path:
+            path = _computed_path_or_skip(item, log)
+            if path:
+                pairs.append(("beets_path", path))
+        records.append(
+            Record(
+                key=realpath_key(item.path),
+                pairs=pairs,
+                art=[ArtImage(*cover)] if cover else None,
+            )
+        )
+    return records