Enrich your retro game and ROM collection with titles, cover art, descriptions, release years, genres, and platform info — automatically, from community-maintained game databases.
nself license set nself_pro_...
nself plugin install game-metadata
nself build
nself startnself-game-metadata queries the IGDB (Internet Game Database via Twitch API) and ScreenScraper APIs to match ROM files to their canonical game entries. When nself-file-processing ingests a ROM, it calls this plugin to look up the game by filename, hash, or title and fetch the full record: cover art, screenshots, synopsis, genre, publisher, release date, and player count.
Platform detection is automatic — the plugin reads the file extension and parent folder name to identify the platform (NES, SNES, GBA, PS1, N64, Sega, etc.) before querying the database. Hashes (CRC32, MD5, SHA1) are computed and sent to ScreenScraper for accurate matching when filenames are non-standard or modified.
Cover art and screenshots are downloaded to object storage. Metadata is cached in Postgres to reduce API calls on repeated library scans. A background refresh job updates stale entries (default: 30 days) and picks up new artwork when it becomes available on the upstream databases.
| Variable | Required | Description |
|---|---|---|
DATABASE_URL | Yes | Postgres connection string (auto-set by nself) |
GAME_IGDB_CLIENT_ID | Yes | Twitch application Client ID (used for IGDB access) |
GAME_IGDB_CLIENT_SECRET | Yes | Twitch application Client Secret |
GAME_SCREENSCRAPER_USER | No | ScreenScraper username for hash-based lookup (recommended) |
GAME_SCREENSCRAPER_PASS | No | ScreenScraper password |
GAME_IMAGE_BUCKET | No | Object storage bucket for cover art and screenshots. Defaults to media bucket |
GAME_CACHE_REFRESH_DAYS | No | Days before re-fetching cached metadata. Default: 30 |
GAME_LANGUAGE | No | Preferred metadata language code. Default: en |
| Endpoint | Method | Description |
|---|---|---|
/game/search | GET | Search by title and optional platform. Returns ranked IGDB matches |
/game/:id | GET | Full game metadata by internal ID (cached) |
/game/enrich/:media_id | POST | Force-enrich a ROM file in the ɳTV library with game metadata |
/game/platforms | GET | List all known platforms with ROM extension mappings |
/health | GET | Plugin health and IGDB API connectivity |
| Table | Purpose |
|---|---|
np_game_metadata | Cached game records: title, platform, genre, publisher, release date, player count |
np_game_images | Cached image paths in object storage (covers, screenshots, box art) |
np_game_platforms | Platform registry: name, extension list, ScreenScraper system ID, IGDB platform ID |
| Event | Payload |
|---|---|
game.enriched | Media ID, IGDB game ID, platform, match confidence |
game.match.failed | Media ID, filename attempted, platform detected, top candidates |
nself-game-metadata is the enrichment layer for ROM and game file content in ɳTV. When nself-file-processing ingests a ROM, it triggers enrichment here. The ɳTV app displays cover art, descriptions, and platform badges in the game library view. Use nself-streaming with an emulator container to serve games as streaming sessions.
IGDB credentials: IGDB requires a free Twitch developer account. Register at dev.twitch.tv, create an application, and use the Client ID + Secret. The plugin handles OAuth token refresh automatically.
Match not found: ROMs with non-standard names (translations, hacks, regional variants) often fail title-based lookups. Set GAME_SCREENSCRAPER_USER and GAME_SCREENSCRAPER_PASS to enable hash-based lookup — ScreenScraper maintains a comprehensive hash database that handles most no-intro and redump sets.
Port: 3516 (moved from 3123) | Bundle: ɳTV ($0.99/mo) or ɳSelf+ ($3.99/mo) | Last Updated: May 2026 | Plugin Version 1.0.13