AppleTV with XBMC

Playing any recording on an Apple TV 2
This article deals with the jailbreaking the (black) Apple TV 2nd generation, and installing XBMC. For information on jailbreaking the AppleTV 1st generation, see AppleTV and EyeTV.

Hardware

 * Jailbroken (hacked) Apple TV (version 2) to show recordings on a television.
 * Network disk (Network-Attached Storage, NAS) or desktop PC or Mac that acts as a file server with recorded television shows.
 * A micro-USB cable (not included with the Apple TV, but fairly common for mobile phones)

The Problem

 * The Apple TV supports only a few movie formats and only sees content in the iTunes library, but not recorded content (such as EyeTV recordings) or downloaded content (from a different reseller than Apple's own store).
 * Software such as EyeTV (that I use to record television broadcasts) allows automatic export of the recordings to iTunes, but conversion takes hourse and hours, and requires a fair amount of disk space.

The solution

 * Television shows are recorded on my Mac using EyeTV
 * Movies are downloaded on my Mac, or converted from DVD to MP4 format using Handbrake. (XBMC handles VIDEO_TS folders, but AppleTV has hardware acceleration for the H.264 encoding in MP4 files, and that plays much better than native DVD files).
 * Optional: The shows copied to put on a (LaCie) file server (Network-Attached Storage, NAS) (alternative: configure your Mac as a Windows file server).
 * The Apple TV runs XBMC which can mount the network disk with recordings and play most of them.

The most easy solution to first jailbrake the Apple TV software using either Seas0nPass or PwnageTool and then install a mplayer-based media center, such as XBMC.

The following describes my experience.

Jailbreaking Apple TV 2
Jailbreaking is the process of hacking a device so that it can run any software you like.

Jailbreaking of the Apple TV 2nd generation is the hardest part, even though it is still pretty straightforward is you have some UNIX experience.

The procedure goes as follows:
 * Create a IPSW file which includes a shell daemon. The name IPSW comes from iPhone software, since the Apple TV 2nd generation runs iOS (the iPhone/iPad OS). IPSW files contain the operating system and the software.
 * Connect the Apple TV to a computer using a micro-USB cable (warning: this cable is not included with the Apple TV; you have to buy it separately -- the cable is often used to charge mobile phones), and bring the Apple in DFU (Device Firmware Update) mode.
 * Use iTunes to install the software on the IPSW on the Apple TV.
 * Log in to the Apple TV using SSH.

Creating a IPSW File
IPSW contain the operating system and some software for iOS-based hardware, including the Apple TV.

I used Seas0nPass to create (and install) the IPSW software. PwnageTool is an alternative.

Your best choice depends on the iOS version (4.2.1, 4.3 are in common use at time of this writing) of the Apple TV and the operating system of the computer you connect to (Mac or Windows). By all means, check out the Jailbreak wizard at iClarified. With a few clicks, you see what software you can use, and get a excellent walk-through.

DFU Mode
After the IPSW file is created, you are instructed to boot your Apple TV in DFU mode. DFU means Device Firmware Update. You disconnect HDMI, power and network from your Apple TV, and hook it up to your computer using a micro-USB cable. A micro-USB cable is not included with the Apple TV, so you have to buy it separately -- micro-USB is now the standard for charging mobile phone, so it is readily available in shops (Apple is one of the few manufacturers with a non-standard connector) (for the techies: you need a male USB type A connector for your computer and a male USB micro A connector for your Apple TV). There is some debate if the power cord should be connected to the Apple TV or not. For me, it worked fine with the power cord disconnected.

After the Apple TV is connected to your computer, press and hold the menu and play buttons on the Apple TV' remote for 7 seconds. After that, release the buttons, and the light on your Apple TV should flash rapidly. It is now in DFU mode.

Note that the above is referred to as a tethered jailbreak, since you actually connect the Apple TV to your computer. An untethered jailbreak would not need an external computer. I do not know of any untethered jailbreaks for the Apple TV (they do exist for the iPhone and iPad). I recommend to ignore the terminology, and simply follow the instructions in the how-to at iClarified's Jailbreak wizard'''.

Use iTunes to Install a IPSW File
Most jailbreak software only create the IPSW file, but do not install it on the Apple TV themselves. iTunes is used to actually install the software on the Apple TV.

If you are running Linux or Windows, it seems that the redsn0w software by the dev team (of course not the real iPhone developer team, but a bunch of clever hackers who call themselves like that) is able to install IPSW files without the help of iTunes. I have no experience with redsn0w myself (if you tried this and know of a good tutorial, let me know and I gladly link to it!).

Seas0nPass is able to control iTunes for you (that's why the Mac version asks you to enable application scripting when you run Seas0nPass for the first time), but the procedure is simple enough to do it yourself.


 * Connect your Apple TV to your computer and bring in in DFU mode as described above
 * Start iTunes; your Apple TV should be listed. If it is not, your Apple TV is not properly connected to your computer.
 * In iTunes, you should see a "Restore" button. Hold down the alt (option) key and press this button. This will bring up a dialog where you can select a IPSW file. (If you didn't hold the alt key, it will install a IPSW file from a standard location; usually not the jailbroken version).

The software "restore" takes up to 10 minutes. iTunes will report when it is done.

SHSH Files
Before iTunes will actually install the IPSW file, it verifies with the Apple Update Server (gs.apple.com) if the given IPSW file is suitable for the given device.

This is good news and bad news. It's good news that you don't accidentally install software which is incompatible with the given hardware (like a Apple TV IPSW file on an iPad or vice versa). It is bad news in that it gives Apple control what software you may install on the device you own. Right now, Apple is relative liberal and lets you install any technically compatible software. There is no guarantee that this policy will never change in the future.

For this reason, many sites recommend to make backups of the so-called SHSH files. These files contain a checksum (the SHSH blob in jargon) which is signed by Apple. Since it is impossible to recreate Apple's signature, the backups allow you to re-install old IPSW files in case Apple later decides to retract their signature from their update server.

If iTunes fails to find a valid signature, it will display the following error message:
 * The Apple TV "Apple TV" could not be restored. This device isn't eligible for the requested build.

The reason could be the network on your computer is down, or the Apple Update Server (gs.apple.com) is not reachable.

My first thought upon realizing the problem was "oh no, Apple must have blocked this; I should find a way to redirect traffic to another server which does approve it." It turned out that the exact opposite was true: I had run TinyUmbrella, a program designed to backup the SHSH files. TinyUmbrella did exactly this. There is an option in the program called "Set Hosts to Cydia on Exit", which adjusts the /etc/hosts file on your computer to redirect all traffic for gs.apple.com (Apple's Update Server) to 74.208.10.249 (a machine under control by the Cydia developers. (Cydia a package manager for Jailbroken iOS hardware.)

It turned out that in my case, Apple just released a new version of their software (4.3), but the signature was not yet available on the Cydia server, so iTunes erroneously rejected the IPSW file. This problem is described by Lei Mobile as well.

My recommendation is to run TinyUmbrella or another program to backup your SHSH files, but to turn off the "Set Hosts to Cydia on Exit", so your Mac runs unmodified after you quit TinyUmbrella. You can turn this back on if Apple ever changes its policy.

Log in to the Apple TV
You can log in to your Apple TV using SSH.

If you just Jailbroken the device, the root password is "alpine". Make sure that one of the first things you do it to change this password (and store it in your KeyChain, so you don't forget!):

mymac% ssh root@ root@192.0.2.7's password: alpine Apple-TV:~ root# password Changing password for root. New password: Retype new password: Bedroom-Apple-TV:~ root#

The package manager in most Jailbreaks is apt-get.

To search for a specific package, run: % apt-cache search

To install a specific package, run: % apt-get install

Specify Software Repositories
If you plan to use the command line to install software, it is important that you specify good sources for your software. This is done in /etc/apt/sources.list.d/.

Cydia is a user-interface for apt-get for your jailbroken your iPhone or iPad. In addition, it is a repository of software. Unfortunately, it only seem to list junk software, mostly thousands of ugly themes from five sources (including Big boss and zodttd). I recommend that you trash these sources: rm /etc/apt/sources.list.d/cydia.list

On the other hand, the following sources are worth-while: deb http://apt.awkwardtv.org/ stable main deb http://nitosoft.com/cydia / deb http://apt.saurik.com/ ios main deb http://mirrors.xbmc.org/apt/atv2 ./ deb http://dl.firecore.com/black /

For some reason the file /etc/apt/sources.list.d/saurik.list is empty by default (and the cydia.list file contains an incorrect URL for saurik). So I manually added this source: echo "deb http://apt.saurik.com/ ios main" >> /etc/apt/sources.list.d/saurik.list

The Firecore source was add after I bought the aTV Flash (black) software. I can recommend it.

The other sources where there already.

Disable Automatic Updates
Even if you jailbroken your Apple TV, it will check for Software Updates. If an update is available, you are presented with a menu where you can select between "Update Now" and "Update Later". If you select "Update Now", the software is updated and your jailbroken software is removed.

Your may want to click "Update Later" until the jailbreak software has been updated as well. Alternatively, you can disable checking for updates.

The easiest way to do this is to make sure your Apple TV can no longer reach Apple's servers. You can do this by adding the following lines in the file /etc/hosts on your Apple TV:

127.0.0.1      gs.apple.com 127.0.0.1      mesu.apple.com

Since the Apple TV OS does not come with an editor, here is a simple way to append the line in the UNIX shell (make sure to use, not  ): echo "127.0.0.1      gs.apple.com" >> /etc/hosts echo "127.0.0.1      mesu.apple.com" >> /etc/hosts

An alternative is to install the com.nito.updatebegone package: apt-get install com.nito.updatebegone

Install Unix Tools
If you want to install UNIX tools, such as vim</tt> on your Apple TV, make sure that the repository for saurik is correct, as described above. Otherwise, apt will not be able to find the vim package.

Install XBMC on the Apple TV
Log in to your Apple TV and install XBMC:

ssh root@<IP address of your Apple TV>
 * 1) apt-get update
 * 2) apt-get install org.xbmc.xbmc-atv2

And that's it. Now connect your Apple TV to your television, and you should a XBMC menu.

Issues
I encountered a few issues.

Overscan of screen

 * Problem:The borders of the picture are not visible on the television
 * Solution:This can be fixed in the System preferences of XBMC (System - Video - Calibration pattern...)

Recording stops playing after a few minutes

 * Problem:Recordings stop playing after a few minutes, a gray screen is show, and XBMC quits.
 * Solution:Unknown. For some reason, the problem disappeared for me, so I did not check any further.

Two possible suggestions. The first was my initial thought, the second is what I read on a website somewhere:
 * 1) Perhaps the SMB connection times out. In that case it might help to mount a network disk in the OS, instead of mounting it from within XBMC.
 * 2) There is an update available, and as soon as the AppleTV is trying to pop up a window telling the user there is an update, XBMC crashes.

Play DVD files

 * Problem:XBMC displays DVD's as a folder with VIDEO_TS folder and .VOB files. The VOB files can be played, but it is impossible to change language.
 * Solution:Play the VIDEO_TS.IFO file, not the VTS_01_1.VOB file. Also, it is possible to press the "play" button instead of the "OK" button on your Apple remote control if you see the VIDEO_TS folder. This will start playing immediately instead of browsing the DVD folder.

Install Media Player on the Apple TV
Media Player is a simple media player created by Firecore. It is part of the $30 aTV Flash (black) software.

I recommend it. It can be installed by following the instructions at the Firecore site, or using apt-get:

apt-get install com.firecore.media