AppleTV 3.0 and remote control navigation

Getting it on your AppleTV

To support AppleTV in your custom iTunes LP there are a few things you need to take care of. The first of which is to tell iTunes that your iTunes LP is compatible with AppleTV 3.0. To do so you need to provide a manifest.xml file with a list detailing compatible versions:

<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns="http://apple.com/itunes/media_archive/manifest" version="1.0" media_archive_version="2.0">
	<requirements>
		<supported_platforms>
			<platform name="iTunes" minimum_version="9.0"/>
			<platform name="AppleTV" minimum_version="3.0"/>
		</supported_platforms>
	</requirements>
</manifest>

This will tell iTunes that this iTunes LP is compatible with any version of iTunes later than 9.0 and any version of AppleTV later than 3.0. As soon as you've added this requirements section to your manifest.xml iTunes should be able to sync your iTunes LP to the AppleTV.

Controlling iTunes LPs with the remote

The AppleTV OS converts clicks on the Apple remote to keyboard events. These events are mapped to regular keypressed such as UP, DOWN, LEFT, RIGHT, ENTER and BACKSPACE. To control your iTunes LP on the AppleTV you need to listen for these keypress events and handle all navigation accordingly.

There are a few things you have to take into account though.

• When displaying an iTunes LP on an AppleTV you shouldn't show "back" buttons, because the Apple remote has a dedicated button for that.
• Besides keyboard navigation you also need to provide mouse navigation, which can be a bit tricky.
• When a user clicks "back" this will exit out of the iTunes LP if you don't handle those keypresses properly. When the user is at the home screen the back button should be handled as normal, however in any other case we have to prevent the AppleTV to handle the event normally.

First you should set up a handler that listens to keypresses somewhere in your initialization code. In this case I'm assuming an initialization function which already exists will call the setupKeyListener() function:

var KEY_LEFT = 37;
var KEY_UP = 38;
var KEY_RIGHT = 39;
var KEY_DOWN = 40;

var KEY_BACK = 8;
var KEY_BACK2 = 27; // This BACK2 is added because when testing with the keyboard pressing escape for back sometimes feels more logical than pressing backspace.
var KEY_ENTER = 13;

var isInSubMenu = false;

function onKeyDown()
{
	switch (event.keyCode) {
		case KEY_BACK:
		case KEY_BACK2:
			// If we are not inside a submenu the default action for the back-button should happen, which will exit the application.
			if (!isInSubMenu) return;
			
			// Otherwise navigate out of our current submenu
			. . .
			
			break;
		case KEY_DOWN:
			// Move the current selection down
			. . .
			
			break;
		case KEY_LEFT:
			// Move the current selection left
			. . .
		
			break;
		case KEY_RIGHT:
			// Move the current selection right
			. . .
			
			break;
		case KEY_UP:
			// Move the current selection up
			. . .
			
			break;
		case KEY_ENTER:
			// Select the current highlighted item. If this is a submenu this action should set isInSubMenu to true.
			. . .
			
			break;
	}
	
	event.stopPropagation();
	event.preventDefault();
}

function setupKeyListener()
{
	window.addEventListener("keydown", onKeyDown, true);
}

You'll notice a lack of code inside the various case statements. This is because this for a great deal depends on how your navigation actually looks. The iTunes Emulator project will also have a toolkit library in the future which will abstract this kind of complexity for you. Just tell it which navigation elements you have on screen, and it will handle everything else. However I'm afraid that there is no planned release-date for this toolkit yet.

Audio feedback

Usually when navigating on an AppleTV you will get audio feedback when a selection-highlight moves, or when you have reached a navigation boundary and you cannot go any further in that direction. iTunes LPs on AppleTV allow you to trigger those same familiar sounds when navigation occurs. To trigger these sounds we can use the window.iTunes.getSystemSounds() function:

var IS_APPLETV = ((window.iTunes !== undefined) && (window.iTunes.platform == 'AppleTV'));
var APPLETV_SOUNDS = IS_APPLETV ? window.iTunes.getSystemSounds() : null;

// The sound that you hear when you select an item by clicking "play"
var SOUND_SELECT = IS_APPLETV ? APPLETV_SOUNDS.SystemSoundSelect : null;

// When you use the remote cursors to move your selection succesfully
var SOUND_SCROLLSTART = IS_APPLETV ? APPLETV_SOUNDS.SystemSoundScrollStart : null;

// When you try to move your selection but you've reached a navigation edge, or have reached the end of a scrolling list
var SOUND_SCROLLLIMIT = IS_APPLETV ? APPLETV_SOUNDS.SystemSoundScrollLimit : null;

// When you use the "menu" button to back out of a submenu
var SOUND_EXIT = IS_APPLETV ? APPLETV_SOUNDS.SystemSoundExit : null;

function playNavigationSound(aSound)
{
	if (IS_APPLETV) {
		APPLETV_SOUNDS.playSystemSound(aSound);
	}
}

These system sounds are only available in this form on the AppleTV. You can see that for this reason we specifically check for window.iTunes.platform to see if we're running the iTunes LP on AppleTV. We also do the same check inside the playNavigationSound function. This way you can trigger those sounds from anywhere when they are appropriate, and not have to worry about having to check for the correct platform in each location. Playing these sounds is not required, but does serve to better integrate the iTunes LP with the AppleTV experience.

Examples

For a good example of how such a thing might work, check out the iTunes LP from Justin Bianco - Kingdom Crumble which uses some of the methods described in this tutorial. As mentioned before, also check out the iTunes Emulator project, to which a toolkit to ease this kind of development will be added soon.