Appendix E: Cover Art Processing

This section explains how Picard handles cover art, from finding images to embedding them in your files.

Overview

Picard’s cover art system has four stages:

Discovery - Find available images from configured providers.
Filtering - Decide which images to keep or skip.
Processing - Resize and convert images for embedding or saving.
Assignment - Copy images to files, respecting per-file protection rules.

Cover Art Providers

Cover art providers are the sources Picard queries for cover art. They run in a user-configured priority order under the Cover Art Options configuration. Each provider can queue images for download.

Cover Art Archive (CAA)

The most common provider. The CAA stores images uploaded by MusicBrainz editors with metadata: image types (front, back, booklet, etc.), approval status, and available thumbnail sizes.

How it works:

Picard fetches the CAA JSON metadata for the release (list of available images).
For each image, it checks:
- Is the image approved, or is the edit on MusicBrainz adding the image still pending approval (if “approved only” is enabled)?
- Does the image’s type match the include/exclude type filters?
- Is the image a PDF (only downloaded if “save to files” is enabled)?
For accepted images, Picard picks a thumbnail URL based on the configured image size preference (250px, 500px, 1200px, or full size).
Before downloading, the pre-download metadata filter can reject images based on the thumbnail’s known width. This is the only filter that saves bandwidth.

CAA image sizes and bandwidth:

The CAA has no upload size limit. Editors routinely upload 600 dpi scans that can exceed 15-30 MB per image, and some releases have 10+ images (front, back, booklet pages, disc, liner notes, etc.). A vinyl box set might have 50+ images.

When “Full size” is selected, Picard downloads the original uploaded file which could be a 30 MB PNG scan at 4800x4800 pixels. For a release with 12 images, that’s potentially 360 MB of downloads and significant processing time (resizing a 30 MB PNG is CPU-intensive).

The thumbnail sizes (250px, 500px, 1200px) are pre-generated by the CAA servers and are much smaller file sizes(typically 50-500 KB). The default is 500px, which is a good balance between quality and bandwidth. The pre-download metadata filter can reject thumbnails below the minimum size threshold before downloading, which is the only point where bandwidth is actually saved.

CAA-specific options:
The following options only apply to the CAA provider, and are set in the Cover Art Archive configuration:

Image size (thumbnail selection: 250px, 500px, 1200px, or full size).
Restrict to specific image types (include/exclude lists).
Only use approved images.

Other Providers

CAA Release Group - Falls back to the release group’s cover art if there is no cover art for the specific release.
Local Files - Reads images from files in the same directory (e.g. cover.jpg, folder.png).
URL Relationships - Uses image URLs from MusicBrainz release relationships.

Plugins can register additional providers.

Filtering

Filters determine whether an image should be kept or discarded. There are two stages of filtering with different purposes:

At Download Time (post-download)

This filter runs after the image data is downloaded. It does not save bandwidth because the download has already happened. It does prevent further processing and storage of unwanted images. This filter is set in the Cover Art Processing configuration and applies to all providers.

Size filter - Rejects images below the configured minimum dimensions.

At Assignment Time (per-file)

These filters run when images are being assigned to individual files. They compare each downloaded image against what is already embedded in that specific file, protecting existing embedded art from being downgraded. The filters are set in the Cover Art Options configuration and apply to all providers.

“Never replace with smaller” - If the file already has an embedded image of the same type (e.g. front) that is larger than the downloaded one, the downloaded image is skipped for that file.
“Never replace selected types” - If the file already has an embedded image whose type is in the user’s “never replace” list, the downloaded image is skipped for that file.

These per-file filters only apply when “Save images to tags” is enabled. If you’re only saving to external files, there are no embedded images to protect.

Why per-file?
Different files in the same album may have different embedded images (different sizes, different types). The filters compare against each file’s own embedded images, not an album-wide aggregate.

Interaction with CAA thumbnail size:
If “Never replace with smaller” is enabled and the files already have large embedded images (e.g. 1200px), but the CAA image size is set to a smaller thumbnail (e.g. 500px default), the filter will always reject the downloaded images, effectively preventing any cover art update for those files. Users in this situation should increase the CAA image size setting to match or exceed their existing embedded image dimensions.

Processing

After filtering, images are processed (resized, converted) before being stored, based on the settings in the Cover Art Processing configuration. Processing runs in background threads and produces separate results for:

Tags - Resized/converted for embedding in file tags (typically smaller).
External files - Resized/converted for saving along with the audio file.

The same source image can produce different output for tags vs. external files based on separate size/format settings.

Assignment

Images are assigned to files in two scenarios:

Files already matched when cover art downloads:
When cover art finishes downloading and files are already matched to the album, images are immediately assigned to all tracks and files. Per-file “never replace” filters run at this point.
Files matched after cover art is loaded:
When a file is matched to a track that already has cover art, the track’s images are copied to the file. Per-file “never replace” filters run here too, comparing against the file’s original embedded images.

In both cases, the same filtering logic applies, ensuring consistent behavior regardless of timing.

Saving

When the user saves a file, Picard writes images based on two independent options set in the Cover Art Options configuration:

Save to Tags (embedding)

Images from the file’s metadata file.metadata.images are embedded directly in the audio file’s tags (ID3 APIC frames, Vorbis METADATA_BLOCK_PICTURE, MP4 covr atoms, etc.)

Related options:

Embed only one front image - Only embed the first front image, skip others.
Never replace with smaller - Protect existing larger embedded images.
Never replace selected types - Protect specific image types from replacement.

Save to Files (external)

Images are written as separate files along with the audio file (e.g. cover.jpg).

Related options:

Filename pattern - Template for the external image filename.
Overwrite existing - Whether to replace existing external image files.
Save only one front image - Only save one front image externally.
Use image type as filename - Name files by their type (e.g. front.jpg, back.jpg).

Both options can be enabled simultaneously, and images will be both embedded and saved externally.

Image Storage Model

Internally to Picard, each file-like object carries two sets of images:

	Current Images	Original Images
Album	Downloaded from providers	Aggregate of all matched files’ embedded images
File	What will be saved (filtered per-file)	What was read from the file’s tags on disk

The album’s “original images” represent what is currently embedded across all matched files. Individual file “original images” represent what is in that specific file. The per-file filters compare against the individual file’s originals, not the album aggregate.