A sleek, modern WPF application that automatically downloads missing cover art for your retro game ROM collection from the official libretro-thumbnails GitHub repositories.
Tired of manually hunting for game cover art? Retro Game Cover Downloader scans your ROM folders, identifies missing covers, and fetches them directly from libretro's extensive thumbnail database. With built-in rate limit handling, progress tracking, and error reporting, managing your retro gaming library has never been easier!
🎮 Multi-System Support - Automatically detects available gaming systems from libretro's repositories
📁 Smart Folder Scanning - Scans your ROMs and existing covers to find what's missing
⬇️ Batch Downloading - Downloads all missing covers in one click with progress tracking
⚡ Rate Limit Management - Intelligent handling of GitHub API limits with visual countdown timer
🔐 Token Integration - Optional GitHub token support for 4,900 downloads/hour (vs 55 without)
🔑 Auto Token Prompt - Automatically prompts for a new token on 401 Unauthorized errors
🔄 Update Checker - Automatically notifies you of new versions
🐛 Error Reporting - Automatic bug reports to help improve the application
⏹️ Cancellation Support - Cancel operations anytime
📊 Progress UI - Real-time progress bar and status messages
🖥️ CLI Support - Command-line arguments for automation
🌐 Proxy Support - Configure HTTP proxy with host, port, and authenticated credentials
📂 File Extensions Configuration - Customize which file extensions are recognized as ROM files
🔒 Settings Encryption - Tokens and passwords are encrypted using Windows DPAPI
🔁 Retry with Exponential Backoff - Automatic retry on transient failures with intelligent backoff
⚡ Circuit Breaker - Protects against hammering distressed servers during outages
💾 Systems Cache - Caches the available systems list for faster startup and offline resilience
🌙 Modern UI - Fluent Design dark theme powered by WPF-UI
📸 Screenshot Hotkey - Press F8 anytime to capture the app window
- Windows 10 or later
- .NET 10.0 Runtime (installed automatically with the application)
- Grab the latest release from the Releases Page
- Extract the ZIP file to your desired location
- Run
RetroGameCoverDownloader.exe
To unlock the full 4,900 downloads/hour limit:
- Go to File → GitHub Token in the menu bar (the token dialog also appears automatically on first launch)
- Follow the in-app instructions or:
- Visit GitHub Token Settings
- Generate a token with
public_reposcope - Copy and paste it into the application
💡 Tip: Without a token, you're limited to ~55 covers/hour. With a token, you can download thousands!
- Set ROM Folder: Browse to your ROM collection directory
- Set Cover Folder: Choose where to save cover images
- Select System: Pick your gaming system (NES, SNES, Genesis, etc.)
- Prepare: Scan and identify missing covers
- Download: Fetch all missing covers automatically
# Basic usage (ROM folder first, then Cover folder)
RetroGameCoverDownloader.exe "C:\ROMs\SNES" "C:\Covers\SNES"
# With flags
RetroGameCoverDownloader.exe --cover "C:\Covers" --rom "C:\ROMs"
# Positional arguments (ROM folder first, then Cover folder)
RetroGameCoverDownloader.exe "C:\ROMs" "C:\Covers"- MVVM Pattern: Main window uses ViewModels; dialogs use code-behind for simplicity
- Async/Await: Fully asynchronous operations for UI responsiveness
- WPF-UI: Modern Fluent Design dark theme with dynamic resources
- Serilog: Structured logging with buffered UI sink, file sink, and debug output
- Rate Limiting: Custom
RateLimiterservice with event notifications - Error Handling: Comprehensive logging and bug reporting via BugReportSink
- Circuit Breaker: Tracks consecutive 503 errors and triggers cooldown to avoid hammering distressed servers
- Retry Logic: Exponential backoff with configurable retry attempts
MainViewModel: Core business logic and state managementGitHubService: Handles all GitHub API interactionsBugReportService/BugReportSink: Automatic error reporting via structured Serilog sinkSettingsManager: JSON-based settings persistence with DPAPI encryption for sensitive dataRateLimiter: Intelligent API request throttlingUpdateCheckerService: Checks for new application versions
The project includes a comprehensive test suite using xunit:
dotnet testTests cover models, services, helpers, converters, commands, ViewModels, managers, and integration tests. A MockBugReportService is injected via [ModuleInitializer] to prevent real API calls during testing.
This project is licensed under the GPL-3.0 license.
- Issues: Report Bugs
- Discussions: Ask Questions
- Email: support@purelogiccode.com
If you find this project helpful, please consider giving it a star on GitHub! It helps others discover the project and motivates continued development.
⭐ Click the star button at the top of the repository if you like this project! ⭐