Scrapers and Metadata
GamesDownloader enriches your library with artwork, descriptions, ratings, and playtime pulled from external providers. This page covers every source, how to obtain the credentials each one needs, how titles are matched, and how the built-in metadata editor lets you fine-tune the result.
All scraped media is downloaded to your server and served locally. Covers, heroes, screenshots, logos and videos are fetched once and stored under
data/resources/, then served from your own instance. Nothing is hot-linked from a third-party CDN at browse time, so your library keeps working even if a provider goes offline or rate-limits you.
- The keyed scrapers
- Built-in, keyless sources
- What each source provides
- How title matching works
- The Edit Metadata panel
- Metadata backup and restore
- Plugins as metadata providers
- Where credentials are stored
Settings → Metadata: scraper credentials, each with a Test button
Four providers need credentials, entered under Settings → Metadata. Each row has a Test button that verifies the credentials against the live service before you save. All four are optional; add only the ones you want.
Game metadata, covers, ratings, and franchise data. IGDB authenticates through Twitch, so you create a Twitch application, not an IGDB one:
- Sign in at dev.twitch.tv/console/apps and click Register Your Application.
- Give it any name, set the OAuth Redirect URL to
http://localhost, category Application Integration. - Copy the Client ID and generate a Client Secret.
- Paste both into Settings → Metadata → IGDB and click Test.
Backgrounds, descriptions, and ratings from RAWG.io.
- Go to rawg.io/apidocs and request a free API key.
- Paste it into Settings → Metadata → RAWG.
Community artwork: grid covers, hero banners, logos, and icons (including animated WebP variants).
- Sign in at steamgriddb.com, open Preferences → API.
- Generate an API key and paste it into Settings → Metadata → SteamGridDB.
The primary ROM metadata source: covers, heroes, screenshots, support art, videos, descriptions, and scores. ScreenScraper needs a free user account:
- Register at screenscraper.fr.
- Enter your account username and password under Settings → Metadata → ScreenScraper.
Developer credentials (optional). ScreenScraper's API also expects a registered developer identity. GamesDownloader ships with a built-in one, so scraping works out of the box with just your user account. The developer credentials fields let you supply your own registered ScreenScraper dev ID and password if you have them (useful for higher personal rate limits). Leave them blank to use the built-in default. The lookup order is: your configured dev credentials, then the SCREENSCRAPER_DEVID / SCREENSCRAPER_DEVPASSWORD environment variables if set, then the built-in default.
These need no configuration and are always available:
| Source | Provides | Notes |
|---|---|---|
| GOG | Covers, backgrounds, logos, descriptions, requirements, ratings | Pulled from your connected GOG account for GOG titles. See GOG Integration. |
| LaunchBox | ROM covers (Box-Front, Box-3D, Fanart), heroes, screenshots, clear logos, descriptions, ratings | The metadata archive is downloaded on first boot and built into an on-disk SQLite index (persistent, near-zero RAM after the first build). |
| HowLongToBeat | Playtime estimates (Main Story, 100%) | Shown on GOG, Custom Games, and ROM detail pages. |
| Steam | Requirements, ratings | For the GOG / Custom Games library. |
| SystemRequirementsLab | System requirements | For the GOG / Custom Games library. |
| Source | Covers | Backgrounds | Logos | Description | Requirements | Rating | Playtime |
|---|---|---|---|---|---|---|---|
| GOG | + | + | + | + | + | + | |
| SteamGridDB | + | + | + | ||||
| IGDB | + | + | + | ||||
| RAWG | + | + | + | ||||
| Steam | + | + | |||||
| SystemRequirementsLab | + | ||||||
| HowLongToBeat | + |
| Source | Cover | Hero | Screenshots | Support / Bezel / Wheel | Steam Grid | Video | Description | Score | Playtime |
|---|---|---|---|---|---|---|---|---|---|
| ScreenScraper | + | + | + | + | + | + | + | ||
| IGDB | + | + | + | + | |||||
| LaunchBox | + | + | + | + | + | + | |||
| SteamGridDB | + | + | + | + | |||||
| Plugins | + | + | + | + | + | + | |||
| HowLongToBeat | + |
A single scrape pass queries all configured sources for a title and merges the results, so you get the best available artwork and data from across providers in one go.
Matching is title-based. GamesDownloader normalises the game name and searches each provider, using smart matching to avoid wrong-game results (for example, distinguishing a remaster from the original, or ignoring edition suffixes). You can always override the match manually in the Edit Metadata panel.
ROM matching is far more precise because it is hash-based:
-
Hash match (most accurate). GamesDownloader computes CRC32, MD5, and SHA1 of the ROM and looks it up in the provider's database. For
.zipand.7zarchives the hash is taken from the ROM inside the archive, not the archive itself, so compression does not break matching. - Filename match. If no hash match is found, the filename is used.
- Name search. As a last resort, a text search on the cleaned-up title.
This is why ROM scraping is usually spot-on: an exact hash identifies the precise revision of a game.
The Edit Metadata panel with combined multi-source search
Every game has an Edit Metadata editor for reviewing and overriding what was scraped. Highlights:
- Combined multi-source search across ScreenScraper, IGDB, LaunchBox, SteamGridDB, and metadata plugins, with icon-based source filter buttons and per-source result counts.
- Ten tabs for ROMs: Cover, Hero, Screenshots, Support, Bezel, Wheel, Steam Grid, Video, Description, Details.
- Per-field Apply. The Description and Details tabs show each source side by side so you can apply, say, the IGDB description but the ScreenScraper score.
- Box-art variant picker (front, 3D, back, spine) and a manual URL override for any image.
- Scrape this version re-scrapes a single result from ScreenScraper or LaunchBox.
- Source badges with provider icons appear on every cover thumbnail so you always know where an image came from.
For the preferred ROM cover, GamesDownloader defaults to the 2D box art from the ScreenScraper region; you can switch variant per game.
The bottom of Settings → Metadata has a backup and restore tool:
- Backup exports your scraped metadata (and, optionally, the downloaded media and your settings) into a single downloadable archive, with live counts of how many rows and how much media will be included.
- Restore imports such an archive, with independent toggles for metadata, media, and settings, and a summary of inserted / updated / skipped rows afterwards.
This lets you move a fully-scraped library to another instance, or keep an offline snapshot, without re-scraping everything.
Metadata plugins add extra sources that behave exactly like the built-in ones: they contribute covers, heroes, logos, screenshots, descriptions, and ratings across the GOG, Custom Games, and ROM libraries, and they appear in the Edit Metadata search alongside the native providers. Examples on the store include TheGamesDB and PPE.pl. See Plugin Development to write your own.
All scraper credentials you enter in Settings → Metadata are stored in the application database and encrypted at rest (with a key derived from your GD_AUTH_SECRET_KEY). They are not read from environment variables, and you should never put them in .env - that would keep them in plaintext for no benefit. See Configuration → Infrastructure vs in-app settings.
Next: Email & Notifications or Network & Security.