- --except filters albums by directory name (glob or substring, repeatable)
- README.md: new options table entries, new cover sources, updated pipeline,
corrected test count (33), added batch example
- BEDIENUNGSANLEITUNG.md: new options table, sections E (batch+except),
F (--status), LASTFM_API_KEY env var, corrected test count
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
MusicBrainz returns vinyl track numbers as 'A1', 'B3' etc. instead of
plain integers. int('A1') raised ValueError crashing the entire album.
metadata_resolver.py: parse vinyl positions with regex before int():
- 'A1' → track 1, disc 1 (side A)
- 'B3' → track 3, disc 1 (side B)
- 'C1' → track 1, disc 2 (side C)
- Non-vinyl: extract first digit group via re.search
hint_extractor.py: guard int(tl_track) in tracklist matching with
try/except + re.search so any non-numeric track position is skipped
gracefully instead of crashing.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- _album_is_complete(album_dir): checks cover presence + sampled tag quality
(first/last/middle files); returns (bool, problems_list)
Sampling strategy: covers first, last and up to 3 middle files to catch
albums where only some tracks were tagged
- _print_status() now uses _album_is_complete() internally (DRY)
- --skip-complete flag: filters album_dirs before the main loop, prints
how many were skipped upfront
- Typical batch command:
python3 music_enricher.py --auto --confidence 0.1 --rename --embed-cover \
--no-fingerprint --skip-complete ~/nvme2n1p7_home/Musik
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Previously any albumartist≠track_artist triggered classical naming, causing
false positives for jazz compilations, folk samplers, pop albums with
multiple featured artists. Now requires explicit confirmation:
- Genre contains a classical keyword (classical, baroque, opera, symphon …)
- OR track_artist name contains a known composer (Bach, Mozart, Beethoven …)
Pure name-inequality alone no longer triggers the Performer-Composer-Work schema.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- _discogs_cover_url(): searches Discogs database/search API by artist+album,
returns primary image URL; uses DISCOGS_TOKEN if set, else anonymous
- download_discogs_cover(): downloads and saves as folder.jpg (PNG→JPEG via PIL)
- resolve_cover() priority: local → MusicBrainz → Discogs
- music_enricher: pass artist/album to resolve_cover() for Discogs lookup
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
_GENRE_MAP translates common German genre names (Volksmusik, Schlager,
Marschmusik, Klassik …) and English variants (rhythm and blues, swing music …)
to consistent Jellyfin-friendly labels. All-upper or all-lower genres without
a mapping entry are title-cased. Applied in resolve() before building AlbumProposal.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Scans all album directories and reports:
- Albums without any cover image
- Albums where the first 3 audio files have missing/placeholder tags
(title or artist empty, 'Unknown', 'AudioTrack')
Exits without writing anything.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add normalize_cover_to_folder_jpg(): renames/converts any local cover
(Front.jpg, front.webp, cover.jpg, …) to folder.jpg in-place; WebP/PNG
are converted to JPEG via PIL
- resolve_cover() now calls normalize_cover_to_folder_jpg() automatically
after finding a local cover, so future enrichment runs always produce folder.jpg
- One-time batch: 38 existing library covers renamed/converted to folder.jpg
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- download_cover() now writes folder.jpg instead of _cover_download{ext}
- PNG responses are converted to JPEG via PIL during download (avoids PNG
in the album directory entirely)
- find_local_cover() priority: folder > front > cover > album (folder.jpg
is now the canonical name for both downloaded and manually placed covers)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- hint_extractor: filter existing tags through _is_good() so 'Unknown',
'Unknown Artist' etc. in existing ID3 tags don't override filename-parsed
artist names
- executor: _is_classical() now returns False when track_artist is a placeholder
('unknown', 'unknown artist') — prevents pop albums from getting the
Performer-Composer-Work filename schema
- executor/music_enricher: pass albumartist to _proposed_filename() so fallback
works when track artist is missing; fix display to use albumartist fallback too
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
disc_number=1 is now treated identical to disc_number=None: no 'D-' prefix in
filenames, no discnumber tag written. The D-TT prefix and discnumber tag are
only applied for genuine multi-CD albums (disc_number > 1).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- hint_extractor: add _normalize_vertical_tracklist() to handle bare-number/
title/duration format (Tufaranka-style tracklists)
- hint_extractor: fix level-1 tracklist match — allow disc_num=None (single-CD)
by assuming disc=1; previously no tracklist title was ever applied to single-
CD tracks because the guard required disc_num to be set
- music_enricher: register module in sys.modules before exec_module() so
@dataclass definitions in jellyfin_playlist_generator work correctly
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
scanner.py: collect_album_dirs() now recursively finds album dirs
- Dirs with audio files at root → album
- Dirs with disc subdirs (CD1/CD2) and no root audio → multi-CD album
- Container dirs without audio → recurse into subdirs
music_enricher.py:
- After execute_album(), auto-discovers jellyfin_playlist_generator.py
in ../Jellyfin_Playlist_Generator/ (or via --playlist-generator PATH)
- Calls generate_playlist() directly via importlib — no subprocess,
no destructive cleanup_all_playlists, targeted to the enriched album
- New --playlist-generator CLI option for custom generator path
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The previous regex lookbehind (?<![A-Za-z0-9_-]) excluded _ as valid preceding
character, so IDs after underscores were never matched. New approach: split stem
by _ and check if the last token is an 11-char YouTube ID (mixed case + digit).
Also strips the ID token from the stem before _parse_filename() to prevent it
from leaking into the track title or being misread as an artist-title separator.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Extract 11-char YouTube video IDs from audio filenames
- Fetch title, uploader, chapters via yt-dlp (--dump-json)
- Use chapters as tracklist when no .txt tracklist is available
- Store yt_title / yt_uploader in AlbumHints for LLM prompt context
- Fall back to YouTube video title as track title for single-file albums
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
_update_m3u(): writes #EXTM3U + #EXTINF:seconds,Artist - Title + filename
per track, in disc/track order (same order as the renamed files).
Duration is read from mutagen; -1 if unavailable.
execute_album(): after renaming, finds existing *.m3u / *.m3u8 in the
album directory and overwrites it. Only triggered when files_renamed > 0
and a playlist file exists — never creates a new one from scratch.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
hint_extractor: _ocr_back_cover() sends back/inlay images to Ollama Vision
when no tracklist .txt/.htm/.nfo is present. Model priority:
qwen3-vl:latest → minicpm-v:latest → deepseek-ocr:latest (configurable
via OLLAMA_OCR_MODEL env var). Timeout 180s. OCR text is fed into the
same _parse_tracklist() pipeline as regular text files.
music_enricher: extract_hints(use_ocr=not args.no_api) — OCR is skipped
with --no-api to allow fully offline/fast runs.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
executor: disc=1 now generates '1-01' prefix (same as disc=2 → '2-01'),
so multi-disc albums have consistent D-TT scheme throughout.
Single-disc tracks without disc tag stay as plain 'TT'.
hint_extractor: tracklist pattern 2 now requires '.' ')' or ':' as separator
(not bare whitespace) — prevents false-positive matches like
'2 x CD, Compilation, Remastered' being parsed as track 2.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
hint_extractor:
- _norm_for_match(): strips all non-alnum for punctuation-agnostic comparison
- _catalog_key(): extracts BWV/Op./K./HWV/... catalog number for matching
(fixes abbreviated filenames like "Fantasia_Cm_BWV_562" vs "Fantasia In C Minor, BWV 562")
- Matching priority: exact number+disc → exact title → fuzzy title → catalog number
- Tracklist disc+track OVERRIDE M3U position when a match is found
(M3U is only used as last fallback; fixes wrong alphabetical ordering)
metadata_resolver:
- LLM prompt now defines artist/albumartist roles explicitly
(artist = composer for classical; albumartist = performer/interpreter)
- LLM albumartist can override dir_artist when confidence < 0.4
- _build_track_proposals: when track artist == albumartist (performer from filename),
composer (album-level artist) is used as track artist instead
- Tracklist header (first lines before tracks) included in LLM prompt
for label/year/album-title discovery
- import re added (was missing)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Pop schema: TT_-_Artist_-_Title.ext
Classical schema: TT_-_Performer_-_Komponist_-_Werk[-_Orchester_Dirigent].ext
triggered when albumartist ≠ track artist (pianist vs composer)
All spaces in names → underscores; separator _-_ between parts.
Missing parts (orchestra, conductor) are omitted.
models.py: added conductor/orchestra optional fields to TrackProposal.
executor.py: sanitize_dir_names() tries NameToUnix first, falls back to detox.
Called after all renames in a directory are complete.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Filename schema now: TT - AlbumArtist - TrackArtist - Title when albumartist
differs from track artist (e.g. pianist vs. composer). Identical artist → old
two-part format unchanged.
metadata_resolver: removed Claude API fallback entirely from _claude_resolve.
Chain is now Ollama (local, free) → OpenRouter (DeepSeek V3, cheap) only.
music_enricher: updated status line and use_claude flag accordingly.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Strip non-timestamp characters (BOM, invisible chars) from date/year values
both when reading existing tags in metadata_resolver and when writing in
executor. Also harden the EasyID3 except block to not wipe existing tags
when adding a missing ID3 header, and add per-field try/except in MP3 tag
writing so one bad field doesn't abort the entire track.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
scanner: nicht in Unterordner wenn Root Audio-Dateien enthält (verhindert
Doppel-Scan bei versehentlichen Unterordner-Kopien); nur Disc-Ordner
(CD1, Disc 2…) werden bei Multi-CD-Alben rekursiert.
hint_extractor: M3U/Playlist-Dateien als Track-Reihenfolge-Quelle; BOM-
Bereinigung; Tracklist-Matching auch per Titel (nicht nur per Nummer);
tracknumber=0 wird als 'keine Nummer' gewertet.
metadata_resolver: sequenzielle Fallback-Nummerierung (1,2,3…) für Tracks
ohne Tracknummer — verhindert '00'-Präfix beim --rename; dir_artist hat
Vorrang vor 'Various Artists'-Heuristik; LLM darf bei Konfidenz <0.3
auch bestehende Werte korrigieren (Tippfehler im Verzeichnisnamen).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
_claude_resolve() nutzt jetzt Ollama lokal (kostenlos, RTX 3090) als
erste Wahl, dann OpenRouter/DeepSeek V3 (sehr günstig) und zuletzt
Claude API. Neue ENV-Variablen: OPENROUTER_API_KEY, OLLAMA_RESOLVE_MODEL.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
AI-powered per-album pipeline: scan → local hints → MusicBrainz/Discogs/Claude
resolve → cover art → interactive or auto review → tag write + rename + report.
All external dependencies optional; 17/17 unit tests passing.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
