Launch ROMs via URL

Open games directly using Provenance's URL scheme

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

If system is provided but invalid, the game will not open — even if a title match exists. Double-check your system identifier.

---

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

The home screen icon will use a generic Safari bookmark icon. For a custom icon, use the Shortcuts app method below.

iOS Shortcuts Automation

Build Shortcuts workflows that launch games:

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

Game Picker Menu

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

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.

---

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

---

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.