dschlueter/Music_Metadata_Enricher
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
Vervollständigt die Informationen über ein Musik-Datei-Verzeichnis, passt die Dateinamen und Metadaten der Dateien entsprechend an.
1 commit 1 branch 0 tags 330 KiB
  • Python 100%
Find a file
dschlueter b273052f68 first commit
2026-04-29 05:26:59 +02:00
README.md first commit 2026-04-29 05:26:59 +02:00

README.md

Music Metadata Enricher

KI-gestützter Musik-Metadaten-Enricher für Jellyfin-Bibliotheken.

Analysiert Album-Verzeichnisse, vervollständigt Tags, besorgt Cover-Art und benennt Dateien optional nach einem einheitlichen Schema um — vollständig ohne API-Key nutzbar, mit optionaler Claude-KI für lückenhafte Metadaten.

Features

  • Lokale Analyse — Verzeichnisname, Dateinamen, bestehende ID3/FLAC/M4A-Tags, Tracklist-Textdateien (.txt, .htm, .html)
  • MusicBrainz-Lookup — Textsuche + AcoustID-Fingerprinting (optional)
  • Discogs-Fallback — bei MusicBrainz-Misses
  • Claude API — Reasoning-Schritt für unklare / widersprüchliche Daten (optional)
  • Cover-Art — lokal → MusicBrainz Cover Art Archive → einbetten in MP3/FLAC/M4A
  • Tag-Schreiben — title, artist, album, albumartist, tracknumber, discnumber, date, genre, label (mutagen, ID3v2.4)
  • Umbenennen — 01 - Artist - Title.ext / 2-07 - Artist - Title.ext (Multi-CD)
  • Backup — Sicherungskopien vor jeder Änderung
  • CSV-Report — vollständiges Protokoll aller Änderungen
  • Interaktiver / Auto-Modus — mit Konfidenz-Schwellwert

Voraussetzungen

pip install mutagen musicbrainzngs pyacoustid discogs_client \
            anthropic Pillow requests tqdm
sudo apt install libchromaprint-tools   # fpcalc für AcoustID-Fingerprinting
Paket Zweck Optional?
mutagen Tags lesen/schreiben nein
musicbrainzngs MusicBrainz-API ja
pyacoustid AcoustID-Fingerprinting ja
discogs_client Discogs-API ja
anthropic Claude API ja
Pillow Cover-Bildgröße prüfen ja
requests Cover-Art-Download ja
tqdm Fortschrittsbalken ja
fpcalc Audio-Fingerprinting-Binary ja

Umgebungsvariablen (optional)

Variable Beschreibung
ANTHROPIC_API_KEY Claude API (Reasoning für Metadaten-Lücken)
ACOUSTID_API_KEY AcoustID-Fingerprinting
DISCOGS_TOKEN Discogs-API

CLI

music_enricher.py [Optionen] PFAD [PFAD ...]
music_enricher.py --album PFAD [Optionen]
Option Beschreibung
--dry-run Vorschläge anzeigen, nichts schreiben
--auto Kein interaktiver Review-Schritt
--confidence FLOAT Min-Konfidenz für --auto (default: 0.85)
--rename Dateien nach Schema umbenennen
--embed-cover Cover-Art in Audiodatei einbetten
--backup PFAD Backup-Verzeichnis vor Änderungen
--report PFAD CSV-Report der Änderungen
--no-fingerprint AcoustID-Fingerprinting überspringen
--no-api Keine externen API-Calls
--no-cover Kein Cover-Art-Download
--album PFAD Einzelnes Album verarbeiten
--no-tqdm Fortschrittsanzeige deaktivieren

Verwendung

# Einzelnes Album — Dry-Run, kein API-Key nötig
python3 music_enricher.py --dry-run --no-api \
    --album ~/Musik/Abba_-_Greatest_Hits

# Mit MusicBrainz-Lookup
python3 music_enricher.py --dry-run \
    --album ~/Musik/Bach_Organ_-_Peter_Hurford

# Vollständig: Tags + Cover einbetten + umbenennen, mit Backup und Report
python3 music_enricher.py --embed-cover --rename \
    --backup /tmp/musik_backup \
    --report report.csv \
    ~/Musik

# Auto-Modus: nur Vorschläge ≥ 90% Konfidenz anwenden
python3 music_enricher.py --auto --confidence 0.90 \
    --embed-cover --backup /tmp/backup \
    ~/Musik

# Mit Claude API (ANTHROPIC_API_KEY setzen)
export ANTHROPIC_API_KEY=sk-ant-...
python3 music_enricher.py --dry-run --album ~/Musik/UnbekanntesAlbum

Verarbeitungs-Pipeline

Album-Verzeichnis
      │
      ▼
1. AlbumScanner        — Dateitypen klassifizieren
      │
      ▼
2. HintExtractor       — lokal, keine API
   ├─ Verzeichnisname  → Artist, Album, Jahr
   ├─ Dateinamen       → Tracknummer, Artist, Titel
   ├─ ID3/FLAC-Tags    → bestehende Werte
   └─ Tracklist .txt   → Tracklisten parsen
      │
      ▼
3. MetadataResolver
   ├─ AcoustID         → MusicBrainz via Fingerprint
   ├─ Textsuche        → MusicBrainz-API
   ├─ Discogs          → Fallback
   └─ Claude API       → Reasoning-Schritt (optional)
      │
      ▼
4. CoverHandler        — lokal → MusicBrainz → einbetten
      │
      ▼
5. ReviewStep          — interaktiv oder --auto mit Konfidenz
      │
      ▼
6. Executor            — Backup → Tags → Cover → Umbenennen → Report

Konfidenz-Modell

Quelle Bonus
AcoustID-Match ≥ 90% +0.20
MusicBrainz via Fingerprint +0.25
MusicBrainz-Texttreffer (Score/100) +0.30 × Score
Discogs +0.15
Claude-Reasoning +0.10
Lokale Hints (Ordner-/Dateiname) +0.05

Dateinamen-Schema (mit --rename)

01 - ABBA - Dancing Queen.mp3
2-07 - Bach - Toccata And Fugue In D Minor BWV 565.flac

Bei Single-Disc entfällt die Disc-Nummer. Bei Multi-CD-Alben (Unterordner CD1/, CD2/ etc.) wird die Disc-Nummer automatisch erkannt.

Projektstruktur

Music_Metadata_Enricher/
├── music_enricher.py       Haupt-CLI, Pipeline-Orchestrierung
├── models.py               Dataclasses: AlbumScan, AlbumHints, TrackProposal, …
├── scanner.py              Dateisystem-Scanner, Typ-Klassifikation
├── hint_extractor.py       Dateiname/Tag/Tracklist-Auswertung
├── metadata_resolver.py    MusicBrainz + Discogs + Claude API
├── cover_handler.py        Cover-Art: Suche, Download, Einbettung
├── executor.py             Backup, Tag-Schreiben, Umbenennen, CSV-Report
└── test_suite_enricher.py  17 Unit-/Integrationstests

Tests

python3 test_suite_enricher.py
# 📊 17/17 Tests erfolgreich

Unterstützte Formate

Format Tags Cover-Einbettung
MP3 ID3v2.4 (EasyID3) APIC-Frame
FLAC Vorbis-Comments METADATA_BLOCK_PICTURE
M4A/AAC MP4-Tags covr-Atom
Sonstige mutagen generic –