AppleTV and EyeTV

Playing EyeTV recordings on an Apple TV 1
This article deals with the original (white) Apple TV. For information on the (black) Apple TV version 2, see AppleTV with XBMC.

Hardware

 * Jailbroken (Hacked) Apple TV (version 1) to show recording on a television.
 * Desktop Mac with EyeTV to record television shows.

Optional:
 * Network disk (Network-Attached Storage, NAS) as a file server. This is entirely optional: you can also use your Mac as a file server.

The Problem

 * EyeTV stores contents in MPEG 1 or MPEG 2 format. Apple TV requires MPEG 4 or H.264 format. Converting takes hours and hours for even a short recording.
 * The Apple TV only sees content in the iTunes library, not directly in the EyeTV recordings folder or on a network hard disk.
 * UPnP streaming do not work very well (choppy movies, or no playback at all).

The solution

 * Television shows are recorded on my Mac using EyeTV
 * Optional: The shows copied to put on a (LaCie) file server (Network-Attached Storage, NAS) (alternative: configure your Mac as a file server).
 * The network disk with recordings is mounted on the (hacked) AppleTV.
 * The Apple TV displays these files on a television


 * Update the Apple TV software to support MPEG 1 and MPEG 2
 * Update the Apple TV software to mount the network disk

The most easy solution to update the Apple TV software is to use the description given at AwkwardTV.

The following describes my experience.

Non-Solution
The Apple TV has other drawbacks. For example, it only supports 720 pixel wide screens, not 1080 pixel wide. It can not record TV directly, and has a small hard disk. No solution to these problems is provided here, although there are ways to cope with this (even if it means buying an Mac Mini instead of Apple TV). This guide assumes that the current Operating System is patched, rather then installing a completely new operating system (e.g. Linux).

Guide
All the basics is explained at:
 * Beginners Guide for Apple TV 2.x (the 2.x refers to the software version, which works on the Apple TV 1 hardware)
 * Take 2 Full Update

Basic Procedure
What I did was:
 * Create a Patchstick using atvusb-creator to install some springboard server such as a SSH daemon (DropBear) or file server.
 * Create a new user account (for safety reasons)
 * Install NitoTV
 * install OpenAL.framework (required by nitoTV)
 * Install Perian (only if you did not install NitoTV, as it is already included with NitoTV)
 * Install Sharity in order to mount an SMB share (this worked better for me then a AFP share).
 * Install Mount_SMB in order to mount an SMB share (Sharity Light only supports an old version of the SMB protocol).

While I started this procedure as light-weight, in the course of a few years some additions where made to cope with changing requirements.

Terminology
Just some terminology that is used a lot without explanation.
 * ATV:Apple TV
 * Take 2:Version 2 of the Apple TV software by Apple. So firmware 2.3 is Take 2, release 3.
 * Patchstick:A bootable USB key that can boot the Apple TV when it is plugged in the device.

Upgrade
I recommend NOT to upgrade AppleTV to 2.3, but to stick with 2.1. I found that nitoTV does not work very well with 2.3, and nitoTV is currently the only tool that decently plays video. (note: this applies to the 2008 situation; it is likely that things have improved since)

Creating a Patchstick
The standard Operating System on the Apple TV does not allow you to modify files. There is no SSH or file access, and it is not possible to start a SSH or file server. The first goal is to install some springboard server or installer (e.g. a SSH server, ATVFiles or SoftwareMenu). This can be done by either taking out the hard disk, mount it in another computer, and add the required spingboard server. The more easy alternative it to create a patchstick, a USB key with an operating system that boots and runs an installer script for the given springboard software.

The four options to create a patchstick are:
 * 1) Use atvusb-creator, an very easy to use application that uses Linux as operating system, and can install dropbear SSH, Unix tools, SoftwareMenu and/or XBMC/Boxee. See atvusb-creator.
 * 2) Use the createPatchstick script which copies the required files from a Mac OS 10.4 (Tiger) OS and installs the OpenSSH server (the same that comes with Mac OS X), and optionally perian and atvloader. See Creating a Patchstick (be sure to download Patchstick1.0.zip!)
 * 3) Use a variant of the createPatchstick shell script that gathers the required files from a Mac OS 10.4 (Tiger) installer disk and the Mac OS 10.4.9 updater. This script can installs the OpenSSH server (the same that comes with Mac OS X). See Create Patchstick in Leopard and createPatchstick
 * 4) Manual create a patchstick. See Turbo's AppleTV Hacks and Booting from a USB Thumbdrive.

I first tried to use the createPatchstick script, but this failed for me. Diskutil created an additional EFI partition, but even after adjusting the script for that, it still did not work. I finally used atvusb-creator with a different USB key. That worked fine. As reported by others, not all USB keys work, and I suspect that I had that problem too (A Kingston 16GB USB2 key did not work. An Imation 8GB USB1 key did work).

Hard Disk
It seems that the Apple TV uses a scratch disk. The regular file system is mounted as read-only, and all changes made to the file system are stored on another disk, which is mounted at /mnt/Scratch. Thus the Scratch disk contains the incremental changes. The advantage of this approach is that it is easy to do a roll-back in case something goes seriously wrong (deleting the Scratch disk would return the unmodified file system).

Note: I have not tested the exact working of the scratch disk. As always, be cautious.

To mount the root file system are writable: mount -uw / To mount the root file system as read-only again: mount -ur /

Change Frontrow Password and Add Users
The default username and password is frontrow and frontrow. Make sure to either change the password or create a new account and disable the frontrow account:

dscl / -passwd /Users/frontrow

Second login: It is highly advisable that before you change the password, you first create an additional log in, either a second account or upload your ssh public key.

Automatic login: If you change the password in this way, the automatic login of Apple TV will no longer work. If you reboot you will see the Mac OS X login window (log-in screen) instead of the intro movie. In order to enable auto-login again, you must store the password in the file /etc/kcpassword on the Apple TV. The kcpassword file is encrypted. The following script creates a new kcpassword.

use strict; use warnings; use Foundation; sub kcpassword_xor { my ($pass) = @_; ### The magic 11 bytes - these are just repeated # 0x7D 0x89 0x52 0x23 0xD2 0xBC 0xDD 0xEA 0xA3 0xB9 0x1F my @key = qw( 125 137 82 35 210 188 221 234 163 185 31 ); my $key    = pack "C*", @key; my $key_len = length $key; for (my $n=0; $n', $file) || die; print $kcp $enc; close($kcp); chmod(0600, $file); } my $pass = "YourFrontrowPassword"; my $enc = kcpassword_xor($pass); write_pass($enc); exit 0;
 * 1) !/usr/bin/perl
 * 2) Gavin Brock (http://www.brock-family.org/gavin/perl/kcpassword.html) - June 2007


 * 1) Store the script, change the password in the $pass variable, and run the script.
 * 2) Upload the kcpassword file to the frontrow home directory using scp kcpasswd frontrow@AppleTV.local
 * 3) Log in to the Apple TV: ssh frontrow@AppleTV.local
 * 4) Backup the old kcpassword file: sudo cp /etc/kcpassword ~/kcpassword-orig
 * 5) Set the permissions: sudo chown root:wheel kcpassword; sudo chmod 600 kcpassword
 * 6) Move the file to the new location: sudo cp ~/kcpassword /etc/kcpassword</tt>
 * 7) Reboot: /sbin/reboot</tt>

Unix Tools
I did most of the installations using the script in download files, as I found that installers in the GUI (e.g. in Software Menu) often did not work.

my PATH variable was set to /usr/bin:/bin by default. I wanted it to be /usr/bin:/bin:/sbin:/sbin. I created a file /etc/profile</tt> with content PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/libexec:/System/Library/CoreServices; export PATH

NitoTV
Download NitoTV installer for AppleTV and follow the instructions. (unzip nitoTVInstaller_tt.zip, upload nitoTV.pkg and installme files, and run installme as root).

nitoTV use Mounted Disk
In order to have nitoTV > Files go to the mounted disk (e.g. /mnt/Donald) instead of /Users/frontrow/Movies), set the following preference, and reboot the Apple TV:

defaults write com.apple.frontrow.appliance.nitoTV startAtFolder /Users/frontrow/Movies/Donald

Note: the following may also affect this; please try yourself.

defaults read com.apple.frontrow.appliance.nitoTV mountLocation /Users/frontrow/Movies/Donald

Run Mplayer manually
If your remote is lost or broken, you can manually start mplayer using the following command:

/System/Library/CoreServices/Finder.app/Contents/PlugIns/nitoTV.frappliance/Contents/Resources/mplayer -fs \ /Users/frontrow/Movies/Donald/Series/Comedy/MyFavouriteShow.avi

OpenAL.framework
I found that nitoTV requires OpenAL.framework. When playing some movies, nitoTV attempts to install OpenAL by itself, but this fails, so I installed OpenAL.framework manually.


 * 1) Download MacOSXUpdCombo10.4.9Intel.dmg from Apple
 * 2) mkdir OpenAL; cd OpenAL
 * 3) Extract the OpenAL.framework: pax -z -f /Volumes/Mac\ OS\ X\ 10.4.9\ Combined\ Update\ \(Intel\)/MacOSXUpdCombo10.4.9Intel.pkg/Contents/Archive.pax.gz -r  "./System/Library/Frameworks/OpenAL.framework"</tt>
 * 4) Now copy /System/Library/Frameworks/OpenAL.framework to the AppleTV.

Perian
Perian is a collection of codecs for the QuickTime, the default movie player on the AppleTV.

If you installed NitoTV, you can go to nitoTV > Settings > Install Software > Install Perian If you have not installed nitoTV, you will have to do this manually. Perian and Flip4Mac contain a large number of codecs, which enhances the QuickTime player to play many more movie formats.

I simply copied the files Perian.component</tt>, AC3MovieImport.component</tt>, Flip4Mac WMV Import.component</tt> and A52Codec.component</tt> to /Library/Audio/Plug-Ins/Components/</tt> (A52Codec) or /Library/Quicktime/</tt> (the other codecs).

Unfortunately, Perian does not seem to work as I hoped. Even after installation, I get the error "The selected video could not be played. The format was not recognized." when I want to play MPEG-1 muxed files. I am able to play AVI files though. My solution is to use the Mplayer build into nitoTV, an open source alternative for the QuickTime player.

ATVFiles
You need to download ATVFiles-1.2.0.run, copy to the AppleTV and run it as root. That's all.

Mount Remote Disk on AppleTV
There are multiple SMB (CIFS) clients for OS X. Two choises are sharity light and mount_smb, which is the client build-in to Mac OS X (but not in the AppleTV). Sharity Light is easier, but does not work with encrypted passwords.

Install Sharity Light
I use Sharity Light to mount a LaCie disk over SMB, as I found this was more stable than mounting over AFP or using the Mac OS native mount_smb.

Download a binary of Sharity Light and unpack it: openssl base64 -d -in shlight.base64 -out shlight.zip unzip shlight.zip % copy slight to the AppleTV cp shlight /usr/sbin/shlight

Alternatively, download the source code of sharity light from http://www.obdev.at/products/sharity-light/download.html and compile with the following parameters in the Makefile</tt>: ARCH = -arch i386 CFLAGS = -Wall -O4 -DBSD4_4_LITE2 -isysroot /Developer/SDKs/MacOSX10.4.sdk -mmacosx-version- min=10.4 THE_CC = cc RPC_WARNFLAGS = -Wno-unused -Wno-switch -Wno-uninitialized

Install Mount_smb
pax -r -z -f /Volumes/Mac\ OS\ X\ 10.4.9\ Combined\ Update\ \(Intel\)/MacOSXUpdCombo10.4.9Intel.pkg/Contents/Archive.pax.gz \ './System/Library/Extensions/smbfs.kext' \ './sbin/mount_smbfs' chown -R root:wheel /System/Library/Extensions/smbfs.kext /sbin/mount_smbfs chmod u+s a+x /sbin/mount_smbfs sudo /sbin/turbo_kext_enabler.bin sudo kextload /System/Library/Extensions/smbfs.kext
 * Download MacOSXUpdCombo10.4.9Intel.dmg
 * Extract the system extension and mount application:
 * copy smbfs.kext and mount_smbfs to the AppleTV (note that smbfs.kext is a folder, not a file)
 * Set the permissions (this is particularly important to smbfs.kext):
 * chown root:wheel /sbin/turbo_kext_enabler.bin ; chmod a+x /sbin/turbo_kext_enabler.bin
 * Download turbo_kext_enabler.bin and copy to /sbin/</tt> on your AppleTV.
 * Run turbo_kext_enabler.bin:
 * Load the smbfs.kext extension:

Startup Script
Than create a mount point and startup script (my server is called Donald, you will have to replace that with the name of your server in the following examples):

mkdir /Users/frontrow/Movies/Donald chown frontrow /Users/frontrow/Movies/Donald

Create a file /Library/StartupItems/MountShares/MountShares:

. /etc/rc.common StartService { # for sharity light: /usr/sbin/shlight "//Donald/movies" /Users/frontrow/Movies/Donald -U username -P password # for mount_smb: /sbin/turbo_kext_enabler.bin kextload /System/Library/Extensions/smbfs.kext mount_smbfs "//<Username>:<Password>@donald.example.com/movies" /Users/frontrow/Movies/Donald } StopService { for id in `ps awx | grep shlight | awk '{print $1}'` do        kill $id done } RestartService { StopService; StartService } RunService "$1"
 * 1) !/bin/sh
 * 1) The start subroutine
 * 1) The stop subroutine
 * 1) The restart subroutine

chmod a+x /Library/StartupItems/MountShares/MountShares

and create a file /Library/StartupItems/MountShares/StartupParameters.plist:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd"> <plist version="0.9"> Description Mount Shares OrderPreference Late Provides Network Shares Uses Network Requires Network

Play DVR-MS files
MPlayer by default is able to play DVR-MS files. However, they do not show up in the file browser. You need to add "dvr-ms" to the list of shown suffixes:

defaults write com.apple.frontrow.appliance.nitotv suffixes -array-add "dvr-ms"

Photo Slide Show
There are multiple options to view a slide show of photo's on the Apple TV, but all have their disadvantages:
 * The built-in Apple TV browser looks best, but requires your photo's to be synced with iTunes. It is not possible to just play all photos in a given folder (all photo's are in a very peculiar folder hierarchy in /mnt/Media/Photos)
 * NitoTV works, but is extremely picky on the file format, and often stops working for me. Also, it requires you to mark each folder as a "photo folder" (nitoTV does so by creating a hidden and empty file, ".nitophoto", in the folder). Do not use the playlist option in nitoTV, I found that this only works for music, not for video or photos (it tries to "play" the images in the background)
 * ATVFiles works, but has a 2 second delay between photos where it shortly returns to the menu, also the interface is kind of slow.
 * It is possible to create a short movie yourself of images. This takes some work.

Normally, while browsing folders, neither nitoTV nor ATVFiles will show photos. To have them show up, add the jpg and png extensions to the list of recognized file formates.

defaults write com.apple.frontrow.appliance.nitotv suffixes -array-add "jpg" "png"

defaults write net.ericiii.ATVFiles VideoExtensions -array m4v 3gp m3u pls divx xvid avi mov wmv asx asf ogm mpg mpeg mp4 mkv avc flv dv fli m2v ts jpg png

(Note: I am not sure if doing this for nitoTV will have any affect on it's built-in slide show capability)

So far, neither option really did the trick for me.

EyeTV
There are different options to play EyeTV recorded content on an AppleTV
 * Install EyeTV on your AppleTV and have them streamed from a shared library within EyeTV.
 * Convert the files in EyeTV on your Mac, and submit them to iTunes.
 * Copy them to the AppleTV and play them with MPlayer.
 * Put them on a disk and have them streamed, for example with UPnP media streaming.

In the end, I decided that the easiest solution for me was to put them on a network disk, have the network disk mount on the AppleTV, and play them with MPlayer. This requires no conversion and no (instable) browsing and playing using a UPnP client.

If you want to try a different option, see EyeTV and Frontrow and EyeTV and TwonkyMedia

Eliminate Black Borders around Video
Some recording have black borders on all four sides, so they only occupy a small portion of the TV screen. This is likely caused by TV series which are recorded in 16:9 aspect ration (breedbeeld), but are transmitted by TV channels in 4:3 aspect ratio, with black borders on the top and bottom. This is recorded like that on your computer. If these recording are played on the AppleTV, they are recognized as 4:3 aspect ratio recording and MPlayer will add a black border on the left and right.

Of course, this sucks.

While QuickTime can often recognize the black borders on top and bottom, and scales up the video, MPlayer does not yet have support for this. It is worked in progress though, so you may want to check if it is supported one way or the other (look for the feature called panscan, panning and scanning).

It is possible to tell Mplayer to zoom in, using the panscan parameter:

mplayer -fs -ontop -panscan 0.5 movie.avi

Unfortunately, since we don't know beforehand how much to zoom in (we don't know if it is a 4:3 or 16:9 aspect ration), so we need to configure this per movie. The easiest solution, lacking auto recognition, is to allow zoom-in and zoom-out on the fly.

My solution was to map the - and + keys (which are normally used to change the sound volume) to zoon-out and zoom-in of the video. I simply set the sound volume with my TV remote control instead of the AppleTV remote control. See AppleTV MPlayer keymap how to change the key mapping of the remote control keys with MPlayer.

Springboard servers
There are many possible tools, extensions and add-ons to install on an Apple TV. Some of this software allows you to add even more extensions and third party software.


 * OpenSSH: An open source SSH (secure shell) daemon. OpenSSH is also installed on Mac OS X. You can compile OpenSSH yourself or copy it from Mac OS X.
 * Dropbear SSH: Another open source SSH daemon. You can compile Dropbear yourself or use atvusb-creator.
 * Unix tools: Some often used binaries. You can compile these utilities yourself, copy the binaries from Mac OS X or use atvusb-creator. As an alternative, you can use Busybox, which is a minimal set of Unix tools.
 * Perian: A free, open source QuickTime component that adds native support for many popular video formats. It is a must for every Apple TV, and adds support for MPEG 1, MPEG 2, DivX and more.
 * ATVFiles: A browser for the Apple TV file system. For example, you can browse to movie files and play them, without relying on the iTunes synchronization.
 * SoftwareMenu: A plug-in manager for Apple TV 2.0 and higher. It allows you to download plugins and scripts. SoftwareMenu is a prolongation of the earlier iScripts.
 * nitoTV: A front end for the popular mplayer media player.
 * XBMC: XBMC is a Media Center for Linux, Mac OS X, Windows and XBox. It allows you to play a variety of different media formats, and has a custom interface.
 * Boxee: Boxee is a fork of XBMC with support for media provides and social networks, such as YouTube, Flickr, PicassaWeb, MySpaceTV, etc.
 * ATV Loader: (also known by it's name awkwardtv.frappliance) is a plug-in manager that allows installation of other plug-ins from the Apple TV GUI (instead of manually downloading and copying). Unfortunately, it does only support Apple TV 1.x, not the current Apple TV 2.x (Take2) OS. Use SoftwareMenu for Apple TV 2.0 and higher.

Further plug-ins can be found at http://plugins.awkwardtv.org/. The AwkwardTV wiki also keeps a list of plug-ins that are surely compatible with Apple TV 2.0 (though not necessarily the latest version 2.x).

Interesting plug-ins are Sapphire (Browser for movies and TV shows), MediaCloud (UPnP streaming client), Couch Surfer (webbrowser), Applications Menu (Application Launcher), and Weather (weather reports).

My experience so far: CouchServer was buggy (viewing webpages crashed my Apple TV), Sapphire was no big addition to the Apple TV native GUI to me. I was not able to install NitoTV and ATVFiles using Software Menu, so in the end I deleted Software Menu.