beets-clapback 0.1.0__py3-none-any.whl

beets_clapback-0.1.0.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.5
+Name: beets-clapback
+Version: 0.1.0
+Summary: beets plugin: look up, embed, and contribute CLAP embeddings to the clapback commons — absubmit reborn
+Project-URL: Homepage, https://clapback.seethroughlab.com
+Project-URL: Repository, https://github.com/seethroughlab/clapback
+Project-URL: Decisions, https://github.com/seethroughlab/clapback/tree/main/docs/decisions
+Author-email: Jeff Crouse <jeff@seethroughlab.com>
+License: MIT License
+        
+        Copyright (c) 2026 Jeff Crouse
+        
+        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.
+License-File: LICENSE
+Keywords: acoustid,audio,beets,clap,embeddings,music
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Python: >=3.11
+Requires-Dist: beets>=2.0
+Requires-Dist: clapback-client<0.2,>=0.1.0
+Requires-Dist: clapback-embed<0.2,>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pyacoustid>=1.3; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# beets-clapback
+
+Look up, embed, and — if you say so — contribute CLAP embeddings for your beets library to the
+[clapback](https://clapback.seethroughlab.com) commons. `absubmit` reborn, with a payload that can
+actually be reconciled across contributors.
+
+```bash
+pip install beets-clapback
+```
+
+```yaml
+plugins: chroma clapback
+
+clapback:
+  contribute: no      # opt-in. Turn it on when you have read "what leaves the machine".
+```
+
+```bash
+beet clapback                        # every track: look up, else embed; contribute if enabled
+beet clapback artist:Autechre        # any beets query
+beet clapback -p                     # say what would happen, touch nothing
+beet clapback-search "dreamy ambient with piano"
+```
+
+## What it does
+
+For each track: hash the AcoustID fingerprint the `chroma` plugin already stored (or compute one),
+ask the commons whether it holds an embedding for that recording from the reference pipeline, and
+if so take it — the model does not run. If not, embed locally with
+[`clapback-embed`](https://pypi.org/project/clapback-embed/), keep the vector, and contribute it
+back only when `contribute: yes`.
+
+Two flexible attributes land on each item, so you can query them like anything else:
+
+| field | values |
+|---|---|
+| `clapback_hash` | the corpus key — SHA256 of the fingerprint |
+| `clapback_status` | `found` · `contributed` · `local` · `unfingerprinted` · `unembedded` |
+
+```bash
+beet ls clapback_status:local        # embedded here, not yet in the commons
+beet ls -a clapback_status:found     # albums the commons already had
+```
+
+The vectors live in `clapback/` under your beets config directory, so `clapback-search` works
+offline over everything embedded or fetched. Delete that directory and nothing is lost but time.
+
+## What it needs
+
+- **`chroma`** enabled, or `chromaprint` installed so this plugin can fingerprint itself. `chroma`
+  is the better answer — it stores the fingerprint once and every plugin benefits.
+- **The ONNX encoders** for `clapback-embed`, 614 MB, not bundled:
+  ```bash
+  pip install 'clapback-embed[export]'
+  python -m clapback_embed.scripts.export_models --out ~/.cache/clapback/models
+  ```
+  Without them, lookups still work; embedding does not, and the plugin says so.
+
+## What leaves the machine
+
+Nothing until `contribute: yes`. Then, per track the commons did not already hold: a 512-float
+vector and a one-way hash. **Never audio, never paths, never tags.** The hash cannot be reversed
+into the fingerprint, and the fingerprint is not the audio.
+
+The first contribution mints a random `client_id` — a UUID, derived from nothing about you or
+your machine — and stores it at `clapback/client_id` under your config directory. It lets the
+commons tell two contributions apart from one client retrying. Delete it and you are a new
+contributor; nothing else changes.
+
+## Options
+
+```yaml
+clapback:
+  url: https://clapback.seethroughlab.com
+  contribute: no     # send vectors the commons lacks
+  auto: no           # run on every import (embedding is minutes per album; off by default)
+  pace: 0.15         # seconds between contributions
+```
+
+## Why this exists
+
+beets shipped `acousticbrainz` and `absubmit` for years. Both were deprecated when AcousticBrainz
+shut down, and the suggested replacement was to compute locally and keep the results. This is the
+other half back — with a difference that matters: AcousticBrainz pooled *estimates* (bpm, key,
+mood) that could never be reconciled between contributors. An embedding from a pinned pipeline
+can be. When two people contribute the same recording, the commons can say whether they agree.
+The reasoning is in
+[`ADR-0011`](https://github.com/seethroughlab/clapback/blob/main/docs/decisions/ADR-0011-the-commons-is-what-other-tools-plug-into.md).

beets_clapback-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+beetsplug/clapback.py,sha256=LKCouRJ7XhMYQILSavlho3WOyY4IcW-sqgU_8H4vPX0,14517
+beets_clapback-0.1.0.dist-info/METADATA,sha256=TiwanZzFZ22HtwqOSzQ1zJMJx9QnLRS5h0IW76V1icw,6230
+beets_clapback-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+beets_clapback-0.1.0.dist-info/licenses/LICENSE,sha256=6Tfw3KwvxvDfednEoMB-s180r3b0xff9qWj57iXpiGs,1068
+beets_clapback-0.1.0.dist-info/RECORD,,

beets_clapback-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

beets_clapback-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Crouse
+
+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.

beetsplug/clapback.py

@@ -0,0 +1,346 @@
+"""beets-clapback — look up, embed, and (if you say so) contribute.
+
+`ADR-0011` point 5's first integration, and `absubmit` reborn with a better
+payload. beets shipped `acousticbrainz` and `absubmit` for years; both were
+deprecated when AcousticBrainz died, and the suggested replacement was to compute
+locally and keep the results. This is the other half back.
+
+    beet clapback                # every track: look up, else embed; contribute if enabled
+    beet clapback -p             # say what would happen, touch nothing
+    beet clapback artist:Autechre
+    beet clapback-search "dreamy ambient with piano"
+
+What it stores on each item, as flexible attributes you can query and see:
+
+    clapback_hash      the corpus key — SHA256 of the AcoustID fingerprint
+    clapback_status    found | contributed | local | unfingerprinted | unembedded
+
+The embeddings themselves live in a sidecar store under your beets config
+directory, keyed by item id, so `clapback-search` works offline over what has
+been embedded or fetched.
+
+What leaves the machine, and only when `contribute: yes`: a 512-float vector and
+a one-way hash. Never audio, never paths, never tags. The hash cannot be reversed
+into the fingerprint, and the fingerprint is not the audio.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from beets import config as beets_config
+from beets import plugins, ui
+from beets.exceptions import UserError
+from clapback_client import (
+    Corpus,
+    CorpusError,
+    FingerprintUnavailable,
+    ensure_client_id,
+    fingerprint_file,
+    hash_fingerprint,
+)
+
+#: The flexible attributes this plugin writes. Named so they group in `beet ls`.
+HASH_FIELD = "clapback_hash"
+STATUS_FIELD = "clapback_status"
+
+
+def _embedder():
+    """`clapback-embed`, imported lazily so `beet` starts fast and a missing model
+    is reported by the command that needs it rather than at plugin load."""
+    import clapback_embed
+
+    return clapback_embed
+
+
+class _Store:
+    """Vectors by item id, in two files under the beets config directory.
+
+    The same shape as the reference client's store — a `.npy` of rows and a
+    small JSON index — because it is the smallest thing that answers a search:
+    a text query is one dot product against every row, and a `.npy` loads into
+    exactly the array that needs. Not the beets database, which stores flexible
+    attributes as strings and would make `beet ls` print 512 floats.
+    """
+
+    def __init__(self, home: Path) -> None:
+        self.home = home
+        self.vectors_path = home / "vectors.npy"
+        self.index_path = home / "index.json"
+        self.ids: list[int] = []
+        self.pipeline_version: str | None = None
+        self._vectors = None
+
+    def load(self) -> _Store:
+        import numpy as np
+
+        if self.index_path.exists():
+            data = json.loads(self.index_path.read_text())
+            self.ids = [int(i) for i in data.get("ids", [])]
+            self.pipeline_version = data.get("pipeline_version")
+        if self.vectors_path.exists():
+            self._vectors = np.load(self.vectors_path)
+        else:
+            self._vectors = np.zeros((0, 512), dtype=np.float32)
+        if len(self.ids) != len(self._vectors):
+            # Two halves that disagree attribute every result to the wrong track.
+            self.ids, self._vectors = [], np.zeros((0, 512), dtype=np.float32)
+        return self
+
+    def save(self) -> None:
+        import numpy as np
+
+        self.home.mkdir(parents=True, exist_ok=True)
+        np.save(self.vectors_path, self._vectors)
+        self.index_path.write_text(
+            json.dumps({"pipeline_version": self.pipeline_version, "ids": self.ids}, indent=1)
+        )
+
+    def __contains__(self, item_id: int) -> bool:
+        return item_id in self.ids
+
+    def put(self, item_id: int, vector: list[float]) -> None:
+        import numpy as np
+
+        v = np.asarray(vector, dtype=np.float32).reshape(1, -1)
+        if item_id in self.ids:
+            self._vectors[self.ids.index(item_id)] = v
+            return
+        self.ids.append(item_id)
+        self._vectors = np.vstack([self._vectors, v]) if len(self._vectors) else v
+
+    def get(self, item_id: int) -> list[float] | None:
+        if item_id not in self.ids:
+            return None
+        return [float(x) for x in self._vectors[self.ids.index(item_id)]]
+
+    def nearest(self, query, limit: int) -> list[tuple[int, float]]:
+        import numpy as np
+
+        if not len(self._vectors):
+            return []
+        sims = self._vectors @ np.asarray(query, dtype=np.float32)
+        top = np.argsort(-sims)[:limit]
+        return [(self.ids[int(i)], float(sims[i])) for i in top]
+
+
+class ClapbackPlugin(plugins.BeetsPlugin):
+    def __init__(self) -> None:
+        super().__init__()
+        self.config.add(
+            {
+                "url": "https://clapback.seethroughlab.com",
+                # `ADR-0011` point 6: opt-in, and a second setting from lookup.
+                # A plugin in somebody else's software has less standing to
+                # assume consent, not more.
+                "contribute": False,
+                # Run on import. Off by default because embedding is minutes per
+                # album on a laptop and an import should not silently become that.
+                "auto": False,
+                "pace": 0.15,
+            }
+        )
+        if self.config["auto"].get(bool):
+            self.register_listener("album_imported", self._on_album_imported)
+            self.register_listener("item_imported", self._on_item_imported)
+
+    # --- where things live --------------------------------------------------
+
+    def _home(self) -> Path:
+        return Path(beets_config.config_dir()) / "clapback"
+
+    def _client_id(self) -> str:
+        """Minted on first contribution and never before — `ADR-0009` point 4
+        covers the fact that an install exists. Stored as a file the user can
+        find and delete; deleting it makes them a new contributor."""
+        return ensure_client_id(self._home() / "client_id")
+
+    # --- the commands -------------------------------------------------------
+
+    def commands(self) -> list[ui.Subcommand]:
+        run = ui.Subcommand(
+            "clapback", help="look up or embed tracks; contribute if enabled"
+        )
+        run.parser.add_option(
+            "-p", "--pretend", action="store_true", help="say what would happen, touch nothing"
+        )
+        run.parser.add_option(
+            "-f", "--force", action="store_true", help="re-process tracks already done"
+        )
+        run.func = self._cmd_run
+
+        search = ui.Subcommand(
+            "clapback-search", help="find tracks matching a description"
+        )
+        search.parser.add_option("-n", "--limit", type="int", default=10)
+        search.func = self._cmd_search
+        return [run, search]
+
+    def _cmd_run(self, lib, opts, args) -> None:
+        items = list(lib.items(args))
+        if not items:
+            raise UserError("no tracks match")
+        self._process(lib, items, pretend=opts.pretend, force=opts.force)
+
+    def _cmd_search(self, lib, opts, args) -> None:
+        description = " ".join(args).strip()
+        if not description:
+            raise UserError("give a description: beet clapback-search \"dreamy ambient\"")
+        embed = _embedder()
+        store = _Store(self._home()).load()
+        if not store.ids:
+            raise UserError("nothing embedded yet — run: beet clapback")
+        query = embed.embed_text(description)
+        for item_id, score in store.nearest(query, opts.limit):
+            item = lib.get_item(item_id)
+            if item is not None:
+                ui.print_(f"{score:.4f}  {item}")
+
+    # --- import hooks -------------------------------------------------------
+
+    def _on_album_imported(self, lib, album) -> None:
+        self._process(lib, list(album.items()), pretend=False, force=False)
+
+    def _on_item_imported(self, lib, item) -> None:
+        self._process(lib, [item], pretend=False, force=False)
+
+    # --- the work -----------------------------------------------------------
+
+    def _process(self, lib, items, *, pretend: bool, force: bool) -> None:
+        """Look up, else embed; contribute if enabled. Over these items."""
+        import time
+
+        contribute = self.config["contribute"].get(bool)
+        pace = self.config["pace"].as_number()
+        corpus = Corpus(self.config["url"].as_str())
+
+        embed = _embedder()
+        pipeline_version = embed.PIPELINE_VERSION
+        store = _Store(self._home()).load()
+        if store.pipeline_version and store.pipeline_version != pipeline_version:
+            # A store from a different pipeline cannot be searched alongside
+            # this one, and its vectors cannot be contributed under this
+            # identity (`ADR-0006` point 5: recomputed, not relabelled).
+            raise UserError(
+                f"the local store was built by {store.pipeline_version}\n"
+                f"and the installed embedder is  {pipeline_version}.\n"
+                "Delete the store to re-embed under the new pipeline:\n"
+                f"  {self._home()}"
+            )
+        store.pipeline_version = pipeline_version
+
+        client_id = None
+        found = contributed = local = unfingerprinted = unembedded = skipped = 0
+        try:
+            for n, item in enumerate(items, start=1):
+                if not force and item.get(STATUS_FIELD) in ("found", "contributed") and item.id in store:
+                    skipped += 1
+                    continue
+
+                # 1. The key. beets' `chroma` plugin stores the fingerprint as
+                #    chromaprint returned it — measured 2026-09-13 on 99 tracks,
+                #    99 byte-identical — but it goes through `hash_fingerprint`
+                #    regardless, because `ADR-0010`'s defect came from a column.
+                fp = item.get("acoustid_fingerprint")
+                if not fp:
+                    try:
+                        fp = fingerprint_file(os.fsdecode(item.path))
+                    except FingerprintUnavailable as exc:
+                        self._log.info("{0}: no fingerprint ({1})", item, exc)
+                        unfingerprinted += 1
+                        if not pretend:
+                            item[STATUS_FIELD] = "unfingerprinted"
+                            item.store()
+                        continue
+                key = hash_fingerprint(fp)
+
+                if pretend:
+                    ui.print_(f"would process: {item}")
+                    continue
+
+                # 2. Look up before anything else. A hit means the commons has
+                #    done the work; it also means we must not POST, because a
+                #    repeat submission is recorded as agreement (`ADR-0008`).
+                try:
+                    row = corpus.lookup(key, pipeline_version)
+                except CorpusError as exc:
+                    self._log.warning("corpus unreachable: {0}", exc)
+                    row = None
+                    corpus_ok = False
+                else:
+                    corpus_ok = True
+
+                if row is not None:
+                    store.put(item.id, row["embedding"])
+                    item[HASH_FIELD] = key
+                    item[STATUS_FIELD] = "found"
+                    item.store()
+                    found += 1
+                    continue
+
+                # 3. Embed locally — unless a previous run already did, in which
+                #    case the vector is in the store and the model does not run.
+                #    This is the path a user takes when they turn `contribute`
+                #    on after indexing: everything they already embedded goes
+                #    out without being recomputed.
+                vector = store.get(item.id)
+                if vector is None:
+                    try:
+                        vector = [float(x) for x in embed.embed_file(os.fsdecode(item.path))]
+                    except embed.ArtifactsMissing:
+                        raise UserError(
+                            "the ONNX encoders are missing — they are 614 MB and not bundled. "
+                            "Export them once with clapback-embed's scripts/export_models.py, "
+                            "or set CLAPBACK_MODEL_DIR to where they already are."
+                        ) from None
+                    except Exception as exc:  # noqa: BLE001 - one bad file must not end the run
+                        self._log.info("{0}: could not embed ({1})", item, exc)
+                        unembedded += 1
+                        item[STATUS_FIELD] = "unembedded"
+                        item.store()
+                        continue
+                    store.put(item.id, vector)
+                item[HASH_FIELD] = key
+
+                # 4. Contribute, if and only if asked.
+                if contribute and corpus_ok:
+                    if client_id is None:
+                        client_id = self._client_id()
+                    try:
+                        corpus.contribute(
+                            fingerprint_hash=key,
+                            embedding=vector,
+                            pipeline_version=pipeline_version,
+                            client_id=client_id,
+                        )
+                    except CorpusError as exc:
+                        self._log.warning("{0}: not contributed ({1})", item, exc)
+                        item[STATUS_FIELD] = "local"
+                        local += 1
+                    else:
+                        item[STATUS_FIELD] = "contributed"
+                        contributed += 1
+                        time.sleep(pace)
+                else:
+                    item[STATUS_FIELD] = "local"
+                    local += 1
+                item.store()
+
+                if n % 25 == 0:
+                    store.save()
+                    self._log.info("{0}/{1}", n, len(items))
+        finally:
+            if not pretend:
+                store.save()
+
+        if pretend:
+            return
+        summary = (
+            f"found in corpus {found} · contributed {contributed} · local only {local} · "
+            f"no fingerprint {unfingerprinted} · unembeddable {unembedded} · already done {skipped}"
+        )
+        if not contribute and local:
+            summary += "\n(contribution is off; set clapback.contribute: yes to send local vectors)"
+        ui.print_(summary)