# Customizing ROMs

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

{% hint style="warning" %}
Please refer to the [Known Issues](#known-issues) regarding customizing ROMs before posting a new one.
{% endhint %}

***

## Replacing Cover Art

{% tabs %}
{% tab title="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
   {% endtab %}

{% tab title="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
   {% endtab %}

{% tab title="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](#formatting) below)
3. Upload all images to the **Imports** folder via Web Server or WebDAV
4. Provenance auto-matches images to games

{% hint style="info" %}
Mass replacement via upload is the recommended method for large libraries. Pasting works one game at a time.
{% endhint %}
{% endtab %}
{% endtabs %}

### 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

{% tabs %}
{% tab title="iOS" %}

1. **Long-press** the game in your library
2. Select **Rename**
3. Type the new name → tap **Done**
   {% endtab %}

{% tab title="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**
   {% endtab %}

{% tab title="Via Game Info (iOS)" %}

1. **Long-press** the game → select **Game Info**
2. **Long-press** the Title field
3. Edit the title → tap **Done**
   {% endtab %}
   {% endtabs %}

***

## 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**

{% hint style="info" %}
**Play History** (play count, time spent) can be **reset** but not manually edited.
{% endhint %}

***

## Known Issues

<details>

<summary><strong>Cover art lost on "Refresh Library"</strong></summary>

Custom cover art [is not retained](https://github.com/Provenance-Emu/Provenance/issues/730) 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.

</details>

<details>

<summary><strong>Cover art doesn't appear after uploading</strong></summary>

* 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

</details>

<details>

<summary><strong>Custom game names reset on Refresh Library</strong></summary>

Custom names are [not currently preserved](https://github.com/Provenance-Emu/Provenance/issues/514) during Refresh Library. Avoid refreshing if you've renamed many games.

</details>

<details>

<summary><strong>Files with extra dots in filename cause a crash</strong></summary>

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`).

</details>

<details>

<summary><strong>Metadata not auto-matching for some ROMs</strong></summary>

ROMs that fail checksum matching (translations, hacks, homebrew) won't auto-populate metadata. You can manually edit game info from the Game Info view.

</details>

***

{% hint style="info" %}
Need help? Ask on [Discord](https://discord.gg/provenance).
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.provenance-emu.com/using-provenance/roms/customizing-roms.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.