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

Paste from Clipboard (iOS)

The quickest way to replace a single game's artwork:

1. Find an image in Safari, Photos, Files, or any app

2. Tap and hold the image → Copy

3. Open Provenance → long-press the game you want to update

4. Select Paste Custom Artwork

5. The cover art updates immediately

Upload via Web Server

Best for bulk replacement and tvOS (which doesn't support pasting).

1. Start the Web Server in Provenance:

   • Tap the + button in the Game Library, or

   • Settings → Import/Export

2. On your computer, open http://[device-ip] in a browser

3. Open the Imports folder

4. Upload your image files (.png or .jpg)

5. Provenance matches images to ROMs by filename

WebDAV alternative:

1. Connect to http://[device-ip]:81 via Finder (Mac) or a WebDAV client

2. Drop images into the Imports folder

Mass Replacement

Replace artwork for your entire library at once:

1. On your computer, gather all cover art files in one folder

2. Name each image to match its ROM filename (see Formatting below)

3. Upload all images to the Imports folder via Web Server or WebDAV

4. 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.sfc

Matching cover art:

Super Mario World.png

Requirements:

• Image format must be .png or .jpg

• Filename (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

iOS

1. Long-press the game in your library

2. Select Rename

3. Type the new name → tap Done

tvOS

1. Select the game and press and hold the Remote or Controller action button

2. Select Rename

3. Type the new name → select Done

Via Game Info (iOS)

1. Long-press the game → select Game Info

2. Long-press the Title field

3. Edit the title → tap Done

---

Editing Game Info

Edit detailed metadata for any game (iOS only):

1. Long-press a game in your library

2. Select Game Info (or 3D Touch and swipe up)

3. Long-press any editable field:

   • Title

   • Description

   • Genre

   • Publisher

   • Release Date

   • Region

4. 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.