Retro Gaming on Apple TV

Provenance on Apple TV

For the past two weeks, I’ve been playing retro games on my Apple TV — Super Mario World, Pokémon Red, and Rocket Knight Adventures, to name a few. This is made possible by an application called Provenance — an emulator developed by James Addyman that’s based on OpenEmu. Provenance currently supports Sega Genesis, NES, Super Nintendo, Game Boy Advance, and a handful of other systems.

Unfortunately, this isn’t an app that you can just download from the App Store. Apple doesn’t allow emulators to be sold on their platforms for legal reasons. The good news is, Provenance can still be installed by sideloading the application with Xcode. There’s no need to jailbreak and you can have the app up and running with just a little bit of time, your Mac, and a USB-C cable.

What You’ll Need

  • A Mac running the latest version of macOS.
  • A fourth-generation Apple TV.
  • A USB-A to USB-C cable — this is what I used — or a USB-C to USB-C cable if you own a new MacBook or MacBook Pro.
  • An Apple developer account — a free account will work, but you’ll only be able to sign Provenance for one week, which means you’ll have to reinstall more frequently than if you had a paid account.
  • A MFi game controller isn’t required, but I highly suggest using one. I’ve been playing with the SteelSeries Nimbus and it’s a great controller. It is possible to play these games with the Siri Remote, but the experience is less than stellar.

Install Process

  • Install Xcode from the Mac App Store.
  • Once Xcode finishes installing, launch it, agree to the application’s user agreement.
  • Launch Terminal (located in the Utilities folder) and enter the following command:

    git clone https://github.com/jasarien/Provenance.git

    This command will download the necessary source code and project files that we’ll be using to install Provenance.

  • Plug in your Apple TV’s power cable in a location near your Mac. Now power your Apple TV on and connect it to your Mac with the aforementioned USB-C cable.

    Provenance Xcode Workspace in Finder

  • In Finder, navigate to the newly downloaded Provenance folder, which should be located inside of your home folder. Open the Provenance Xcode workspace — the white icon, specifically.
  • From the menu bar, open Xcode > Preferences. Inside of the Accounts tab, click on the plus button in the bottom left and choose “Add Apple ID”. Login with your developer account and close Xcode’s preferences.

    Provenance Active Scheme Menu

  • From the Active Scheme menu, choose “ProvenanceTV-release”, and click on your connected Apple TV.

    Provenance Prohect/Target Picker

  • In the left panel, click on “Provenance”.
  • From the project/target picker, choose “ProvenanceTV”.
  • In the center panel, change the middle section of the bundle identifier — the “provenance-emu” part — to something unique.

    Xcode Application Signing

  • In the “Signing” section, choose your account from the “Team” drop-down menu. Xcode should automatically generate a certificate and sign the application to be run on your Apple TV.

    Project/Target Picker, Top Shelf

  • Click on the project/target picker again and choose “TopShelf”.
  • Change “provenance-emu”, in the bundle identifier, to the same unique ID you used for the previous Bundle ID.
  • Choose your account from the “Team” drop-down.
  • Once Xcode has finished indexing and processing all the files, click on the play button in the upper left to build the app and run it on your Apple TV.
  • Once Provenance compiles and installs, you can click the stop button and quit Xcode. Unplug your Apple TV and move it back to your television.

If everything goes well, you’ll have Provenance installed on your Apple TV. But you’ll still need to import some ROMs from your computer or iOS device in order to play. This is where we start treading in waters of questionable legality, but it’s pretty easy to find a source for downloading ROMs with a simple web search.

Importing ROMs

Importing ROMs

I’ll be importing ROMs from iOS because that’s the platform I typically use, but this process could easily be performed from a Mac or PC as well.

  • Launch Provenance on Apple TV and enter the app’s settings pane.
  • Scroll down and select “Import ROMs”.
  • Provenance will start a web server on your Apple TV and display an IP address for you to visit in your web browser.
  • Scroll to the bottom of the webpage and tap on the folder icon next to “roms”.
  • Tap on the “Upload Files” button and choose the ROM you’d like to upload from the document picker — I usually save mine in Transmit, but iCloud Drive will work too.
  • The upload process should be nearly instantaneous and you can repeat this process for all of the ROMs you’d like to play.
  • Once finished, choose “Stop” on your Apple TV and navigate back to your library — Provenance will have unzipped the file, fetched game artwork, and gave the ROMs proper titles.

Updating Provenance

If you’d like to update to the latest version of Provenance or continue using the app beyond the one week signing limitation, you’ll have to regularly reinstall with Xcode. The good news is that the process for updating is the same as the initial install. Just drop the Provenance folder in the trash, run the “git” terminal command from above and follow the subsequent steps.

You won’t have to input your developer account credentials again — because you’ve already setup Xcode with them — but make sure you use the exact same bundle ID as you did when you first installed Provenance — this will tell Xcode to install the new build of Provenance on top of the existing one, retaining all of your ROMs and game saves.