beets-clapback 0.1.0__tar.gz

beets_clapback-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+ENV/
+.eggs/
+*.egg-info/
+*.egg
+
+# uv — `ADR-0005` point 7. The workspace has exactly one lock, at the root, and it
+# is committed. A lock never ships in a wheel: what `clapback-embed`'s dependents
+# resolve comes from its `dependencies` ranges, so committing this cannot pin them.
+# What it does pin is development, CI and the deployed image, which previously
+# resolved fresh on every Docker build.
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Docker
+data/
+
+# Environment
+.env
+.env.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Package venvs and exported model artifacts (614 MB, produced by scripts/export_models.py)
+packages/*/.venv/
+*.onnx
+*.onnx.data

beets_clapback-0.1.0/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.

beets_clapback-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,88 @@
+# 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/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)

beets_clapback-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "beets-clapback"
+version = "0.1.0"
+description = "beets plugin: look up, embed, and contribute CLAP embeddings to the clapback commons — absubmit reborn"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+authors = [{ name = "Jeff Crouse", email = "jeff@seethroughlab.com" }]
+keywords = ["beets", "clap", "audio", "embeddings", "music", "acoustid"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio :: Analysis",
+]
+
+# `clapback-client` is the contract; `clapback-embed` is the reference pipeline
+# this plugin embeds through, and where `PIPELINE_VERSION` comes from. beets users
+# have a library to embed, not their own embedder, so unlike the client the
+# embedder is not optional here — only its 614 MB of encoders are, at runtime.
+dependencies = [
+    "beets>=2.0",
+    "clapback-client>=0.1.0,<0.2",
+    "clapback-embed>=0.1.0,<0.2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.4.0", "ruff>=0.1.0", "pyacoustid>=1.3"]
+
+[project.urls]
+Homepage = "https://clapback.seethroughlab.com"
+Repository = "https://github.com/seethroughlab/clapback"
+Decisions = "https://github.com/seethroughlab/clapback/tree/main/docs/decisions"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# `beetsplug` is a PEP 420 namespace package shared by every beets plugin, so
+# this wheel ships `beetsplug/clapback.py` and no `__init__.py`.
+[tool.hatch.build.targets.wheel]
+packages = ["beetsplug"]
+
+[tool.uv.sources]
+clapback-client = { workspace = true }
+clapback-embed = { workspace = true }
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

beets_clapback-0.1.0/tests/test_plugin.py

@@ -0,0 +1,236 @@
+"""The plugin, driven through beets itself.
+
+`beets.test.helper.PluginTestHelper` loads `beetsplug.clapback` the way `beet`
+does and runs commands through `beets.ui`, so what is under test is the plugin
+as a beets user meets it — config keys, flexible attributes, the sidecar store,
+the summary line. Only two things are stubbed: the corpus (a scripted server
+that records what it was asked) and the embedder (which would otherwise need
+614 MB of ONNX encoders). Neither is the property under test.
+
+The properties are the ones `ADR-0011` point 5 and point 6 ask of any plug-in:
+look up before you contribute, contribute only when told to, never re-embed what
+is already embedded, hash canonically, and mint nothing for a user who has not
+contributed.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from beets.exceptions import UserError
+from beets.test.helper import PluginTestHelper
+
+import beetsplug.clapback as plug
+
+PIPELINE = "laion/clap-htsat-unfused+frontend1+artifact1+pool1+fp32"
+RAW_FP = "AQADtJESbVkUhYL84z4CnwZ4HsdxHD6P4_hx_EAO_cjx"
+
+
+def _unit(i: int) -> list[float]:
+    v = [0.0] * 512
+    v[i % 512] = 1.0
+    return v
+
+
+class FakeEmbed:
+    PIPELINE_VERSION = PIPELINE
+
+    class ArtifactsMissing(Exception):
+        pass
+
+    def __init__(self):
+        self.calls: list[str] = []
+
+    def embed_file(self, path):
+        self.calls.append(path)
+        return _unit(len(self.calls))
+
+    def embed_text(self, text):
+        # Point the query at the first embedded track.
+        return _unit(1)
+
+
+class FakeCorpus:
+    base_url = "https://example.invalid"
+
+    def __init__(self, *_a, **_k):
+        pass
+
+    # Class-level so the plugin's fresh instances share one script; the
+    # fixture resets them before every test.
+    holds: dict[tuple[str, str], list[float]] = {}  # noqa: RUF012
+    log: list[tuple] = []  # noqa: RUF012
+    unreachable = False
+
+    def lookup(self, h, pv):
+        FakeCorpus.log.append(("lookup", h, pv))
+        if FakeCorpus.unreachable:
+            raise plug.CorpusError("down")
+        return {"embedding": FakeCorpus.holds[(h, pv)]} if (h, pv) in FakeCorpus.holds else None
+
+    def contribute(self, **kw):
+        FakeCorpus.log.append(("contribute", kw["fingerprint_hash"], kw["pipeline_version"]))
+        FakeCorpus.last_kw = kw
+        return "contributed"
+
+
+class TestClapbackPlugin(PluginTestHelper):
+    plugin = "clapback"
+    preload_plugin = False
+
+    @pytest.fixture(autouse=True)
+    def _stubs(self, monkeypatch, setup):
+        # `setup` is the helper's own autouse fixture; naming it orders this
+        # one after beets is up and before it is torn down.
+        self.embed = FakeEmbed()
+        FakeCorpus.holds, FakeCorpus.log, FakeCorpus.unreachable = {}, [], False
+        monkeypatch.setattr(plug, "_embedder", lambda: self.embed)
+        monkeypatch.setattr(plug, "Corpus", FakeCorpus)
+
+    # --- helpers --------------------------------------------------------
+
+    def _track(self, title="t", fp=RAW_FP, **kw):
+        return self.add_item(title=title, acoustid_fingerprint=fp, **kw)
+
+    def _run(self, *args, **cfg):
+        with self.configure_plugin({"contribute": False, **cfg}):
+            self.run_command("clapback", *args)
+
+    def _kinds(self):
+        return [k for k, *_ in FakeCorpus.log]
+
+    def _store(self):
+        return json.loads((plug.Path(self.config.config_dir()) / "clapback" / "index.json").read_text())
+
+    # --- the four obligations ------------------------------------------
+
+    def test_a_hit_in_the_corpus_means_the_model_does_not_run(self):
+        """The whole exchange a plug-in makes."""
+        t = self._track()
+        FakeCorpus.holds[(plug.hash_fingerprint(RAW_FP), PIPELINE)] = _unit(7)
+        self._run()
+        t.load()
+        assert t.clapback_status == "found"
+        assert self.embed.calls == []
+        assert self._kinds() == ["lookup"]
+
+    def test_a_miss_is_embedded_and_kept_local_unless_asked(self, capsys):
+        """`ADR-0011` point 6: contribution is a second, separate setting."""
+        t = self._track()
+        self._run()
+        t.load()
+        assert t.clapback_status == "local"
+        assert len(self.embed.calls) == 1
+        assert "contribute" not in self._kinds()
+        assert "contribution is off" in capsys.readouterr().out
+
+    def test_contributing_sends_what_the_records_require(self):
+        t = self._track()
+        self._run(contribute=True)
+        t.load()
+        assert t.clapback_status == "contributed"
+        assert self._kinds() == ["lookup", "contribute"], "look up first, always"
+        kw = FakeCorpus.last_kw
+        assert kw["pipeline_version"] == PIPELINE
+        assert kw["client_id"]
+        assert len(kw["embedding"]) == 512
+
+    def test_the_hash_is_canonical_whatever_the_column_holds(self):
+        """`ADR-0010` point 2. beets' column measured clean on 99 tracks, but a
+        column is where the last defect hid, so the rule applies regardless."""
+        raw = self._track("raw", fp=RAW_FP)
+        esc = self._track("esc", fp="\\x" + RAW_FP.encode().hex())
+        self._run()
+        raw.load()
+        esc.load()
+        assert raw.clapback_hash == esc.clapback_hash
+
+    # --- restraint -------------------------------------------------------
+
+    def test_turning_contribution_on_later_does_not_re_embed(self):
+        """The vector is in the store; the model does not run again. This is
+        the path a user takes after indexing with contribution off."""
+        t = self._track()
+        self._run()
+        assert len(self.embed.calls) == 1
+        FakeCorpus.log.clear()
+        self._run(contribute=True)
+        t.load()
+        assert len(self.embed.calls) == 1, "re-embedded a track it already had"
+        assert t.clapback_status == "contributed"
+
+    def test_done_tracks_are_skipped_without_force(self):
+        self._track()
+        self._run(contribute=True)
+        FakeCorpus.log.clear()
+        self._run(contribute=True)
+        assert FakeCorpus.log == [], "a finished track went back to the corpus"
+        self._run("-f", contribute=True)
+        assert "lookup" in self._kinds()
+
+    def test_pretend_touches_nothing(self, capsys):
+        t = self._track()
+        self._run("-p", contribute=True)
+        t.load()
+        assert t.get("clapback_status") is None
+        assert FakeCorpus.log == [] and self.embed.calls == []
+        assert "would process" in capsys.readouterr().out
+
+    def test_no_identifier_is_minted_until_a_contribution_happens(self):
+        """`ADR-0009` point 4 covers the fact that an install exists."""
+        self._track()
+        self._run()
+        assert not (plug.Path(self.config.config_dir()) / "clapback" / "client_id").exists()
+        self._run(contribute=True)
+        assert (plug.Path(self.config.config_dir()) / "clapback" / "client_id").exists()
+
+    # --- when things are missing ----------------------------------------
+
+    def test_no_fingerprint_and_no_chromaprint_is_a_status_not_a_crash(self, monkeypatch):
+        monkeypatch.setattr(
+            plug, "fingerprint_file", lambda p: (_ for _ in ()).throw(
+                plug.FingerprintUnavailable("chromaprint is not installed")
+            )
+        )
+        t = self.add_item(title="nofp")
+        self._run()
+        t.load()
+        assert t.clapback_status == "unfingerprinted"
+        assert self.embed.calls == []
+
+    def test_an_unreachable_corpus_still_embeds_locally(self):
+        """Offline is a normal state. The store fills; nothing is sent."""
+        FakeCorpus.unreachable = True
+        t = self._track()
+        self._run(contribute=True)
+        t.load()
+        assert t.clapback_status == "local"
+        assert len(self.embed.calls) == 1
+        assert "contribute" not in self._kinds()
+
+    def test_a_store_from_another_pipeline_is_refused(self):
+        """`ADR-0006` point 5: recomputed, not relabelled."""
+        self._track()
+        self._run()
+        idx = plug.Path(self.config.config_dir()) / "clapback" / "index.json"
+        data = json.loads(idx.read_text())
+        data["pipeline_version"] = "something+else"
+        idx.write_text(json.dumps(data))
+        with pytest.raises(UserError, match="Delete the store"):
+            self._run("-f")
+
+    # --- the local value ------------------------------------------------
+
+    def test_search_ranks_the_matching_track_first(self, capsys):
+        """`ADR-0001` point 8: worth running with the corpus empty."""
+        a = self._track("alpha", fp=RAW_FP)
+        b = self._track("beta", fp=RAW_FP[::-1])
+        self._run()
+        capsys.readouterr()  # drop the run's summary line
+        with self.configure_plugin({}):
+            self.run_command("clapback-search", "anything at all")
+        out = capsys.readouterr().out.strip().splitlines()
+        assert "alpha" in out[0]
+        assert self._store()["pipeline_version"] == PIPELINE
+        assert sorted(self._store()["ids"]) == sorted([a.id, b.id])