Skip to content

Metadata Providers

RomM supports multiple metadata providers to enrich your game library with titles, descriptions, cover art, and achievements. You don't need all providers, so this guide covers popular combos and setup instructions.

Here are some combinations you can use based on your needs:

⭐ The French Connection: ScreenScraper + Retroachievements

  • Supports 125+ popular systems
  • ScreenScraper provides titles, descriptions, cover art, screenshots and manuals
    • Also supports hash-based matching (as of v4.4)
    • With the option for 3D boxes and CD/cartridge covers
  • Retroachievements provides achievement progress
  • Use this if you want to avoid Twitch/Amazon products

ScreenScraper + Retroachievements

⭐ The Chef's Choice: Hasheous + IGDB + SteamGridDB + Retroachievements

  • Supports 135+. popular systems
  • Hasheous provides hash-based matching and proxies IGDB data (titles, descriptions and artwork)
  • IGDB adds additional metadata like related games and screenshots
  • SteamGridDB provides high-quality alternative cover art
  • Retroachievements provides achievement progress
  • This is the recommended setup for most users

Hasheous + IGDB + SteamGridDB + Retroachievements

The Twitch Fanboy: IGDB + PlayMatch

  • Supports the 200+ systems available on IGDB
  • Provides titles, descriptions, cover art and related games from IGDB
  • PlayMatch adds hash-based matching for unmatched files
  • Use this if you want a single-provider solution

The Quick Starter: Hasheous

  • Hash-based matching only ⚠️
  • Proxies titles, descriptions and cover art from IGDB
  • Incredibly fast scan times
  • For users who want to avoid API keys

Setup instructions

IGDB

IGDB (Internet Game Database) is a popular metadata provider that offers metadata, cover art, screenshots, related games and more.

To access the IGDB API you'll need a Twitch account and a valid phone number for 2FA verification. Up-to-date instructions are available in the IGDB API documentation. When registering your application in the Twitch Developer Portal, fill out the form like so:

  • Name: Something unique or random like romm-3fca6fd7f94dea4a05d029f654c0c44b or KVV8NDXMSRFJ2MRNPNRSL7GQT
  • OAuth Redirect URLs: localhost
  • Category: Application Integration
  • Client Type: Confidential

Important

The name you pick has to be unique! Picking an existing name will fail silently, with no error messages. We recommend using romm-<random hash>, like romm-3fca6fd7f94dea4a05d029f654c0c44b

Note the client ID and secret that appear on screen, and use them to set IGDB_CLIENT_ID and IGDB_CLIENT_SECRET in your environment variables.

Screenshots

IGDB Creation IGDB Secret

ScreenScraper

ScreenScraper.fr is a French provider that offers metadata, cover art, screenshots and manuals, along with the option for 3D boxes and CD/cartridge cover art. It supports a wide range of systems and is a great alternative to IGDB.

To access the ScreenScraper API, create a ScreenScraper account and copy the user and password you just created to SCREENSCRAPER_USER and SCREENSCRAPER_PASSWORD respectively.

MobyGames

MobyGames is a metadata provider that offers metadata, cover art and screenshots.

To access the MobyGames API, create a MobyGames account and then visit your profile page. Click the API link under your user name to sign up for an API key. Copy the key shown and use it to set MOBYGAMES_API_KEY.

Important

Access to the MobyGames API is a paid feature. While we will continue to support it, we recommend using ScreenScraper instead, as it is free to use.

LaunchBox

The LaunchBox Games Database is a community-driven database that provides metadata, cover art, and screenshots. Like the Launchbox desktop application, RomM downloads the entire database locally and matches games based on their exact filenames.

To enable LaunchBox, set LAUNCHBOX_API_ENABLED=true in your environment variables. You can enable regular updates of the database by setting ENABLE_SCHEDULED_UPDATE_LAUNCHBOX_METADATA, and set the frequency on the cron job with SCHEDULED_UPDATE_LAUNCHBOX_METADATA_CRON (defaults to 5:00 AM every day).

Hasheous

Hasheous is a free, open-source metadata provider that uses file hashes to match games. It proxies IGDB data for titles, descriptions, and cover art, and can provide Retroachievements IDs for matched games.

Simply set HASHEOUS_API_ENABLED=true in your environment variables, and future scans will start using the Hasheous API.

PlayMatch

PlayMatch is a hash-based matching service used in conjunction with IGDB to provide better matching for games, hosted by a member of our community.

To enable PlayMatch, set PLAYMATCH_API_ENABLED=true in your environment variables.

SteamGridDB

SteamGridDB provides custom cover art for games or collections. It's not accessed through the scanner but from the "search cover" button when manually editing a game.

To access the SteamGridDB API, you need to login to their website with a Steam account. Once logged in, go to your API tab under the preferences page. Copy the key shown and use it to set STEAMGRIDDB_API_KEY.

RetroAchievements

RomM is able to display your achievements from RetroAchievements. To sync it with your RomM instance, you need to generate an API key from your RetroAchievements account in your settings.

Copy the key shown and use it to set RETROACHIEVEMENTS_API_KEY and perform a UNMATCHED scan targeting the platform you want to match with RetroAchievements.

After that, each user needs to set their own username in their profile and sync it with RetroAchievements. A new Achievements tab will appear in the Personal tab in the game details.

To avoid unnecessary API calls, a cached file with the RA database is stored in RomM. Refresh time for that cache file can be changed with the environment variable REFRESH_RETROACHIEVEMENTS_CACHE_DAYS.

Screenshots

RA API key RA details

Flashpoint

The Flashpoint Project Database is a project that enables metadata for 180,000+ flash and browser-based games. Enable this metadata source with the FLASHPOINT_API_ENABLED=true environment variable. If you are adding this provider to an existing RomM setup, perform a UNMATCHED scan with Flashpoint selected to update an existing platform.

How Long To Beat

The How Long To Beat project provides game completion times for more than 84,000 games. Enable this metadata source with the HLTB_API_ENABLED=true environment variable. If you are adding this provider to an existing RomM setup, perform a UNMATCHED scan with How Long To Beat selected to update an existing platform.

Game completion times will be added to a new tab on the details page for supported matched games.

ES-DE gamelist.xml

EmulationStation, and it's modern successor ES-DE, use a custom XML format to store game metadata. RomM can parse this format and import the assets as cover art and screenshots. You'll need to store the gamelist.xml file and any related assets under the platform folder:

library/
└─ roms/
    └─ gba/
        ├─ game_1.gba
        ├─ game_2.gba
        ├─ gamelist.xml
        ├─ 3dboxes/
        │  ├─ game_1.png
        │  └─ game_2.png
        ├─ covers/
        ├─ screenshots/
        └─ etc...

Metadata Tags in Filenames

Scans will now parse custom metadata tags in the filename that match specific patterns, and use them to fetch game metadata for the specified ID. The supported tags are:

(igdb-xxxx) for IGDB (moby-xxxx) for MobyGames (ra-xxxx) for RetroAchievements (ssfr-xxxx) for ScreenScraper (launchbox-xxxx) for Launchbox (hltb-xxxx) for HowLongToBeat

Filenames will not be renamed by RomM to add tags, as they are a non-standard formatting system and could create conflicts with other software.