TuneCover

Application for managing album cover art in music libraries, with CLI + GUI interfaces.

Note: This application works best with properly tagged files. You can use tools like MusicBrainz Picard, MP3Tag, etc. to prepare your files.

• Library scanning: Recursive analysis of all album folders
• Multi-format detection: MP3, FLAC, OGG, OGA, M4A, MP4, Opus, WAV, AIFF, WMA
• Dual verification: Embedded covers (tags) AND image files (cover.jpg, folder.png, etc.)
• Custom patterns: Folder exclusion via glob patterns (Podcasts, Audiobooks, etc.)
• Detailed reports: JSON or CSV export for review before modification

• Multi-providers: MusicBrainz/Cover Art Archive (default), Discogs, Last.fm
• Multi-level identification: Hierarchical system to find the best match
  • Level 1: MusicBrainz ID (MBID) from tags
  • Level 2: Discogs ID from tags
  • Level 3: UPC/EAN barcode
  • Level 4: ISRC (International Standard Recording Code)
  • Level 5: Text search by artist/album
  • Level 6: AcoustID audio fingerprinting (optional)
• Source selector: Enable/disable providers in preferences

• Tag embedding: Integration into audio files (ID3, FLAC, MP4, OGG)
• External file: Save cover.jpg/folder.jpg in the folder
• Timestamp preservation: Option to keep original file modification date
• Configurable strategy: Customizable filename and compression settings

• Python 3.12 or higher
• Linux, macOS, or Windows

This project uses uv as package manager (recommended):

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Create environment and install
uv venv
source .venv/bin/activate
uv pip install -e .

Or with pip:

pip install -e .
# or
pip install -r requirements.txt

To enable AcoustID identification, install chromaprint:

# Linux (Debian/Ubuntu)
sudo apt install libchromaprint-tools && pip install pyacoustid
# macOS
brew install chromaprint && pip install pyacoustid
# Windows: Download fpcalc.exe from https://acoustid.org/chromaprint
pip install pyacoustid

A free AcoustID API key is required: https://acoustid.org/new-application

python -m src.main
# or
python -m src.main gui

• Drag & Drop: Drop folders or audio files directly into the library
• Import/Export: Save and load album lists as JSON (Ctrl+E / Ctrl+I)
• Group as album: Combine individual files into a single album entry
• Ungroup: Split a grouped album back into individual files
• Grid/List views: Switch between visual grid and compact list

Filter albums by cover status:

• No cover / Embedded only / External only / Both covers
• Covers that differ (embedded ≠ external)
• Identical covers (find duplicates by image hash)
• Small covers / Covers to improve
• Without AcoustID / Single tracks

Sort by: Artist, Album, Year, Cover size, Path

When an album has both embedded and external covers:

• Sync to file: Copy embedded cover to folder
• Sync to tags: Copy folder cover to audio tags
• Keep largest: Automatically use the higher resolution version
• Compare: Side-by-side comparison dialog with zoom

• Batch download: Fetch covers for multiple albums with progress tracking
• Batch AcoustID: Identify albums via audio fingerprinting
• Minimum score: Configurable threshold for automatic matching (default: 95%)
• Skip/Cancel: Granular control during batch processing

View library statistics including:

• Cover status distribution
• Average dimensions (embedded vs external)
• Format distribution (JPEG, PNG, etc.)
• File size statistics

The CLI workflow has two steps to ensure no modifications without approval.

python -m src.main scan /path/to/music [options]

# Examples
python -m src.main scan ~/Music
python -m src.main scan ~/Music -o report.json
python -m src.main scan ~/Music --exclude Podcasts Audiobooks

python -m src.main fetch report.json [options]

# Interactive (default)
python -m src.main fetch report.json
# Automatic
python -m src.main fetch report.json --auto --min-score 90
# Dry run
python -m src.main fetch report.json --dry-run

Names: cover, folder, front, album, albumart, artwork, art, thumb, disc, scan, jacket

Extensions: .jpg, .jpeg, .png, .gif, .bmp, .webp

Configuration is stored in:

• Linux: ~/.config/tunecover/config.json
• macOS: ~/Library/Application Support/tunecover/config.json
• Windows: %APPDATA%\tunecover\config.json

To improve MusicBrainz rate limit (1 → 50 req/s), configure a contact email in Edit > Preferences > General.

For Discogs and Last.fm, configure API keys in Edit > Preferences > API Keys:

• Discogs: https://www.discogs.com/settings/developers
• Last.fm: https://www.last.fm/api/account/create

Configurable via Edit > Preferences > Cache:

# Clone and install
git clone https://github.com/comxd/tune-cover.git
cd tune-cover
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pre-commit install
# Commands
make test # Run tests
make test-cov # Tests with coverage
make lint # Check code (ruff)
make format # Format code (ruff)
make run # Run the application

Application metadata is centralized using a single source of truth:

pyproject.toml ─► version, name (canonical source)
 │
 ▼ (importlib.metadata)
src/utils/constants.py ─► VERSION, APP_NAME_SLUG, APP_NAME, etc.
 │
 ▼ (uv run python -c "...")
Makefile ─► VERSION, PROJECT variables
 │
 ▼ (pybabel --project --version)
messages.pot ─► Project-Id-Version header (template only)

To update the version:

1. Edit version in pyproject.toml
2. Run uv pip install -e . to update package metadata
3. Run make i18n-extract to update the .pot template

Note: .po files keep their own Project-Id-Version to track when translations were made.

Key files:

• pyproject.toml: Canonical version (version = "X.Y.Z")
• src/utils/constants.py: All app name variants and dynamic version
• Makefile: Reads constants for i18n commands

Download ready-to-use packages from GitHub Releases:

# Install prerequisites
sudo apt install flatpak flatpak-builder
flatpak install flathub org.kde.Platform//6.8 org.kde.Sdk//6.8
# Build
cd flatpak
flatpak-builder --force-clean --user --repo=repo build-dir io.github.comxd.TuneCover.yml
# Test without installing
flatpak-builder --run build-dir io.github.comxd.TuneCover.yml tunecover
# Create installable bundle
flatpak build-bundle repo TuneCover-linux-x86_64.flatpak io.github.comxd.TuneCover

# Install dependencies
uv sync --frozen --all-extras
# Compile translations
uv run pybabel compile -d src/i18n/locales
# Build executable
cd packaging
uv run pyinstaller tunecover.spec
# Result: dist/TuneCover/TuneCover.exe

# Install dependencies
uv sync --frozen --all-extras
brew install chromaprint
# Compile translations
uv run pybabel compile -d src/i18n/locales
# Generate icon and build
./packaging/generate-macos-icons.sh
cd packaging
uv run pyinstaller tunecover-macos.spec
# Result: dist/TuneCover.app

The project uses GitHub Actions to build for all platforms automatically. You can trigger builds without creating a release:

1. Go to Actions → Build Release
2. Click Run workflow
3. Select branch and click Run workflow
4. Download artifacts from the completed workflow

# Trigger the workflow
gh workflow run build-release.yml
# Watch progress
gh run watch
# List artifacts when complete
gh run view --log

git tag v1.0.0-test
git push origin v1.0.0-test
# A draft release with all platform builds will be created

Python dependencies are managed with req2flatpak for reproducibility:

# Update versions in requirements file
# Edit flatpak/requirements-flatpak.txt
# Regenerate manifest sources (uvx installs and runs the tool)
uvx req2flatpak \
 --requirements-file flatpak/requirements-flatpak.txt \
 --target-platforms 312-x86_64 \
 --yaml
# Copy output to io.github.comxd.TuneCover.yml (python3-dependencies section)

GPL-3.0-or-later - See LICENSE for details.