A C++ library that indexes a local music collection and resolves cover art by track metadata. Written for discord-music-presence, where lookups need to be fast enough not to be noticeable: give it an artist / title / album query, get back the path to the matching cover art. If nothing matches, you get nothing back. That’s the whole thing.

How it works

Tags are read via TagLib — ID3 is the source of truth, not filenames or folder structure. The index lives in memory by default; set db_path to persist it via LMDB, which makes warm starts near-instant (the constructor returns in a few milliseconds and a background thread reconciles anything that changed while the app wasn’t running). A file watcher (efsw) keeps the index current while running.

Lookups use bigram similarity (Sørensen–Dice) so minor tag inconsistencies between what the OS reports and what’s in the file don’t cause misses. A composite score — title 50%, artist 35%, album 15% — is compared against a configurable threshold; set exact = true for strict matching instead.

Cover art resolves two ways: external files matched by case-insensitive regex (default cover\.gif), or embedded pictures read from the audio tags when embedded is on.

Performance

Benchmarked on a 4,470-track library (Windows 11, SSD), external-art mode:

Supported formats: mp3, flac, ogg, opus, m4a, aac, wav, aiff, wv, ape, mpc, wma — anything TagLib can read tags from.

Integration details live in the API page.