Artist photos, artist bios and album liner notes for an iPod running PodBox, in one click.
This carries on from ipod-artist-photos, which only did artist photos and is no longer being developed. Everything it did is included here, unchanged, alongside the new artist bios and liner notes.
Warning
Still in development, not ready for public use yet. This is an experimental tool I'm testing on my own iPod. Things may change or break between versions, and the Artist Bio screen it writes for isn't available in any official PodBox release. If you just want artist photos, use ipod-artist-photos instead.
Please read first
- Forked from PodBox.
art_fetch.pyis a modified copy of the artwork tool from PodBox (tools/art_fetch, version 3.8). This is an unofficial fork and isn't affiliated with or endorsed by the PodBox project. Please report problems with this tool here, not to PodBox.- Written with AI. The changes to
art_fetch.py, and the newartist_fallback.py,artist_bios.py,liner_notes.pyandiPod Liner Notes.bat, were written with the help of Claude, an AI assistant made by Anthropic, at my direction. I've used them on my own iPod Classic, but they haven't been tested more widely.- Bios and liner notes need a custom PodBox build. The Artist Bio and Liner Notes screens that show them aren't in PodBox's official releases yet; Artist Bio has been proposed to the PodBox developer. Until they are, seeing them on the iPod means building PodBox from source with those changes added. On an official PodBox build both steps are skipped automatically, and everything else (artist photos, database and art cache) works as normal.
- Use at your own risk. The tool writes picture files into your iPod's music folders and updates its database. Keep a backup of your music.
A one-click Windows tool that fills the Artist Portraits menu and the Artist Bio and Liner Notes screens of an iPod running PodBox, the Rockbox-based firmware for the iPod Classic and iPod Video.
Double-click one file and it:
- finds a photo of every artist on your iPod, from Last.fm, Deezer, fanart.tv and TheAudioDB;
- uses an album cover for any artist with no photo anywhere, so nobody is left blank;
- writes a biography and a banner photo for each artist, for the Artist Bio screen (hold Select on Now Playing);
- writes liner notes for each album, with the critics' scores, for the Liner Notes screen;
- updates the iPod's database and art cache, so the pictures are there as soon as you eject it, with nothing to do on the iPod itself.
- A Windows PC.
- An iPod running PodBox that has been switched on at least once since PodBox was last installed or updated. (The database tools refuse to run until it has.)
- Music on the iPod arranged as
Music\Artist\Album\folders, as PodBox and most sync tools do. Album folders can be named any way you like:OK Computer,1997 - OK ComputerandRadiohead - OK Computerall work. A year in front isn't needed.
You only need to do this once.
- Download Python 3 from python.org/downloads.
- Run the installer. On its first screen, tick "Add python.exe to PATH" before clicking Install Now. If you miss this box, the tool can't find Python.
To check it worked, open Command Prompt (press the Windows key, type
cmd, press Enter) and type:
python --version
It should print something like Python 3.12.4.
In the same Command Prompt window, type:
pip install requests pillow mutagen opencv-python
Wait for it to finish, then close the window.
- At the top of this page, click the green Code button, then Download ZIP.
- Open your Downloads folder, right-click the ZIP and choose
Extract All. Put it somewhere permanent, for example
Documents\iPod Liner Notes.
You should now have these files in that folder:
| File | What it is |
|---|---|
iPod Liner Notes.bat |
The one you double-click. It runs everything below in order. |
art_fetch.py |
Finds artist photos online. |
artist_fallback.py |
Uses an album cover when no photo can be found. |
artist_bios.py |
Writes each artist's bio and banner for the Artist Bio screen. |
liner_notes.py |
Writes each album's notes and cover banner for the Liner Notes screen. |
translate.py |
Translates bios and notes for artists who don't work in English, when you add a DeepL key. |
iPod Liner Notes settings.txt |
Settings for the bios and liner notes (see Settings). |
Keep them together in the same folder.
Last.fm has the most artist photos, but it only answers the tool if you give it a free API key:
-
Sign in to Last.fm (or create a free account), then go to last.fm/api/account/create. Any name and description will do; leave the callback box empty.
-
Copy the API key and Shared secret it shows you.
-
Optionally, get a free fanart.tv key too, from fanart.tv/get-an-api-key. It adds more photos for well-known artists.
-
Open Command Prompt in the tool's folder (open the folder in File Explorer, click the address bar, type
cmdand press Enter), then type:python art_fetch.py --install-credentials --prompt-credentialsPaste each key when asked, and press Enter to skip any you don't have.
The keys are saved on your PC, in
%APPDATA%\RockboxArtistArt\artist_art_credentials.json, not in this folder,
so they aren't shared if you share the folder. Without any keys the tool
still works using Deezer and TheAudioDB, but finds fewer photos.
The tool assumes your iPod shows up as drive G: with its music in
G:\Music. If yours is different:
-
Plug in the iPod and look in File Explorer > This PC to see its drive letter.
-
Open
iPod Liner Notes settings.txtin Notepad. -
Change the
ipod driveline to match, for exampleipod drive = E:. If the music isn't in a folder calledMusic, setmusic foldertoo. -
Save and close.
- Plug in the iPod and wait for it to appear in File Explorer.
- Double-click iPod Liner Notes.bat.
- Let it run. The first time takes a while, roughly a few seconds per artist. You can press Ctrl+C to stop at any point; next time it carries on where it left off.
- When it says it has finished, eject the iPod as normal. The pictures are in Artist Portraits when it restarts.
If Windows shows "Windows protected your PC" the first time, click
More info, then Run anyway. That appears for any downloaded .bat
file.
| Step | What happens |
|---|---|
| 1. Fetch photos | Looks for a photo of each artist that doesn't have one yet, including artists showing an album cover in place of one. A cover is replaced only when a real photo is found. Artists with a real photo already are skipped. |
| 2. Album cover fallback | Any artist still without a photo gets the cover of their biggest album, squared, instead. |
| 3. Fetch bios | Writes a bio and banner for each artist that doesn't have one yet (see Artist bios below). Runs only if the PodBox on your iPod has the Artist Bio screen. |
| 4. Fetch liner notes | Writes notes for each album that doesn't have them yet (see Liner notes below). Runs only if the PodBox on your iPod has the Liner Notes screen. |
| 5. Update database | Runs PodBox's database tool on the iPod. |
| 6. Update art cache | Runs PodBox's art cache tool, so the new pictures show straight away. |
At the end it prints a summary, and saves these lists in the tool's folder:
- Artists using album cover.txt: artists showing an album cover because no photo was found.
- Artists without photos.txt: artists with no photo and no album art at all.
- Artists without bios.txt: artists no bio could be found for.
- Albums without notes.txt: albums whose page has only the facts line.
Run it again whenever you've added music. Artists that are already done are skipped, so repeat runs are quick. Each artist still on the album-cover list is looked up again every time, so photos for them appear once Last.fm or Deezer gets one.
Steps 5 and 6 use PodBox's own PC tools, which come with PodBox and are
already on your iPod, in .rockbox\tools\ (database_pb.exe and
artcache_pb.exe). There is nothing extra to install, and you don't need to
run anything on the iPod.
If either step says FAILED, do it on the iPod instead: eject it, then go to Settings > General Settings > System > Library Maintenance and choose Update Database, then Update Art Cache.
To use your own picture for an artist, save any square-ish JPEG as
folder.jpg in that artist's folder on the iPod, replacing the one there,
then run the tool again (or Update Art Cache on the iPod). The tool never
replaces a photo you've put there yourself.
PodBox also reads artist pictures from Artwork\People\<Artist>.jpg at the
root of the iPod, and a picture there takes priority over the artist
folder's folder.jpg. If an artist shows the wrong picture, check there
first.
iPod Liner Notes settings.txt, beside the scripts, holds the tool's settings. Open it in Notepad, change a value after the = and
save; it takes effect on the next run.
| Setting | Default | What it does |
|---|---|---|
ipod drive |
G: |
The iPod's drive letter |
music folder |
empty | The music folder, if it isn't Music on the iPod's drive |
bios |
auto |
Artist bios: auto writes them only if the PodBox on the iPod has the Artist Bio screen, yes always, no never |
liner notes |
auto |
The same for liner notes and the Liner Notes screen |
recheck missing days |
30 |
Days before artists with no bio and albums with no notes are looked for again; 0 never. Ones that have them are left alone |
bio recheck days |
365 |
Days before an artist's bio is checked again; 0 never checks. Artists who have died and bands that have split are never checked again |
notes recheck days |
365 |
The same for an album's liner notes |
banners |
yes |
Fetch the banner pictures. no writes the text only |
refresh after podbox install |
no |
Whether installing a new PodBox build also fetches photos, bios and notes and updates the database and art cache, as running the .bat does. no does that only when there is new music or the database was rebuilt |
discogs token |
empty | Your Discogs personal token, an extra source for both |
deepl key |
empty | Your DeepL key, to translate bios and notes for artists who don't work in English (see Translation) |
Step 3 writes two files per artist into Artwork\Bios at the root of the
iPod, which the Artist Bio screen reads:
<Artist>.txt: the name, a line of genre, home town and dates (birth to death for a person, start to end for a band), then the biography.<Artist>.jpg: a 320 x 160 banner from the artist's photo, cropped so the faces stay in view.
The bio is the introduction of the artist's English Wikipedia article. Where there is none it comes from Last.fm (with your Last.fm key) or Discogs, then, for an artist who doesn't work in English, their own language's Wikipedia or Last.fm, translated (see Translation), and failing those a line of facts. The last line of each bio says where it came from and the date it was retrieved. Before looking anything up it checks which artist yours is: when several share the name (a singer called Dijon, and the city), it picks the one whose albums match your album folders. A very long bio is swapped for a much shorter one from another source when there is one.
Photos come from TheAudioDB, Deezer, Discogs or Wikipedia. When none has
one, the artist's own folder.jpg from step 1 is used, unless it is an album
cover step 2 put there; failing that, the cover of one of their albums. An
artist whose banner is an album cover gets their folder.jpg instead as soon
as step 1 finds them a photo, with nothing downloaded again. What was downloaded is kept on
the PC (in %APPDATA%\RockboxArtistArt\bios), so a later run only looks up
new artists, plus any active artist whose bio is over a year old (change that
with bio recheck days in the settings file). Artists who have died and bands
that have split are left as they are. When a bio is checked again, it is only
replaced if it has really changed, not for a small edit, and the banner photo
stays as it was. If a source is down when a bio is due, the old one is kept.
To write your own bio or banner, edit or replace the file in
Artwork\Bios; the tool leaves a file you've changed alone. To look every
artist up again, run python artist_bios.py "G:\Music" --refresh, or for one
artist add --only "Artist Name".
The Artist Bio screen isn't in PodBox's official releases yet, so to see the
bios you need a PodBox build compiled from source with the Artist Bio changes
added. The .bat
checks the iPod and skips this step when its PodBox doesn't have the screen.
To change that, set bios in the settings file: yes writes bios whatever
the firmware, no never does.
Step 4 writes two files per album into Artwork\Notes at the root of the
iPod, named <Album Artist> - <Album>, which the Liner Notes screen reads:
.txt: the title, a facts line (artist, year, label, tracks, length), the album's notes, then the critics' scores, and where the text came from and the date it was retrieved..jpg: the album's own cover (cover.jpg,folder.jpgor the art in the files), cropped to a 320 x 160 banner.
Each album is matched first among the artist's albums on Wikidata, else on
MusicBrainz by the artist and title, so a song, a single or a video of the
same name can't take its place (a folder of three tracks or fewer is taken to
be a single). Its English Wikipedia article supplies the introduction, the
first paragraph about what critics made of it and the scores from its ratings
box. An album with no English article, by an artist who doesn't work in
English, gets its article in their language, translated. Otherwise the notes
come from Last.fm or Discogs; an album none of them covers still gets a page
with its facts line. The album and artist names come from the files' tags; an
album split into disc folders (CD1, CD2) is read as one, and a Singles
folder or one holding several albums is skipped.
The title on the page is the plain title, without "Deluxe Edition" and the like. The year is when the album first came out, from Wikidata and MusicBrainz, then your files' original-date tag, and only then their date tag, which often holds a reissue's year.
As with bios, a file you've changed is left alone, and notes are checked again
once they're a year old (notes recheck days in the settings file) and only
rewritten if they've really changed. To look
an album up again, run
python liner_notes.py "G:\Music" --only "Artist - Album" --refresh. The
liner notes setting works like bios.
Most of what is written about Japanese, Korean or Chinese releases, and some
European ones, isn't in English. With a free DeepL key in the settings file
(deepl key = ..., from deepl.com/pro-api,
500,000 characters a month), bios and notes for those artists come from their
own language's Wikipedia or Last.fm, translated into English. The page's last
line then says it was machine-translated.
Translation is used only for artists who work in another language (Wikidata records their language or country), and only text that really isn't English is sent. Every translation is kept on the PC, so a later run never pays for the same text twice. A whole library uses a small part of the free allowance.
| Problem | What to do |
|---|---|
'python' is not recognized |
Python wasn't added to PATH. Run the Python installer again, choose Modify, and tick Add Python to environment variables. |
No module named requests (or PIL, mutagen or cv2) |
Step 2 of installing didn't finish. Run pip install requests pillow mutagen opencv-python again. |
| An artist has the wrong bio | Edit that artist's .txt in Artwork\Bios on the iPod; the tool leaves a file you've changed alone. Deleting it only brings the same bio back next run. |
Can't find G:\Music |
The iPod isn't plugged in, or is on a different drive. See Tell it where your iPod is. |
| An artist gets the wrong person's photo | Delete that artist's folder.jpg on the iPod and add one yourself (see Adding a photo yourself). |
| An artist is never found | Check the artist's name is spelled correctly in your music tags. The tool searches by the name in your tags. |
| Database or art cache step says FAILED | Switch the iPod on once with PodBox, then try again, or run the update on the iPod (see Updating the iPod's database). |
art_fetch.py is a modified copy of the artwork tool that comes with PodBox,
tools/art_fetch
(version 3.8), which downloads artist and album art for a Rockbox-style music
library.
The original is a general artwork fetcher. Run against a real iPod library to fill Artist Portraits, it left many artists with no picture:
- Last.fm often refused its requests or returned image links that no longer worked.
- Smaller artists missing from Last.fm, fanart.tv and TheAudioDB got nothing.
- An artist with no photo anywhere was left blank, even when their album covers were on the iPod.
- Getting new pictures to show on the iPod took several separate steps, some of them on the iPod itself.
art_fetch.py
- More reliable Last.fm. Last.fm pages are requested the way a web browser asks for them, and when Last.fm refuses (HTTP 403 or 406) two other ways are tried, with a pause between, before giving up.
- Every lookup retries when a site is busy. A "too many requests" (429) or "temporarily unavailable" (5xx) answer from any source is waited out and tried again, instead of losing that source for the artist.
- Broken image links retried at the other sizes Last.fm offers.
- Errors are shown rather than skipped silently.
- Only the artist's own photos. Pictures of similar artists are no longer picked up from Last.fm pages.
- New source: Deezer. Free, needs no key, and covers many smaller artists. Several artists can share a name, so a Deezer photo is only used when one of that artist's Deezer albums matches one of your album folders (ignoring endings such as "- EP" and "(Deluxe)").
artist_fallback.py (new): for an artist with no photo, squares the cover
of their biggest album (embedded in the tracks, or the album's folder.jpg or
cover.jpg) into the artist's folder.jpg, as a baseline JPEG the iPod can
read. art_fetch replaces these stand-ins only when it finds a real photo.
With --remove it takes them away, leaving any picture you've added
yourself.
artist_bios.py (new): bios and banner photos for PodBox's Artist Bio
screen. See Artist bios above.
liner_notes.py (new): liner notes and cover banners for PodBox's Liner
Notes screen. See Liner notes above.
iPod Liner Notes.bat (new): runs everything above in order,
then updates the database and art cache with PodBox's tools.
python -m unittest discover tests runs offline checks of the cases that
have tripped real runs: a song or a video taken for an album, lost quote
marks, untidy scores, reissue years, names too long for the iPod, and the
language checks. They need no network and take under a second.
art_fetch.py comes from PodBox, which is licensed under the GNU General
Public License, version 2. This modified copy is under the same licence; see
LICENSE.