# Launch ROMs via URL
Provenance registers a custom URL scheme (`provenance://`) that lets you launch games directly from Safari, Shortcuts, home screen bookmarks, or other apps.
***
## URL Scheme Syntax
```
provenance://open?[parameter]=[value]
```
### Parameters
You can identify a game using any of these parameters (or combine them):
| Parameter | Description | Example |
| --------- | ------------------------------------- | ------------------------------------------------------------- |
| `md5` | Game's MD5 hash (exact match) | `provenance://open?md5=85260599FDADA2E137053A8647AA0D06` |
| `title` | Game title (exact match, URL-encoded) | `provenance://open?title=Super%20Mario%20World` |
| `system` | System identifier (use with `title`) | `provenance://open?title=Sonic&system=com.provenance.genesis` |
### Combining Parameters
Use `title` + `system` together when you have games with the same name on different systems:
```
provenance://open?title=Tetris&system=com.provenance.gb
provenance://open?title=Tetris&system=com.provenance.nes
```
{% hint style="info" %}
If `system` is provided but invalid, the game will **not** open — even if a title match exists. Double-check your system identifier.
{% endhint %}
***
## System Identifiers
Use these identifiers with the `system` parameter:
| System | Identifier |
| ------------------------- | ----------------------------- |
| **Nintendo** | |
| NES / Famicom | `com.provenance.nes` |
| Famicom Disk System | `com.provenance.fds` |
| SNES / Super Famicom | `com.provenance.snes` |
| Nintendo 64 | `com.provenance.n64` |
| Game Boy | `com.provenance.gb` |
| Game Boy Color | `com.provenance.gbc` |
| Game Boy Advance | `com.provenance.gba` |
| Virtual Boy | `com.provenance.vb` |
| Pokemon mini | `com.provenance.pokemonmini` |
| Nintendo DS | `com.provenance.nds` |
| Nintendo 3DS | `com.provenance.3ds` |
| **Sega** | |
| SG-1000 | `com.provenance.sg1000` |
| Master System | `com.provenance.mastersystem` |
| Genesis / Mega Drive | `com.provenance.genesis` |
| Game Gear | `com.provenance.gamegear` |
| Sega CD / Mega-CD | `com.provenance.segacd` |
| Sega 32X | `com.provenance.32x` |
| Sega Saturn | `com.provenance.saturn` |
| Dreamcast | `com.provenance.dreamcast` |
| **Sony** | |
| PlayStation | `com.provenance.psx` |
| PSP | `com.provenance.psp` |
| **Atari** | |
| Atari 2600 | `com.provenance.2600` |
| Atari 5200 | `com.provenance.5200` |
| Atari 7800 | `com.provenance.7800` |
| Atari Lynx | `com.provenance.lynx` |
| Atari Jaguar | `com.provenance.jaguar` |
| **NEC** | |
| PC Engine / TurboGrafx-16 | `com.provenance.pce` |
| TurboGrafx-CD | `com.provenance.pcecd` |
| PC Engine SuperGrafx | `com.provenance.sgx` |
| PC-FX | `com.provenance.pcfx` |
| **SNK** | |
| Neo Geo Pocket | `com.provenance.ngp` |
| Neo Geo Pocket Color | `com.provenance.ngpc` |
| **Bandai** | |
| WonderSwan | `com.provenance.ws` |
| WonderSwan Color | `com.provenance.wsc` |
| **Other** | |
| ColecoVision | `com.provenance.colecovision` |
***
## Use Cases
### Add a Game to Your Home Screen
Create a "shortcut" icon that launches directly into a game:
1. Open **Safari** on your iPhone/iPad
2. Type the URL in the address bar:
```
provenance://open?title=Super%20Mario%20World
```
3. Tap **Share** (the share icon) → **Add to Home Screen**
4. Name it (e.g., "Super Mario World") and tap **Add**
5. Tap the new icon to launch directly into the game
{% hint style="info" %}
The home screen icon will use a generic Safari bookmark icon. For a custom icon, use the Shortcuts app method below.
{% endhint %}
### iOS Shortcuts Automation
Build Shortcuts workflows that launch games:
{% tabs %}
{% tab title="Simple Game Launcher" %}
1. Open the **Shortcuts** app
2. Tap **+** to create a new shortcut
3. Add action: **Open URLs**
4. Enter: `provenance://open?title=Your%20Game%20Name`
5. Tap the shortcut name → **Add to Home Screen**
6. Choose a custom icon and name
{% endtab %}
{% tab title="Game Picker Menu" %}
Create a menu that lets you choose from your favorite games:
1. Open **Shortcuts** → tap **+**
2. Add action: **Choose from Menu**
3. Add options for each game (e.g., "Mario", "Zelda", "Sonic")
4. Under each option, add **Open URLs** with the matching URL:
* `provenance://open?title=Super%20Mario%20World`
* `provenance://open?title=Legend%20of%20Zelda`
* `provenance://open?title=Sonic%20the%20Hedgehog&system=com.provenance.genesis`
5. Add to Home Screen with a custom icon
{% endtab %}
{% endtabs %}
### Link from Other Apps
Use the URL scheme anywhere that supports links:
* **Notes app** — Paste URLs as tappable links to organize your game collection
* **Reminders** — Link a game for "play later" lists
* **Web pages** — Create an HTML page with links to your games
* **Other automation apps** — Scriptable, Toolbox Pro, etc.
***
## URL Encoding
Game titles with special characters must be URL-encoded:
| Character | Encoded | Example |
| ----------- | ----------- | ----------------------- |
| Space | `%20` | `Super%20Mario%20Bros` |
| Apostrophe | `%27` | `Kirby%27s%20Adventure` |
| Colon | `%3A` | `Castlevania%3A%20SOTN` |
| Ampersand | `%26` | `Toejam%20%26%20Earl` |
| Parentheses | `%28` `%29` | `Pokemon%20%28Red%29` |
{% hint style="info" %}
**Tip:** The Shortcuts app handles URL encoding automatically when you use the "URL Encode" action. Safari also auto-encodes when you type in the address bar.
{% endhint %}
***
## Troubleshooting
URL opens Provenance but no game launches
* **Title mismatch:** The title must match exactly as it appears in your Provenance library (including capitalization and punctuation). Check your library for the exact name.
* **Invalid system ID:** If using the `system` parameter, verify the identifier from the table above. An invalid system ID causes the lookup to fail silently.
* **Game not imported:** The game must already be in your library. URLs don't import games — they only open existing ones.
"Cannot Open Page" error in Safari
* Provenance must be installed on the device
* Make sure the URL starts with `provenance://` (not `http://`)
* Check for typos in the URL
Shortcut doesn't work
* In Shortcuts, make sure you're using the **Open URLs** action (not "Open App")
* Verify the URL is correct by testing it in Safari first
* Ensure Provenance is allowed in Settings → Shortcuts
***
{% hint style="success" %}
**Pro tip:** Use the `md5` parameter for the most reliable matching — it uniquely identifies a ROM regardless of title or system. Find a game's MD5 in Provenance by long-pressing → Game Info.
{% 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/advanced/launch-roms-via-url.md?ask=
```
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.