Chapter 1: Overview

What is HME?

The TiVo® Home Media Engine (HME) is a powerful platform for building digital media applications with a user interface that appears on the TiVo box. HME makes it possible to create attractive applications with alpha-blended graphics, smooth animations, and anti-aliased text. You can quickly build applications such as

Music players
Photo viewers
Games
News, stock, and weather reports
Streaming radio
Messaging

and much more.

HME Protocol

The HME protocol enables third parties to write applications that display on the TiVo box. The protocol runs over a single TCP/IP connection initiated by the TiVo box. The protocol is latency-tolerant and bandwidth-efficient, features that enable it to provide an excellent user experience in the face of challenging network conditions.

An HME application functions as a server that accepts connections from TiVo boxes, which act as clients. The TiVo box runs the HME Receiver, which receives commands from an HME application.

The HME Software Development Kit (SDK) enables you to create HME applications in Java®. (The HME Protocol itself is independent of the language implementation.) As shown in Figure 1-1, the application uses HME to send commands to the TiVo box to lay out the screen and control media. The TiVo box sends events back to the application whenever a button is pressed on the TiVo remote control.

The SDK assigns object identifiers (IDs) to each view and resource. Most commands and events operate on a view or resource, referenced by ID. You can inspect these IDs by enabling debug output in the SDK (see the options for Main in Chapter 2 and the description of the Simulator in Chapter 3).

Figure 1-1.

HME communication model

Supported Media File Formats

HME applications can display images and play sounds in the following file formats:

Format	Usage
TrueType®	Text can be rendered onscreen using TrueType fonts.
GIF PNG JPEG	Images can be rendered onscreen. Animated GIF is supported.
MP3	MP3 files can be played for the user and programmatically controlled (pause, fast-forward, rewind).
MPEG	Single-frame only.
PCM sound	PCM sound can be used for short sound effects in your application. (8,000 Hz signed 16-bit little endian mono PCM)

HME Software Development Kit (SDK)

The HME Software Development Kit (SDK) contains the HME Java classes, documentation, tools, and samples to help you get started.

HME Java Classes

The HME Java classes are contained in hme.jar. These classes are the heart of the SDK, and you will become very familiar with them while building your application. Table 1-1 lists the major HME SDK classes.

Table 1-1 Major HME SDK Classes

Task	HME SDK Class
Laying out and animating the screen	HmeObject Application View Resource
Communicating with the TiVo box	Factory
Receiving events from the TiVo box	HmeEvent and subclasses:   ApplicationInfo   DeviceInfo   FontInfo   Idle   Key   ResourceInfo
Controlling media	StreamResource

Hosting Interfaces

The SDK ships with a sample hosting environment that provides services to the application (see Chapter 2). The hosting interfaces include the following:

IContext - provides methods for storing persistent data, for communicating with the HME infrastructure, and for creating an application log (see ILogger).
IHmeConstants - defines constants for use by the HME application
ILogger - allows the application to write messages to a centralized log
IArgumentList - A helper class that encapsulates command line arguments and provides useful functions on them.

Samples

The SDK includes samples that illustrate various aspects of HME. Reading through these samples is the quickest way to get started building applications. The samples include:

animate – animated boxes moving around the screen
clock – a ticking clock
effects – all the basic HME animation effects at once
fontinfo – obtaining and using font metrics
fractal – an interactive fractal viewer
hello – the classic “Hello, world!”
music – a basic MP3 player
pictures – a slideshow viewer
rss – headline news from an RSS feed
skullbones – a game for two players : try to get four in a row!
tictactoe – the classic game of Xs and Os
videobackground – illustrates an important rendering optimization
weather – the current weather from an XML feed

To run the samples, use the runsamples scripts in the SDK. Follow the “Getting Started” instructions to see the samples on the TiVo box.

About This Guide

This version of the guide contains a new Chapter 4, “Programming Techniques,” which provides performance tips as well as a detailed walk-through of three sample programs. The guide also now has an index and is available in both PDF and HTML formats.

This document is intended for use by experienced Java developers. The reader should be familiar with the Java programming language, setting the classpath, and running Java applications from the command line.

Related Documentation

The following documents, included in the HME SDK release, are also useful references for SDK developers:

HME Protocol describes the on-the-wire format for all HME commands and events.
Tech Notes deal with specialized programming tasks, typically of an advanced nature. Examples include the Video Backgrounds Tech Note, which describes how to add a video background (a single-frame MPEG clip) to your application, and the Music Playback Tech Note, which provides detailed information on how to work with MP3 audio files.
HME SDK Release Notes detail important changes and bug fixes in this release.

Getting Started

This section describes how to start the HelloWorld sample program.

System Requirements

HME requires JDK 1.4.1 or later and is known to work on Windows XP, Linux, and Mac OS X (10.3). Make sure that the correct version of Java is installed by running:

> java –version 
... 

Run HelloWorld in the Simulator

Note: The following command line examples use a colon for the classpath separator. On Windows systems, use a semicolon instead.

From the top level of the unbundled SDK, run HelloWorld in the HME Simulator as follows:

java –cp simulator.jar:samples/samples.jar \ 
     com.tivo.hme.sim.Simulator \ 
     com.tivo.hme.samples.hello.HelloWorld 
661ms: Registered http://10.0.0.16:7288/hello/ 
... 

This will launch the Simulator and point it at the HelloWorld application. The Simulator window will appear with the words "Hello, world!" in the center.

Run HelloWorld Standalone

It is also possible to run an application standalone and connect to it with the Simulator afterward. To do this use the sample host environment. To run HelloWorld standalone using the sample hosting environment, issue this command from the top level of the unbundled SDK:

java -cp hme-host-sample.jar:samples/sample.jar \ 
   com.tivo.hme.host.sample.Main \ 
   com.tivo.hme.samples.hello.HelloWorld 

The hosting environment will print out the URI to which you can connect to run the application in the Simulator. Copy and paste the application URI to the command line of a separate shell to run the Simulator:

> java -jar simulator.jar http://10.0.0.16:7288/hello/ 
   RUN: http://10.0.0.16:7288/hello/ 
... 

Run Local HME Applications on the TiVo Box

Now that HelloWorld is running, you can see it on the TiVo box: Follow these steps to enable local HME applications:

From TiVo Central®, go to Music, Photos, & More.
Select Enable Home Network Applications...
Press THUMBS UP three times, then press ENTER to enable local HME applications.
Return to TiVo Central, then Music, Photos, & More. The option should now appear as Disable Home Network Applications...
HelloWorld should be visible in the list. Select HelloWorld, and it will appear onscreen. If the application is not listed, check your network to be sure that your TiVo box and your PC are running the HME application on the same subnet.