Customizing ROMs
Rename games, replace cover art, and edit game metadata
Provenance lets you personalize your game library. You can replace cover art, rename games, and edit detailed game metadata — all from within the app.
Customizable fields: Cover Art, Title, Description, Genre, Publisher, Release Date, Region, Play History
Please refer to the Known Issues regarding customizing ROMs before posting a new one.
Replacing Cover Art
The quickest way to replace a single game's artwork:
Find an image in Safari, Photos, Files, or any app
Tap and hold the image → Copy
Open Provenance → long-press the game you want to update
Select Paste Custom Artwork
The cover art updates immediately
Best for bulk replacement and tvOS (which doesn't support pasting).
Start the Web Server in Provenance:
Tap the + button in the Game Library, or
Settings → Import/Export
On your computer, open
http://[device-ip]in a browserOpen the Imports folder
Upload your image files (
.pngor.jpg)Provenance matches images to ROMs by filename
WebDAV alternative:
Connect to
http://[device-ip]:81via Finder (Mac) or a WebDAV clientDrop images into the Imports folder
Replace artwork for your entire library at once:
On your computer, gather all cover art files in one folder
Name each image to match its ROM filename (see Formatting below)
Upload all images to the Imports folder via Web Server or WebDAV
Provenance auto-matches images to games
Mass replacement via upload is the recommended method for large libraries. Pasting works one game at a time.
Formatting
For cover art to auto-match, image filenames must correspond to ROM filenames:
ROM file:
Super Mario World.sfcMatching cover art:
Requirements:
Image format must be
.pngor.jpgFilename (minus extension) must match the ROM filename exactly
Images without a matching ROM will remain in the directory until matched or manually deleted
Renaming Games
Long-press the game in your library
Select Rename
Type the new name → tap Done
Select the game and press and hold the Remote or Controller action button
Select Rename
Type the new name → select Done
Long-press the game → select Game Info
Long-press the Title field
Edit the title → tap Done
Editing Game Info
Edit detailed metadata for any game (iOS only):
Long-press a game in your library
Select Game Info (or 3D Touch and swipe up)
Long-press any editable field:
Title
Description
Genre
Publisher
Release Date
Region
Type, paste, or reset the field → tap Done
Play History (play count, time spent) can be reset but not manually edited.
Known Issues
Cover art lost on "Refresh Library"
Custom cover art is not retained when using the Refresh Library option in Settings. If you use custom artwork, keep backups of your image files so you can re-upload them via the Web Server after a refresh.
Cover art doesn't appear after uploading
Upload ROMs first, then cover art — uploading art before its matching ROM may not match immediately
Uploading ROMs + cover art in a single archive may delay matching
Fix: Force quit Provenance and relaunch to trigger re-matching
Custom game names reset on Refresh Library
Custom names are not currently preserved during Refresh Library. Avoid refreshing if you've renamed many games.
Files with extra dots in filename cause a crash
Filenames with multiple . characters (e.g., Game.v2.1.zip) can cause issues. Rename the file to use only one dot before the extension (e.g., Game v2-1.zip).
Metadata not auto-matching for some ROMs
ROMs that fail checksum matching (translations, hacks, homebrew) won't auto-populate metadata. You can manually edit game info from the Game Info view.
Need help? Ask on Discord.
Last updated