noob's guide to Boxee/XBMC on AppleTV

[Zoom]

Just got my AppleTV yesterday and I'm now up and running with Boxee and XBMC. However, it wasn't easy, largely because I had to search all over these forums for answers to my questions when I encountered problems. So I was hoping to collect what I learned into a single forum post. I realize that this will probably become outdated and I can't promise to maintain it. But it should be good for AppleTV 2.3 and ATV UBS Creator 1.0.b10 at least. I apologize for the length. (Just found this video review - nice info if you're on the fence about doing this, check it out.)

I tried to separate this into two parts: the instructions, and then the comments.

There are lots of simple how-to lists, but they gloss over a lot of details that I found important and if you hit a problem, then you're in trouble. I found the step by step list at Wired most helpful. My biggest complaint is that there isn't a single wiki-like page that is a) up to date and b) tells you how to recognize when things go wrong and finally c) how to handle common problems. There's a ton of info spread all over these forums. We need a single place to gather all the latest info and wisdom in ONE PLACE.

The high level steps are:
A) Get an Apple TV, set it up and update it
B) Make a patchstick
C) Install the stuff and update it

STEP A: set up AppleTV

Obviously you need an Apple TV. But I haven't seen anyone mention tips on setting it up for optimal patching. I would:

* Use HDMI, not component.
* Keep the resolution set to default (480) till you're done.

See next post for more info, but basically this should help you read the patcher logs, which turns out to be important.

Once installed and running, you should update it to the latest firmware (2.3). If it's higher than that, then this post is probably out of date.

STEP B: create patchstick

Download the ATV USB Creator utility here. Again, these comments are for 1.0.b10.

You don't need to download the Boxee/XBMC image. Don't click "Choose a DMG" even. It's not obvious, but you don't need to do anything with this - it will download what it needs. All the other default settings are fine, just leave them alone. All you need to do is plug in a USB drive (and unplug ALL OTHERS), format it with Disk Utility and hit "Create using". This video helps a lot (though it's already out of date):

I've seen different size requirements, but I was able to use a 512GB stick. Well, the creator app said it worked, anyway, though this drive didn't work on the actual patching.

STEP C: install patches

Now... even though the USB Creator says that it succeeded, that doesn't mean that it'll work. I had to go through 3 drives before one worked, even though the creator thing said they were all successfully completed and the files on the drive all looked right. Worse yet, I couldn't even tell that they failed. I followed the patcher instructions, rebooted, saw the penguin, saw logs, rebooted again.... but there was no change to my AppleTV menus (despite some multiple Apple logo flashes and longer boot-up). The key here was seeing the very last patcher log giving you the SSH login credentials ("frontrow" for both user ID and password). If you don't see that, then it wasn't successful. This video helps give you some idea how to do all this and what it looks like, but again, mine looked just like this and failed.

Note that the only log I saw indicating failure was "patchstick failed", somewhere in the middle of my patching logs. This was on my first USB drive (SanDisk Cruzer min 512MB). The second drive (Kingston 4GB) wasn't even recognized. The third one (SanDisk Cruzer Micro 2GB) worked.

When you reboot and see the new menus, then you know it worked for sure. Now you can set your AppleTV screen resolution to 720 or 1080 if you want.

I think the first thing you're supposed to do at this point is go to the "update" submenu on the Boxee/XBMC menu and update everything. Someone below said that you should update the launcher first. After that, I'm not sure.

Final notes

It's not obvious from what I've read, but my understanding is that XBMC and Boxee are largely redundant. Boxee is based on XBMC. They do many of the same things. My guess is that you'll find one you like and not use the other. If you choose XBMC, search LifeHacker for some interesting tips on XBMC (latest called "Altantis"), including installing other skins. I've been using XBMC for a long time now, so it's what I'm used to. But my guess is that I'll end up using Boxee, once I learn my way around - it has some really cool features that I'm anxious to try.

Finally, another tidbit: I had to tweak a lot of the video settings in XBMC for it to look right. It doesn't seem to be able to figure out my screen's resolution, so "auto" mode didn't work. And I had to scale the default skin by 4% I think to make it fit okay, and I'm still seeing some weird distortion on some screens - no clue why.

So. That was my experience. Hope yours goes more smoothly.

See the next post for some things I'd like to see improved, and some specific issues I had to deal with.

[Zoom]

Now some comments on this process. Guys, I love what you've done here. I now have a kick-butt replacement to my old hacked Xbox with XBMC! That's very, very cool and I'm extremely grateful! So take these comments in the spirit they're given: to improve the tools and to make this process dead simple for any person. The bigger the community, the better!

1) The USB Creator.

The UI could really use some changes. It's just not intuitive. Under Installation Options, the first menu has nothing in it, so should be removed. The second pull down has only one option, so why bother? And the third pull down I don't even understand... check boxes on a pull down menu, with a check box next to that? I have no clue even how to work with that. A simple list (not pull down) with check boxes would be fine. Better yet, if 90% of the people will never change any of this stuff, hide it in a "advanced" settings pane.

The "download or" and "Choose a DMG" thing is really confusing. Most people will never use this, I'm guessing, but it looks like you need to select something here. I kept choosing my downloaded Boxee image file, which the app tried to use and then hung. Will anyone ever need to choose a dmg? If not, just remove it; if so, put it on some other "advanced" settings window.

PLEASE list the user-friendly volume name for the target USB device. And please warn the user if the USB device is anything larger than 2-4GB. It should be labeled "select USB drive", with a "refresh list" button (the circling arrows button isn't intuitive). Also, you should tell the user the minimum size of the drive somewhere on this window, or warn them if it's too small. Maybe listing the size of the drive next to the name in the pull down list would help, too.

I would put a big button at the bottom labeled "Go" or "Create" or something, not "creating using->" with a pull down next to it. Have the settings options, then a single, big, shiny action button to start the process.

I'm not sure why some USB drives work and others don't, but in my experience, you can't tell from the output of this utility. Can you help us out and check this? I tried 3 drives, all of which appeared to work just fine, till I tried to patch from them. If you can verify this with the app first, it would save a lot of trouble.

2) The patching scripts

I have two complaints here. First, at high resolution, I couldn't read the logs, and many of them were off the screen to the left and bottom. You might try padding the beginning of each line with spaces or something.

But the real complaint is that it's not at all obvious if it succeeded or failed. And when it fails, there are no clues as to why it fails. I would like to see a big banner-style report at the end of the script saying "SUCCEEDED!" or "FAILED" with error codes, reasons, and things to try. It wouldn't hurt to also tell people what to do next.

3) Debugging: when things go wrong

It would be nice to have a utility app for your Mac to grab all the patcher logs, zip them up and send them to tech support. If ssh was enabled, then this should be pretty easy, given the AppleTV's IP address. Is there a way for the patcher itself to push some logs to a networked Mac, in case SSH enabling fails? Maybe you could do this in the patch creator - remember the IP address of the Mac that created the patcher and push some logs to it....

wait... how about this? Have the USB creator (or some other) utility remain running while you patch the AppleTV, and let the patcher script talk to the utility on your Mac over the network. It could upload logs, error codes, etc - and the app could confirm for you that the patching worked or not, and if not, help you figure out why (or at least upload the error report to you guys). And it might be helpful to have an app on your Mac to poke into the AppleTV, too.

4) Other factors.

I realize there are lots of permutations on TVs, receivers, cables, etc, but I think one thing lacking from all the install advice is stuff about common setup tips: using HDMI vs component, XBMC resolution settings, AppleTV settings, using a receiver vs straight to TV, etc. Maybe this is what the forums are for, but if there are any truly general tips and tricks for basic setup of the hardware, I'd like to see them in one place.

For instance, I immediately set my AppleTV to 1080i. I was using component cables at the time, so 1080p wasn't an option. This made reading the patcher logs nigh impossible (too small). And I had lots of trouble with distortion of XBMC screens and auto-resolution and all that. Maybe it's my Onkyo receiver trying to convert component to HDMI. Maybe it's my Samsung DLP. Or maybe it's both. Dunno. But HDMI works a lot better, and leaving the resolution low really helped read the patcher logs.


My original posts are chronicled here, for what that's worth.


UPDATE: another request

5) Comfort and security

I saw a lot of posts referring to 'factory refresh', but I didn't see anywhere that explained actually how to do this. This, I think, is crucial. A lot of people will read these forums and think 'wow... some people really had a lot of trouble... what if I permanently screw up my new AppleTV?' - and then they'll just walk away. There needs to be a safety net, with clear instructions. Something that says 'hey, don't sweat it - worst case, you can always get back to ground zero, with some work' and then carefully, clearly explain what that work is. Also, people may want to know how to do this if they need to take their ATV in for repairs - hide their tracks.

And along those same lines, I would like someone to clearly lay out what you need to do when things are updated. What if a new rev of Apple TV comes out? Will it auto-install and mess me up? If I install it, and I back-rev? Will my Boxee/XBMC info be lost? Can I back up that info somehow, just in case?

These are going to be serious concerns for any new user. I want to know:

a) how likely will it be that I'll brick my AppleTV?
b) can I restore it to factory-fresh condition, and if so, how?
c) how do I deal with AppleTV firmware updates?
d) can I make a backup of my modded AppleTV, in case something gets messed up later?
e) what if I need to take my ATV in for service?

[marcel]

Hi Zoom

welcome to boxee

read both your posts and what can i say i believe you summed up alot of issues we need to clear up/clarify for the future..regarding your great description in the first post i will use as a reference for new users (if you do not mind)..regarding the issue of which which update should you do first ..it's the launcher..

[Zoom]

Thanks, marcel! Sure, feel free to reference it, at least until it's out of date. I would really prefer to see all of this in a single web page somewhere, instead of even a sticky forum post. I've got friends of mine that will undoubtedly be interested in following my footsteps, and I'd like to send them a single link and say "here's all you need to know".

Keep up the great work! Can't wait to see where this product goes. I've been searching for a solution for a LONG time now, looking at Popcorn Hour, SageTV, XBMC, Moxi, Slingbox, etc. That's another post, but this AppleTV/Boxee solution looks pretty darn good. My big issue now is live TV. I desperately want to cut off my cable and avoid satellite - it's too expensive for what you get, their proprietary walled garden solutions are horrendous and limiting, and they just don't have enough competitive pressure to drive innovation and features. TiVo is slick, but also expensive, it's on TOP of cable, and still buggy (CableCARD and all that).

Anyway... I need IPTV. But for straight-up media stuff, I'm digging AppleTV with Boxee.

[MrHipster]

Zoom,
As a noob, I would like to nominate you for a Noobel Peace Prize (sorry for the bad, but well intentioned pun) for your extremely thorough tutorial, tips and suggestions. There are a lot of us out there who need more coaching in getting all of this together. We're all not wireheads. Great job on your cooperation with the developers.
I bought my ATV after I installed Boxee on my iMac, and cancelled by
sat subscription, as a result. So I really believe in this project, but still am in the dark about setting up all the functionality. Currently I'm waiting for the 15 Dec release, as the 4 Dec release was too buggy on my system.
Hopefully Boxee will attract more like you to back up the excellent work of the developers.
Too bad Steve Jobs doesn't donate a building to them, as ATV sales are going up because of Boxee.

[Zoom]

Glad that it helped!

I added another request in the second post, too.

[islanddreamer]

I'm reviving this old thread because it's the only one I could find that discusses the video settings available within boxee.

Has anyone created a checklist of the optimal video and appearance settings for the new beta on Apple TV?

Playback of streaming Flash content like Hulu is pretty dismal, but the settings do make a difference. By trial and error, I've settled on the following, which gives me maybe 10 frames per second.

I set the Apple TV's resolution to 480p.
Appearance settings/Screen Display blanking is off and Vertical blank sync is off.
Video settings/Player Render method is GLSL and Sync playback to display is off.

Any recommendations on what I should change?