libavalon 0.0.1__tar.gz

libavalon-0.0.1/.env.sample

@@ -0,0 +1,2 @@
+ACOUSTID_API_KEY=xxx
+DISCOGS_TOKEN=xxx

libavalon-0.0.1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+*.egg-info/
+dist/
+.DS_Store
+.avalon_state.json
+.env
+smoke_test_output/
+scratch/

libavalon-0.0.1/.python-version

@@ -0,0 +1 @@
+3.11

libavalon-0.0.1/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Brian Abelson
+
+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.

libavalon-0.0.1/Makefile

@@ -0,0 +1,14 @@
+.PHONY: lint test build upload
+
+lint:
+	uv run ruff check .
+
+test:
+	uv run --extra test pytest
+
+build:
+	rm -rf dist
+	uv run python -m build
+
+upload: build
+	uv run twine upload dist/*

libavalon-0.0.1/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: libavalon
+Version: 0.0.1
+Summary: Standalone audio analysis, tagging, and organization CLI
+Author: abelsonlive
+License: MIT
+License-File: LICENSE
+Requires-Python: <3.12,>=3.10
+Requires-Dist: essentia-tensorflow==2.1b6.dev1110
+Requires-Dist: ffmpeg-python>=0.2.0
+Requires-Dist: mutagen>=1.48.0
+Requires-Dist: numpy<2
+Requires-Dist: requests>=2.31.0
+Requires-Dist: watchdog>=6.0.0
+Provides-Extra: test
+Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# avalon
+
+Analyzes, tags, and organizes a music library:
+- BPM/key extraction, mood/genre/energy descriptors via Essentia
+- ID3/Vorbis/MP4 tag normalization
+- cover art, format conversion
+
+Runs once over a folder or as a watching daemon. MusicBrainz/Discogs
+reconciliation is left to Picard.
+
+## Requirements
+
+- Python 3.10–3.11 (see the `essentia-tensorflow` pin in `pyproject.toml` for why)
+- [uv](https://docs.astral.sh/uv/)
+- `ffmpeg` on `PATH` — `brew install ffmpeg` / `apt install ffmpeg`
+
+## Install
+
+```bash
+git clone <repository-url> && cd avalon
+uv sync
+```
+
+OR 
+
+```shell
+pip install libavalon
+```
+
+First run downloads Essentia's models (~26.5MB) to `~/.cache/avalon/models/`.
+
+## Usage
+
+```bash
+# tag in place
+uv run avalon analyze ~/Music/Downloads --recursive
+
+# reorganize into {artist}/{album}/{title}.{ext}
+uv run avalon analyze ~/Music/Downloads --recursive --dest ~/Music/Library
+
+# convert lossless sources, cap bit depth/sample rate (lossy sources untouched)
+uv run avalon analyze ~/Music/Downloads --dest ~/Music/Library \
+    --convert-lossless-to aiff --max-bit-depth 16 --max-sample-rate 48000
+
+# watch continuously, -v so you can see it working (backfills on startup)
+uv run avalon watch ~/Music/Downloads --dest ~/Music/Library -v
+
+# backfill a large library faster with 8 concurrent worker processes
+uv run avalon analyze ~/Music/Downloads --recursive --dest ~/Music/Library --workers 8
+
+# see what's actually in a file's tags
+uv run avalon inspect ~/Music/Library/Artist/Album/01\ -\ Title.aiff
+```
+
+Full flag list: `avalon analyze --help` / `avalon watch --help`.
+
+## How it works
+
+```mermaid
+flowchart TD
+    src[source file]
+    src --> analyze[essentia analysis]
+    src --> conv{convert?}
+    conv -->|yes| ffmpeg
+    conv -->|no| copy[copy in place]
+    analyze --> write[write tags + art]
+    ffmpeg --> write
+    copy --> write
+    write --> out[output file]
+```
+
+Analysis runs against the original file, before any conversion. Canonical
+fields (title/artist/album/genre/bpm/key) only fill in when missing —
+nothing gets overwritten unless you pass `--force-reanalyze`.
+
+`--workers N` runs analysis in N separate worker processes instead of one
+at a time — each has its own Essentia/TensorFlow session, so results never
+cross between files. Destination-path collisions (e.g. two files with
+missing tags both falling back to the same `Unknown Artist/Unknown Album`
+path) are still resolved from a single process before any work is handed
+to a worker, so numbering stays correct under `--workers` too.
+
+## Tags
+
+Two avalon-owned tags per file: a short headline (`bpm:128;key:Am;camelot:8A;
+energy:0.71;genre:Techno`, in COMM/DESCRIPTION/desc, configurable via
+`--headline-tag`/`--headline-format`) and an extended tag with the full
+descriptor roster (`TXXX:AVALON_ANALYSIS` / a Vorbis field / an MP4 atom).
+
+MusicBrainz/Discogs/AcoustID reconciliation isn't handled by avalon — run
+[Picard](https://picard.musicbrainz.org/) over the library separately for that.
+
+## Development
+
+```bash
+uv sync --extra test
+uv run pytest
+```

libavalon-0.0.1/README.md

@@ -0,0 +1,98 @@
+# avalon
+
+Analyzes, tags, and organizes a music library:
+- BPM/key extraction, mood/genre/energy descriptors via Essentia
+- ID3/Vorbis/MP4 tag normalization
+- cover art, format conversion
+
+Runs once over a folder or as a watching daemon. MusicBrainz/Discogs
+reconciliation is left to Picard.
+
+## Requirements
+
+- Python 3.10–3.11 (see the `essentia-tensorflow` pin in `pyproject.toml` for why)
+- [uv](https://docs.astral.sh/uv/)
+- `ffmpeg` on `PATH` — `brew install ffmpeg` / `apt install ffmpeg`
+
+## Install
+
+```bash
+git clone <repository-url> && cd avalon
+uv sync
+```
+
+OR 
+
+```shell
+pip install libavalon
+```
+
+First run downloads Essentia's models (~26.5MB) to `~/.cache/avalon/models/`.
+
+## Usage
+
+```bash
+# tag in place
+uv run avalon analyze ~/Music/Downloads --recursive
+
+# reorganize into {artist}/{album}/{title}.{ext}
+uv run avalon analyze ~/Music/Downloads --recursive --dest ~/Music/Library
+
+# convert lossless sources, cap bit depth/sample rate (lossy sources untouched)
+uv run avalon analyze ~/Music/Downloads --dest ~/Music/Library \
+    --convert-lossless-to aiff --max-bit-depth 16 --max-sample-rate 48000
+
+# watch continuously, -v so you can see it working (backfills on startup)
+uv run avalon watch ~/Music/Downloads --dest ~/Music/Library -v
+
+# backfill a large library faster with 8 concurrent worker processes
+uv run avalon analyze ~/Music/Downloads --recursive --dest ~/Music/Library --workers 8
+
+# see what's actually in a file's tags
+uv run avalon inspect ~/Music/Library/Artist/Album/01\ -\ Title.aiff
+```
+
+Full flag list: `avalon analyze --help` / `avalon watch --help`.
+
+## How it works
+
+```mermaid
+flowchart TD
+    src[source file]
+    src --> analyze[essentia analysis]
+    src --> conv{convert?}
+    conv -->|yes| ffmpeg
+    conv -->|no| copy[copy in place]
+    analyze --> write[write tags + art]
+    ffmpeg --> write
+    copy --> write
+    write --> out[output file]
+```
+
+Analysis runs against the original file, before any conversion. Canonical
+fields (title/artist/album/genre/bpm/key) only fill in when missing —
+nothing gets overwritten unless you pass `--force-reanalyze`.
+
+`--workers N` runs analysis in N separate worker processes instead of one
+at a time — each has its own Essentia/TensorFlow session, so results never
+cross between files. Destination-path collisions (e.g. two files with
+missing tags both falling back to the same `Unknown Artist/Unknown Album`
+path) are still resolved from a single process before any work is handed
+to a worker, so numbering stays correct under `--workers` too.
+
+## Tags
+
+Two avalon-owned tags per file: a short headline (`bpm:128;key:Am;camelot:8A;
+energy:0.71;genre:Techno`, in COMM/DESCRIPTION/desc, configurable via
+`--headline-tag`/`--headline-format`) and an extended tag with the full
+descriptor roster (`TXXX:AVALON_ANALYSIS` / a Vorbis field / an MP4 atom).
+
+MusicBrainz/Discogs/AcoustID reconciliation isn't handled by avalon — run
+[Picard](https://picard.musicbrainz.org/) over the library separately for that.
+
+## Development
+
+```bash
+uv sync --extra test
+uv run pytest
+```

libavalon-0.0.1/avalon/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

libavalon-0.0.1/avalon/analysis/essentia_analyzer.py

@@ -0,0 +1,140 @@
+"""Runs the full Essentia extraction roster against audio files.
+
+One embedding pass (discogs-effnet) feeds every classifier head, so
+breadth is cheap -- this is the "extract as much information as we can
+from essentia" implementation, not a curated subset.
+
+Loading a TensorFlow graph has real fixed overhead (~1-2s each); with 14
+classifier heads plus the embedding extractor, reloading all of them for
+every file measured at ~25s/track. Loading them once and reusing the
+loaded graphs across files drops that to ~1.1s/track (measured), which is
+the difference between a usable batch tool and one that takes days on a
+real library. `EssentiaAnalyzer` is therefore a reusable object, not a
+stateless function: construct one per CLI run and call `.analyze()` per
+file.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+import numpy as np
+
+from avalon.analysis import model_cache
+from avalon.constants import to_camelot
+from avalon.models import Label, TrackAnalysis
+
+logger = logging.getLogger(__name__)
+
+_ANALYSIS_SAMPLE_RATE = 44100
+_EMBEDDING_SAMPLE_RATE = 16000
+_TOP_N_BY_MODEL = {"genre_discogs400": 3, "mtg_jamendo_moodtheme": 5}
+
+
+def _clean_label(raw: str) -> str:
+    """ "Electronic---Techno" -> "Electronic / Techno" for readability."""
+    return raw.replace("---", " / ")
+
+
+class EssentiaAnalyzer:
+    """Loads every model once; call `analyze(path)` per file."""
+
+    def __init__(self) -> None:
+        os.environ.setdefault("TF_CPP_MIN_LOG_LEVEL", "3")
+
+        import essentia
+        import essentia.standard as es
+
+        essentia.log.warningActive = False
+        essentia.log.infoActive = False
+
+        self._es = es
+        embedding_pb, embedding_output = model_cache.get_embedding_model()
+        self._embedding_algo = es.TensorflowPredictEffnetDiscogs(
+            graphFilename=embedding_pb, output=embedding_output
+        )
+        self._classifiers: dict[str, tuple[object, model_cache.ModelMeta]] = {}
+        for spec in model_cache.CLASSIFIER_HEADS:
+            meta = model_cache.get_classifier(spec)
+            algo = es.TensorflowPredict2D(
+                graphFilename=meta.pb_path,
+                input=meta.input_name,
+                output=meta.output_name,
+            )
+            self._classifiers[spec.name] = (algo, meta)
+
+    def analyze(self, path: str) -> TrackAnalysis:
+        es = self._es
+
+        rhythm_audio = es.MonoLoader(filename=path, sampleRate=_ANALYSIS_SAMPLE_RATE)()
+        bpm, _beats, bpm_confidence, _estimates, _intervals = es.RhythmExtractor2013(
+            method="multifeature"
+        )(rhythm_audio)
+        key, scale, key_strength = es.KeyExtractor()(rhythm_audio)
+        dynamic_complexity, loudness = es.DynamicComplexity()(rhythm_audio)
+
+        embedding_audio = es.Resample(
+            inputSampleRate=_ANALYSIS_SAMPLE_RATE,
+            outputSampleRate=_EMBEDDING_SAMPLE_RATE,
+            quality=4,
+        )(rhythm_audio)
+        embeddings = self._embedding_algo(embedding_audio)
+
+        binary_probs: dict[str, float] = {}
+        categorical: dict[str, tuple[str, float]] = {}
+        multilabel: dict[str, list[Label]] = {}
+
+        for spec in model_cache.CLASSIFIER_HEADS:
+            algo, meta = self._classifiers[spec.name]
+            track_scores = np.mean(algo(embeddings), axis=0)
+
+            if spec.kind == "binary":
+                binary_probs[spec.name] = float(
+                    track_scores[meta.classes.index(spec.positive_label)]
+                )
+            elif spec.kind == "categorical":
+                idx = int(np.argmax(track_scores))
+                categorical[spec.name] = (meta.classes[idx], float(track_scores[idx]))
+            elif spec.kind == "multilabel":
+                top_n = _TOP_N_BY_MODEL[spec.name]
+                order = np.argsort(track_scores)[::-1][:top_n]
+                multilabel[spec.name] = [
+                    Label(
+                        name=_clean_label(meta.classes[i]),
+                        confidence=float(track_scores[i]),
+                    )
+                    for i in order
+                ]
+            else:
+                raise ValueError(f"Unknown model kind: {spec.kind!r}")
+
+        gender_label, gender_confidence = categorical["gender"]
+        timbre_label, timbre_confidence = categorical["timbre"]
+
+        return TrackAnalysis(
+            bpm=float(bpm),
+            bpm_confidence=float(bpm_confidence),
+            key=key,
+            scale=scale,
+            camelot=to_camelot(key, scale),
+            key_strength=float(key_strength),
+            loudness=float(loudness),
+            dynamic_complexity=float(dynamic_complexity),
+            mood_aggressive=binary_probs["mood_aggressive"],
+            mood_happy=binary_probs["mood_happy"],
+            mood_sad=binary_probs["mood_sad"],
+            mood_relaxed=binary_probs["mood_relaxed"],
+            mood_party=binary_probs["mood_party"],
+            danceability=binary_probs["danceability"],
+            mood_acoustic=binary_probs["mood_acoustic"],
+            mood_electronic=binary_probs["mood_electronic"],
+            voice_probability=binary_probs["voice_instrumental"],
+            gender=gender_label,
+            gender_confidence=gender_confidence,
+            tonal_probability=binary_probs["tonal_atonal"],
+            timbre=timbre_label,
+            timbre_confidence=timbre_confidence,
+            genres=multilabel["genre_discogs400"],
+            mood_themes=multilabel["mtg_jamendo_moodtheme"],
+        )

libavalon-0.0.1/avalon/analysis/model_cache.py

@@ -0,0 +1,140 @@
+"""Downloads and caches the Essentia pretrained models avalon uses.
+
+Each model's input/output tensor names and class label order come from its
+`.json` sidecar at run time rather than being hardcoded: node names vary
+per model (e.g. genre_discogs400 uses a different input node than the
+mood/character heads), and -- more importantly -- class order is *not*
+consistent (`mood_sad` is `["non_sad", "sad"]` while `mood_happy` is
+`["happy", "non_happy"]`). Trusting the declared schema avoids silently
+inverted probabilities.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+import requests
+
+from avalon.constants import MODEL_CACHE_DIRNAME
+
+logger = logging.getLogger(__name__)
+
+_BASE_URL = "https://essentia.upf.edu/models"
+_EMBEDDING_SUBDIR = "feature-extractors/discogs-effnet"
+_EMBEDDING_STEM = "discogs-effnet-bs64-1"
+
+
+@dataclass(frozen=True, slots=True)
+class ModelSpec:
+    """One classifier head. `kind` drives how essentia_analyzer reads its
+    output vector:
+      binary      -> single probability of `positive_label`
+      categorical -> whichever of `labels` scores highest, plus its confidence
+      multilabel  -> independent (sigmoid) scores, no single "positive" class
+    """
+
+    name: str
+    subdir: str
+    kind: str
+    positive_label: str | None = None
+
+
+CLASSIFIER_HEADS: tuple[ModelSpec, ...] = (
+    ModelSpec("danceability", "danceability", "binary", positive_label="danceable"),
+    ModelSpec("mood_acoustic", "mood_acoustic", "binary", positive_label="acoustic"),
+    ModelSpec(
+        "mood_aggressive", "mood_aggressive", "binary", positive_label="aggressive"
+    ),
+    ModelSpec(
+        "mood_electronic", "mood_electronic", "binary", positive_label="electronic"
+    ),
+    ModelSpec("mood_happy", "mood_happy", "binary", positive_label="happy"),
+    ModelSpec("mood_sad", "mood_sad", "binary", positive_label="sad"),
+    ModelSpec("mood_relaxed", "mood_relaxed", "binary", positive_label="relaxed"),
+    ModelSpec("mood_party", "mood_party", "binary", positive_label="party"),
+    ModelSpec(
+        "voice_instrumental", "voice_instrumental", "binary", positive_label="voice"
+    ),
+    ModelSpec("tonal_atonal", "tonal_atonal", "binary", positive_label="tonal"),
+    ModelSpec("gender", "gender", "categorical"),
+    ModelSpec("timbre", "timbre", "categorical"),
+    ModelSpec("genre_discogs400", "genre_discogs400", "multilabel"),
+    ModelSpec("mtg_jamendo_moodtheme", "mtg_jamendo_moodtheme", "multilabel"),
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ModelMeta:
+    """Parsed `.json` sidecar: local file path plus the schema bits needed
+    to run inference generically."""
+
+    pb_path: str
+    input_name: str
+    output_name: str
+    classes: tuple[str, ...]
+
+
+def _cache_dir() -> Path:
+    path = Path.home() / ".cache" / MODEL_CACHE_DIRNAME / "models"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _download(url: str, dest: Path) -> None:
+    if dest.exists():
+        return
+    logger.info("Downloading model file %s", url)
+    response = requests.get(url, timeout=60)
+    response.raise_for_status()
+    tmp = dest.with_suffix(dest.suffix + ".part")
+    tmp.write_bytes(response.content)
+    tmp.rename(dest)
+
+
+def _fetch(subdir: str, filename_stem: str) -> tuple[Path, dict]:
+    cache = _cache_dir()
+    pb_dest = cache / f"{filename_stem}.pb"
+    json_dest = cache / f"{filename_stem}.json"
+    base = f"{_BASE_URL}/{subdir}/{filename_stem}"
+    _download(f"{base}.pb", pb_dest)
+    _download(f"{base}.json", json_dest)
+    return pb_dest, json.loads(json_dest.read_text())
+
+
+def _output_by_purpose(outputs: list[dict], purpose: str) -> str:
+    for out in outputs:
+        if out.get("output_purpose") == purpose:
+            return out["name"]
+    return outputs[0]["name"]
+
+
+def get_embedding_model() -> tuple[str, str]:
+    """Downloads (if needed) the shared discogs-effnet embedding extractor.
+
+    Returns (pb_path, embedding_output_node_name).
+    """
+    pb_path, meta = _fetch(_EMBEDDING_SUBDIR, _EMBEDDING_STEM)
+    output_name = _output_by_purpose(meta["schema"]["outputs"], "embeddings")
+    return str(pb_path), output_name
+
+
+def get_classifier(spec: ModelSpec) -> ModelMeta:
+    filename_stem = f"{spec.name}-discogs-effnet-1"
+    pb_path, meta = _fetch(f"classification-heads/{spec.subdir}", filename_stem)
+    schema = meta["schema"]
+    return ModelMeta(
+        pb_path=str(pb_path),
+        input_name=schema["inputs"][0]["name"],
+        output_name=_output_by_purpose(schema["outputs"], "predictions"),
+        classes=tuple(meta["classes"]),
+    )
+
+
+def prefetch_all() -> None:
+    """Downloads every model avalon needs, up front (~26.5MB total)."""
+    get_embedding_model()
+    for spec in CLASSIFIER_HEADS:
+        get_classifier(spec)