How does BTR AMP choose which cover art to display?

BTRAMP pulls cover art from several sources and picks between them using a defined priority order. This page explains how that works — for songs, for collections (albums, artists, genres, composers), and for folders in the Files browser — and how you can supply your own custom art.

The answer breaks into three parts:

• A. How art is picked for an individual song.
• B. How art is picked for a collection — album, artist, genre, or composer.
• C. How art is picked for a file or folder in the Files browser.

Followed by a clarifying note on the two distinct user-customization mechanisms:

• The _btramp/art/ override folders (per-entity custom art, keyed by name).
• Folder-level default images (folder.jpg, cover.jpg, etc. dropped into the same directory as your music).

A. Cover Art for a Song

When BTRAMP needs to display art for a single song, it walks through the following sources in order and uses the first hit:

1. _btramp/art/song/ override — a custom image you placed specifically for that track.
2. Memory cache — an image already loaded this session.
3. Disk cache — an image loaded in a previous session and saved to the app’s cache directory.
4. The song’s own asset, based on where the song lives:
   • iTunes / Apple Music library songs → artwork embedded in Apple’s media library, with a fallback to reading the file’s own metadata directly.
     • Special case: for a cloud iTunes item with no network, a “no network” placeholder is shown.
   • Local files and on-device external files → two sub-sources are consulted. By default the order is embedded art first, then folder image files; flipping the Library setting Prefer Image Files Over Embedded Art reverses that order.
     • Embedded art is the artwork stored inside the audio file (ID3 for MP3, atoms for MP4/M4A/AAC, Vorbis comments for FLAC/OGG/Opus, etc.). For formats that store multiple pictures, BTRAMP prefers the “front cover” picture when present.
     • Folder image files are the first file found in the song’s enclosing folder whose name matches the configured Album Art Filenames list (see Section C).
5. Contextual fallbacks (only if nothing above returns art). BTRAMP tries the following overrides for the containing collection, in order, and uses the first match:
   1. _btramp/art/album/{Album Artist} - {Album Title}.{jpg|png}
   2. _btramp/art/artist/{Artist}.{jpg|png}
   3. _btramp/art/artist/{Album Artist}.{jpg|png}
   4. _btramp/art/genre/{Genre}.{jpg|png}
6. Default placeholder — the app’s built-in fallback image (_btramp/art/default.{jpg|png} if present, otherwise the image bundled with BTRAMP).

Whichever source wins at step 4 is cached in both memory and disk for next time. Overrides from step 1 are not cached in the normal image cache — they’re always read directly from their folder, so edits show up immediately.

B. Cover Art for an Album, Artist, Genre, or Composer

Collections (album, artist, genre, composer, and playlist) don’t have artwork of their own in the file system. Instead, BTRAMP designates a representative song for the collection at scan time and displays that song’s artwork.

Album — Picks the album’s first track by disc/track number. If track numbers are missing or zero across the album, it falls back to the earliest-inserted song for that album.

Artist — Picks the earliest-inserted song across every track where the artist appears either as album artist or as track artist. Songs without a usable asset location are excluded.

Genre — Picks the earliest-inserted song in that genre.

Composer — Picks the earliest-inserted song by that composer.

Once the representative song is chosen, the same resolution order from Section A runs — starting with the appropriate _btramp/art/ override for the collection itself (which, if present, short-circuits the whole lookup). So the effective order for a collection is:

1. _btramp/art/{type}/ override for the collection (for example _btramp/art/album/Pink Floyd - The Wall.jpg or _btramp/art/artist/Pink Floyd.jpg).
2. Memory / disk cache for the representative song.
3. Representative song’s embedded art or folder image (per Section A).
4. For albums only: artist or genre override file as a secondary fallback.
5. Default placeholder.

What if no song in the collection has art? Albums still get a last-chance lookup for an artist or genre override file. Artists, genres, and composers go straight to the default placeholder.

C. Cover Art for Files and Folders (Files Browser)

BTRAMP’s Files browser shows a thumbnail next to each folder. That thumbnail is produced by looking inside that folder for the first file whose name matches BTRAMP’s configurable list of album-art filenames.

Default search order:

folder.jpg, folder.jpeg, folder.png,
cover.jpg,  cover.jpeg,  cover.png,
front.jpg,  front.jpeg,  front.png,
albumartsmall.jpg, albumartsmall.jpeg, albumartsmall.png

The match is case-insensitive, and the first filename found in that folder wins — so the order of the list is the priority. You can add, remove, and reorder entries under Settings → Library → Album Art Filenames.

Three related settings control how and where this is used:

• Settings → Interface → Show Images in File Browser — turns folder thumbnails in the Files tab on or off. On by default.
• Settings → Interface → Folder Art in CarPlay — same idea, but for CarPlay folder browsing. On by default.
• Settings → Library → Prefer Image Files Over Embedded Art — when on, these same folder images also outrank embedded artwork when BTRAMP resolves art for a song (see Section A, step 4). Off by default.

Results are cached in memory and on disk like any other image.

Overrides: _btramp/art/ vs. Folder-Level Defaults

These are two separate features and it’s worth being explicit about the difference.

1. _btramp/art/ — Per-Entity Overrides (Highest Priority)

A single directory tree inside BTRAMP’s Documents folder, accessible via WiFi file transfer or the Files app. Structure:

Documents/
└── _btramp/
    └── art/
        ├── default.jpg           ← optional global fallback
        ├── album/
        │   └── {Album Artist} - {Album Name}.jpg
        ├── artist/
        │   └── {Artist Name}.jpg
        ├── composer/
        │   └── {Composer Name}.jpg
        ├── genre/
        │   └── {Genre Name}.jpg
        ├── playlist/
        │   └── {Playlist Name}.jpg
        └── song/
            └── {Artist} - {Song Name}.jpg

Rules

• Supported formats: JPEG (.jpg / .jpeg) and PNG (.png) only.
• Case-insensitive filename match — Pink Floyd.jpg matches a request for pink floyd.
• Filesystem-unsafe characters are sanitized (e.g. /) before the match, so an album with a slash in its title will match the sanitized form on disk.
• Global default.jpg / default.png at Documents/_btramp/art/ is the ultimate fallback image when nothing else is found.
• When you replace art through BTRAMP’s Metadata Editor, BTRAMP writes to this same tree on your behalf. A reset moves the old file into a _backup/ subfolder, so nothing is lost.

Priority: An override here always wins. If _btramp/art/album/Pink Floyd - The Wall.jpg exists, BTRAMP will show it even if the album’s tracks have embedded art, even if a cover.jpg sits next to the music, and even if the system has a valid memory or disk cache entry.

2. Folder-Level Defaults — cover.jpg, folder.jpg, etc.

These live next to your music files, not in _btramp/art/. They’re conventional image files inside the album/artist/whatever folder where your audio lives:

/Music/Pink Floyd/The Wall/
    ├── 01 - In The Flesh.mp3
    ├── 02 - The Thin Ice.mp3
    ├── ...
    └── folder.jpg          ← used as the album/folder artwork

Rules

• Filenames are matched against the list under Settings → Library → Album Art Filenames. Default list: folder.jpg, cover.jpg, front.jpg, albumartsmall.jpg (plus .jpeg and .png variants of each).
• The list is user-editable — add your own filenames, reorder for priority, or remove ones you don’t use.
• These files serve two jobs at once:
  1. They are what the Files browser uses for folder thumbnails.
  2. They are a fallback artwork source for songs that don’t have embedded art (or the primary source, if Prefer Image Files Over Embedded Art is on).

Priority: These are consulted after _btramp/art/ overrides, memory cache, and disk cache. For songs, they come either before or after embedded art depending on the Prefer Image Files Over Embedded Art setting.

Quick Comparison

Related Settings

All of these are found inside BTRAMP’s Settings screen:

• Settings → Library → Album Art Filenames — the ordered list of filenames BTRAMP looks for in folders.
• Settings → Library → Prefer Image Files Over Embedded Art — flips the order between embedded artwork and folder image files for local songs.
• Settings → Interface → Show Images in File Browser — toggles folder thumbnails in the Files tab.
• Settings → Interface → Folder Art in CarPlay — toggles folder thumbnails in CarPlay browse screens.
• Settings → Interface → Cover Art Memory Cache and Cover Art Disk Cache — toggles the two caches. You can also flush them.