🎮 RetroArch Fast Thumbnail Downloader

A fast and convenient Python utility for downloading game artwork from the Libretro Thumbnail Archive based on a RetroArch playlist (.lpl).

The script processes multiple games in parallel, automatically skips thumbnails that are already downloaded, detects corrupted PNG files, and generates a detailed report for missing artwork.

---

✨ Features

• ⚡ Parallel downloads using multiple worker threads
• 🖼️ Downloads three types of RetroArch artwork:
  • Named_Boxarts
  • Named_Titles
  • Named_Snaps
• 💾 Smart local cache — existing valid thumbnails are skipped
• 🔍 Corrupted PNG detection — invalid or empty PNG files are automatically removed and re-downloaded
• 📊 Beautiful terminal interface powered by Rich
• ⏱️ Progress bar with:
  • Download progress
  • Completed/total count
  • Time remaining
• 🟢 Detects fully downloaded artwork
• 🩷 Detects partially downloaded artwork
• 🔴 Detects games with no available artwork
• 📄 Automatically generates a missing.txt report when artwork is missing
• 🧵 Configurable number of parallel workers

---

📸 Screenshots

Download Process

Missing Artwork Detection

Missing Artwork Report

---

📸 How It Works

The script reads the game titles from your RetroArch .lpl playlist and attempts to download the corresponding artwork from:

http://thumbnails.libretro.com/

For example, a game from the FBNeo - Arcade Games playlist may be downloaded as:

thumbnails/
└── FBNeo - Arcade Games/
    ├── Named_Boxarts/
    │   ├── Game 1.png
    │   └── Game 2.png
    │
    ├── Named_Titles/
    │   ├── Game 1.png
    │   └── Game 2.png
    │
    └── Named_Snaps/
        ├── Game 1.png
        └── Game 2.png

---

📋 Requirements

• Python
• An existing RetroArch playlist (.lpl)
• Internet connection
• Python packages listed in requirements.txt

---

🚀 Installation

1. Clone the repository

git clone https://github.com/KiloTheLoser/Retronail-CLI.git
cd Retronail-CLI

2. Install the required dependencies

pip install -r requirements.txt

---

▶️ Usage

Run the script with:

python fetch.py

The program will ask you for your RetroArch playlist path:

Enter playlist file path (Example: D:\RetroArch-Win64\playlists\FBNeo - Arcade Games.lpl):

Enter the path to your .lpl playlist.

Next, the program will ask for the output directory:

Enter output directory path for thumbnails (Press Enter for default: ...):

You can either:

• Press Enter to use the automatically detected default directory
• Enter your own custom output directory

Change MAX_WORKERS

Find this line inside fetch.py:

MAX_WORKERS = 15

and change to how many parallel workers you want default are 15 (make sure not too much). This is how you controls the number of simultaneous download threads.

---

📊 Download Status

Each game is displayed with its artwork status:

Downloaded Game Name                Boxart: ✓  Title: ✓  Snap: ✓
Partial    Game Name                Boxart: ✓  Title: ✗  Snap: ✓
Not Found  Game Name                Boxart: ✗  Title: ✗  Snap: ✗

Status meanings

Status	Meaning
🟢 Downloaded	All three artwork types were successfully downloaded
🩷 Partial	At least one artwork type was downloaded, but one or more are missing
🔴 Not Found	None of the requested artwork types could be downloaded

---

📄 Missing Artwork Report

If one or more games are missing artwork, the script automatically creates a report for example:

FBNeo - Arcade Games missing.txt

This makes it easy to identify which games need manual attention.

If every game has all three artwork types, no missing.txt file is created.

---

🛠️ Troubleshooting

Playlist not found

Make sure the path points to an existing RetroArch .lpl file.

Example:

D:\RetroArch-Win64\playlists\FBNeo - Arcade Games.lpl

Many games are marked as Partial or Not Found

This usually means that the specific thumbnail asset is missing from the Libretro servers for that game. For example, a game like Street Fighter III: 3rd Strike might have a snap and title screen available on the server, but its boxart might be missing.

Check the generated missing.txt file to see which games are affected.

Downloads fail or time out

Make sure:

• Your internet connection is working
• The Libretro thumbnail server is accessible
• Your firewall is not blocking Python
• You are not using an excessively high MAX_WORKERS value

---

❤️ Credits

Artwork is retrieved from the Libretro Thumbnail Archive.

Built with Python and:

• Rich
• Python urllib
• Python concurrent.futures

---

📜 License

This project is licensed under the MIT License.

See the LICENSE file for the full license text. Feel free to use, modify, and fork this project!