lidarr-musefs 0.0.1__tar.gz

lidarr_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.

lidarr_musefs-0.0.1/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: lidarr-musefs
+Version: 0.0.1
+Summary: Sync Lidarr 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
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# lidarr-musefs
+
+A Lidarr integration that lets Lidarr import into a placeholder library tree
+while musefs serves the real consumer-facing, re-tagged FUSE view.
+
+The supported workflow keeps Lidarr as the downloader, matcher, and metadata
+source, but prevents Lidarr from copying, moving, or rewriting backing audio
+bytes. Lidarr's destination tree exists so Lidarr can track files. Point
+Navidrome, Plex, Jellyfin, or other consumers at the musefs mount instead.
+
+## Required Lidarr settings
+
+- Settings -> Media Management -> Import Using Script: enabled.
+- Import Script Path: `musefs-lidarr-import`.
+- Metadata Provider -> Write Audio Tags: `Never`.
+- File Date: `None`.
+- Linux permission management: disabled.
+
+Do not rely on Lidarr's built-in "Use Hardlinks instead of Copy" for this
+workflow. Lidarr uses a hardlink-or-copy transfer mode internally, so a hardlink
+failure can copy bytes. `musefs-lidarr-import` creates the destination entry
+itself and fails closed.
+
+## Environment
+
+Import script:
+
+```bash
+MUSEFS_LIDARR_LINK_MODE=symlink   # default; use hardlink only if symlinks are unsuitable
+```
+
+Sync script:
+
+```bash
+MUSEFS_DB=/path/to/musefs.db
+MUSEFS_BIN=musefs
+MUSEFS_LIDARR_URL=http://localhost:8686
+MUSEFS_LIDARR_API_KEY=your-api-key
+MUSEFS_LIDARR_AUTOSCAN=1
+```
+
+API keys are redacted from logs and errors.
+
+## Lidarr Custom Script
+
+Configure a Custom Script notification:
+
+- On Release Import: enabled.
+- On Rename: enabled.
+- Path: `musefs-lidarr-sync`.
+
+Test events exit successfully without touching files or the database.
+`TrackRetag` events are skipped with a warning because they fire after Lidarr
+writes tags.
+
+## Manual backfill
+
+Run:
+
+```bash
+musefs-lidarr-sync --all
+```
+
+Manual backfill requires `MUSEFS_LIDARR_URL` and `MUSEFS_LIDARR_API_KEY`. It
+queries all Lidarr artists and syncs their known track files into the musefs DB.
+
+## Doctor
+
+Run:
+
+```bash
+musefs-lidarr-sync --doctor
+```
+
+The doctor checks Lidarr's API for:
+
+- `writeAudioTags = no`
+- `fileDate = none`
+- `setPermissionsLinux = false`
+
+If `MUSEFS_LIDARR_URL` and `MUSEFS_LIDARR_API_KEY` are not configured, `doctor`
+and sync fail because the integration cannot verify safe settings or build
+complete per-track metadata.
+
+## Smoke test
+
+1. Build and install musefs.
+2. Install `python-musefs` and `lidarr-musefs` into the environment Lidarr uses
+   for custom scripts.
+3. Configure Import Using Script and Custom Script as described above.
+4. Import a small album.
+5. Confirm Lidarr's destination entry is a symlink by default.
+6. Run `musefs mount /tmp/mnt --db "$MUSEFS_DB"`.
+7. Confirm the mount shows Lidarr metadata.
+8. Confirm the source file's bytes and mtime did not change.

lidarr_musefs-0.0.1/README.md

@@ -0,0 +1,95 @@
+# lidarr-musefs
+
+A Lidarr integration that lets Lidarr import into a placeholder library tree
+while musefs serves the real consumer-facing, re-tagged FUSE view.
+
+The supported workflow keeps Lidarr as the downloader, matcher, and metadata
+source, but prevents Lidarr from copying, moving, or rewriting backing audio
+bytes. Lidarr's destination tree exists so Lidarr can track files. Point
+Navidrome, Plex, Jellyfin, or other consumers at the musefs mount instead.
+
+## Required Lidarr settings
+
+- Settings -> Media Management -> Import Using Script: enabled.
+- Import Script Path: `musefs-lidarr-import`.
+- Metadata Provider -> Write Audio Tags: `Never`.
+- File Date: `None`.
+- Linux permission management: disabled.
+
+Do not rely on Lidarr's built-in "Use Hardlinks instead of Copy" for this
+workflow. Lidarr uses a hardlink-or-copy transfer mode internally, so a hardlink
+failure can copy bytes. `musefs-lidarr-import` creates the destination entry
+itself and fails closed.
+
+## Environment
+
+Import script:
+
+```bash
+MUSEFS_LIDARR_LINK_MODE=symlink   # default; use hardlink only if symlinks are unsuitable
+```
+
+Sync script:
+
+```bash
+MUSEFS_DB=/path/to/musefs.db
+MUSEFS_BIN=musefs
+MUSEFS_LIDARR_URL=http://localhost:8686
+MUSEFS_LIDARR_API_KEY=your-api-key
+MUSEFS_LIDARR_AUTOSCAN=1
+```
+
+API keys are redacted from logs and errors.
+
+## Lidarr Custom Script
+
+Configure a Custom Script notification:
+
+- On Release Import: enabled.
+- On Rename: enabled.
+- Path: `musefs-lidarr-sync`.
+
+Test events exit successfully without touching files or the database.
+`TrackRetag` events are skipped with a warning because they fire after Lidarr
+writes tags.
+
+## Manual backfill
+
+Run:
+
+```bash
+musefs-lidarr-sync --all
+```
+
+Manual backfill requires `MUSEFS_LIDARR_URL` and `MUSEFS_LIDARR_API_KEY`. It
+queries all Lidarr artists and syncs their known track files into the musefs DB.
+
+## Doctor
+
+Run:
+
+```bash
+musefs-lidarr-sync --doctor
+```
+
+The doctor checks Lidarr's API for:
+
+- `writeAudioTags = no`
+- `fileDate = none`
+- `setPermissionsLinux = false`
+
+If `MUSEFS_LIDARR_URL` and `MUSEFS_LIDARR_API_KEY` are not configured, `doctor`
+and sync fail because the integration cannot verify safe settings or build
+complete per-track metadata.
+
+## Smoke test
+
+1. Build and install musefs.
+2. Install `python-musefs` and `lidarr-musefs` into the environment Lidarr uses
+   for custom scripts.
+3. Configure Import Using Script and Custom Script as described above.
+4. Import a small album.
+5. Confirm Lidarr's destination entry is a symlink by default.
+6. Run `musefs mount /tmp/mnt --db "$MUSEFS_DB"`.
+7. Confirm the mount shows Lidarr metadata.
+8. Confirm the source file's bytes and mtime did not change.

lidarr_musefs-0.0.1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lidarr-musefs"
+version = "0.0.1"
+description = "Sync Lidarr metadata into the musefs SQLite store"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Conor Futro" }]
+dependencies = ["python-musefs>=0.1.0"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Sound/Audio",
+]
+
+[project.urls]
+Homepage = "https://github.com/Sohex/musefs"
+Repository = "https://github.com/Sohex/musefs"
+Issues = "https://github.com/Sohex/musefs/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.scripts]
+musefs-lidarr-import = "musefs_lidarr.cli_import:main"
+musefs-lidarr-sync = "musefs_lidarr.cli_sync:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = [
+    "musefs_bin: tests that shell out to the real `musefs` Rust binary (opt-in)",
+]
+addopts = "-m 'not musefs_bin'"

lidarr_musefs-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lidarr_musefs-0.0.1/src/lidarr_musefs.egg-info/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: lidarr-musefs
+Version: 0.0.1
+Summary: Sync Lidarr 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
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# lidarr-musefs
+
+A Lidarr integration that lets Lidarr import into a placeholder library tree
+while musefs serves the real consumer-facing, re-tagged FUSE view.
+
+The supported workflow keeps Lidarr as the downloader, matcher, and metadata
+source, but prevents Lidarr from copying, moving, or rewriting backing audio
+bytes. Lidarr's destination tree exists so Lidarr can track files. Point
+Navidrome, Plex, Jellyfin, or other consumers at the musefs mount instead.
+
+## Required Lidarr settings
+
+- Settings -> Media Management -> Import Using Script: enabled.
+- Import Script Path: `musefs-lidarr-import`.
+- Metadata Provider -> Write Audio Tags: `Never`.
+- File Date: `None`.
+- Linux permission management: disabled.
+
+Do not rely on Lidarr's built-in "Use Hardlinks instead of Copy" for this
+workflow. Lidarr uses a hardlink-or-copy transfer mode internally, so a hardlink
+failure can copy bytes. `musefs-lidarr-import` creates the destination entry
+itself and fails closed.
+
+## Environment
+
+Import script:
+
+```bash
+MUSEFS_LIDARR_LINK_MODE=symlink   # default; use hardlink only if symlinks are unsuitable
+```
+
+Sync script:
+
+```bash
+MUSEFS_DB=/path/to/musefs.db
+MUSEFS_BIN=musefs
+MUSEFS_LIDARR_URL=http://localhost:8686
+MUSEFS_LIDARR_API_KEY=your-api-key
+MUSEFS_LIDARR_AUTOSCAN=1
+```
+
+API keys are redacted from logs and errors.
+
+## Lidarr Custom Script
+
+Configure a Custom Script notification:
+
+- On Release Import: enabled.
+- On Rename: enabled.
+- Path: `musefs-lidarr-sync`.
+
+Test events exit successfully without touching files or the database.
+`TrackRetag` events are skipped with a warning because they fire after Lidarr
+writes tags.
+
+## Manual backfill
+
+Run:
+
+```bash
+musefs-lidarr-sync --all
+```
+
+Manual backfill requires `MUSEFS_LIDARR_URL` and `MUSEFS_LIDARR_API_KEY`. It
+queries all Lidarr artists and syncs their known track files into the musefs DB.
+
+## Doctor
+
+Run:
+
+```bash
+musefs-lidarr-sync --doctor
+```
+
+The doctor checks Lidarr's API for:
+
+- `writeAudioTags = no`
+- `fileDate = none`
+- `setPermissionsLinux = false`
+
+If `MUSEFS_LIDARR_URL` and `MUSEFS_LIDARR_API_KEY` are not configured, `doctor`
+and sync fail because the integration cannot verify safe settings or build
+complete per-track metadata.
+
+## Smoke test
+
+1. Build and install musefs.
+2. Install `python-musefs` and `lidarr-musefs` into the environment Lidarr uses
+   for custom scripts.
+3. Configure Import Using Script and Custom Script as described above.
+4. Import a small album.
+5. Confirm Lidarr's destination entry is a symlink by default.
+6. Run `musefs mount /tmp/mnt --db "$MUSEFS_DB"`.
+7. Confirm the mount shows Lidarr metadata.
+8. Confirm the source file's bytes and mtime did not change.

lidarr_musefs-0.0.1/src/lidarr_musefs.egg-info/SOURCES.txt

@@ -0,0 +1,28 @@
+LICENSE
+README.md
+pyproject.toml
+src/lidarr_musefs.egg-info/PKG-INFO
+src/lidarr_musefs.egg-info/SOURCES.txt
+src/lidarr_musefs.egg-info/dependency_links.txt
+src/lidarr_musefs.egg-info/entry_points.txt
+src/lidarr_musefs.egg-info/requires.txt
+src/lidarr_musefs.egg-info/top_level.txt
+src/musefs_lidarr/__init__.py
+src/musefs_lidarr/api.py
+src/musefs_lidarr/cli_import.py
+src/musefs_lidarr/cli_sync.py
+src/musefs_lidarr/env.py
+src/musefs_lidarr/errors.py
+src/musefs_lidarr/events.py
+src/musefs_lidarr/import_link.py
+src/musefs_lidarr/mapping.py
+src/musefs_lidarr/sync.py
+tests/test_api.py
+tests/test_cli.py
+tests/test_env.py
+tests/test_events.py
+tests/test_import_link.py
+tests/test_mapping.py
+tests/test_path_gate.py
+tests/test_smoke.py
+tests/test_sync.py

lidarr_musefs-0.0.1/src/lidarr_musefs.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lidarr_musefs-0.0.1/src/lidarr_musefs.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+musefs-lidarr-import = musefs_lidarr.cli_import:main
+musefs-lidarr-sync = musefs_lidarr.cli_sync:main

lidarr_musefs-0.0.1/src/lidarr_musefs.egg-info/requires.txt

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

lidarr_musefs-0.0.1/src/lidarr_musefs.egg-info/top_level.txt

@@ -0,0 +1 @@
+musefs_lidarr

lidarr_musefs-0.0.1/src/musefs_lidarr/__init__.py

@@ -0,0 +1,3 @@
+"""Lidarr integration for syncing metadata into musefs."""
+
+__version__ = "0.1.0"

lidarr_musefs-0.0.1/src/musefs_lidarr/api.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from .errors import ConfigError, LidarrApiError
+
+
+def redacted(value: str | None) -> str:
+    """Return ``"<redacted>"`` for a non-empty value, else ``"<missing>"``."""
+    return "<redacted>" if value else "<missing>"
+
+
+@dataclass(frozen=True)
+class LidarrConfig:
+    """Lidarr API connection settings (URL and API key)."""
+
+    url: str | None = None
+    api_key: str | None = None
+
+    @classmethod
+    def from_env(cls, environ: dict[str, str] | None = None) -> "LidarrConfig":
+        """Read URL/key from ``MUSEFS_LIDARR_URL``/``MUSEFS_LIDARR_API_KEY``.
+
+        Raises ``ConfigError`` if only one of the two is set.
+        """
+        env = os.environ if environ is None else environ
+        url = env.get("MUSEFS_LIDARR_URL") or None
+        api_key = env.get("MUSEFS_LIDARR_API_KEY") or None
+        if bool(url) != bool(api_key):
+            raise ConfigError("MUSEFS_LIDARR_URL and MUSEFS_LIDARR_API_KEY must be set together")
+        return cls(url=url, api_key=api_key)
+
+    @property
+    def enabled(self) -> bool:
+        """True when both URL and API key are present."""
+        return bool(self.url and self.api_key)
+
+
+@dataclass(frozen=True)
+class PreflightResult:
+    """Outcome of the Lidarr settings preflight: ``ok`` plus any error strings."""
+
+    ok: bool
+    errors: list[str]
+
+
+class LidarrClient:
+    """Minimal read-only client for the Lidarr v1 REST API."""
+
+    def __init__(self, config: LidarrConfig, *, opener=urlopen, timeout: int = 15):
+        if not config.url or not config.api_key:
+            raise ConfigError("Lidarr API configuration is required")
+        self._base = config.url.rstrip("/")
+        self._api_key = config.api_key
+        self._opener = opener
+        self._timeout = timeout
+
+    def get_json(self, path: str, params: dict[str, object] | None = None):
+        """GET ``path`` with optional query params; return parsed JSON.
+
+        Raises ``LidarrApiError`` on HTTP, network, or JSON-decode failure.
+        """
+        query = ""
+        if params:
+            clean = {k: v for k, v in params.items() if v is not None}
+            if clean:
+                query = "?" + urlencode(clean, doseq=True)
+        url = f"{self._base}{path}{query}"
+        request = Request(url, headers={"X-Api-Key": self._api_key})
+        try:
+            with self._opener(request, timeout=self._timeout) as response:
+                return json.loads(response.read().decode("utf-8"))
+        except HTTPError as exc:
+            raise LidarrApiError(
+                f"Lidarr API request failed with HTTP {exc.code}; api_key={redacted(self._api_key)}"
+            ) from exc
+        except URLError as exc:
+            raise LidarrApiError(f"Lidarr API request failed: {exc.reason}") from exc
+        except json.JSONDecodeError as exc:
+            raise LidarrApiError("Lidarr API returned invalid JSON") from exc
+
+    def media_management_config(self):
+        """Return Lidarr's media-management config."""
+        return self.get_json("/api/v1/config/mediamanagement")
+
+    def metadata_provider_config(self):
+        """Return Lidarr's metadata-provider config."""
+        return self.get_json("/api/v1/config/metadataprovider")
+
+    def track_files(self, *, artist_id=None, album_id=None, track_file_ids=None):
+        """Return track files filtered by artist, album, or track-file ids."""
+        params = {}
+        if artist_id is not None:
+            params["artistId"] = artist_id
+        if album_id is not None:
+            params["albumId"] = album_id
+        if track_file_ids:
+            params["trackFileIds"] = list(track_file_ids)
+        return self.get_json("/api/v1/trackfile", params)
+
+    def tracks(self, *, artist_id=None, album_id=None, track_ids=None):
+        """Return tracks filtered by artist, album, or track ids."""
+        params = {}
+        if artist_id is not None:
+            params["artistId"] = artist_id
+        if album_id is not None:
+            params["albumId"] = album_id
+        if track_ids:
+            params["trackIds"] = list(track_ids)
+        return self.get_json("/api/v1/track", params)
+
+    def album(self, album_id: int):
+        """Return a single album by id."""
+        return self.get_json(f"/api/v1/album/{album_id}")
+
+    def artists(self):
+        """Return all artists in the Lidarr library."""
+        return self.get_json("/api/v1/artist")
+
+    def artist(self, artist_id: int):
+        """Return a single artist by id."""
+        return self.get_json(f"/api/v1/artist/{artist_id}")
+
+
+def _lower(value) -> str:
+    return str(value).strip().lower()
+
+
+def check_safe_settings(metadata: dict, media_management: dict) -> PreflightResult:
+    """Verify Lidarr won't mutate backing files.
+
+    Requires ``writeAudioTags=no``, ``fileDate=none``, and
+    ``setPermissionsLinux`` falsy; collects a message per violation.
+    """
+    errors = []
+    if _lower(metadata.get("writeAudioTags")) != "no":
+        errors.append(f"writeAudioTags must be no, got {metadata.get('writeAudioTags')}")
+    if _lower(media_management.get("fileDate")) != "none":
+        errors.append(f"fileDate must be none, got {media_management.get('fileDate')}")
+    if bool(media_management.get("setPermissionsLinux")):
+        errors.append("setPermissionsLinux must be false")
+    return PreflightResult(ok=not errors, errors=errors)
+
+
+def run_preflight(client: LidarrClient) -> PreflightResult:
+    """Fetch Lidarr's configs and run :func:`check_safe_settings`."""
+    return check_safe_settings(
+        metadata=client.metadata_provider_config(),
+        media_management=client.media_management_config(),
+    )

lidarr_musefs-0.0.1/src/musefs_lidarr/cli_import.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import os
+import sys
+
+from .env import lidarr_get
+from .errors import MusefsLidarrError
+from .import_link import ensure_link, parse_import_env
+
+
+def run(environ: dict[str, str] | None = None) -> int:
+    """Create the import link for one Lidarr script-import call; return exit code.
+
+    Lidarr's Test event is a no-op success. Other events read the source and
+    destination from the environment and create the link.
+    """
+    env = os.environ if environ is None else environ
+    if lidarr_get(env, "Lidarr_EventType") == "Test":
+        print("musefs-lidarr-import: test ok")
+        return 0
+
+    try:
+        request = parse_import_env(env)
+        ensure_link(request.source, request.destination, request.mode)
+        print(
+            f"musefs-lidarr-import: {request.mode.value} {request.source} -> {request.destination}"
+        )
+        return 0
+    except MusefsLidarrError as exc:
+        print(f"musefs-lidarr-import: {exc}", file=sys.stderr)
+        return 1
+
+
+def main() -> int:
+    return run()