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

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:

Text can be rendered onscreen using TrueType fonts.
Images can be rendered onscreen. Animated GIF is supported.
MP3 files can be played for the user and programmatically controlled (pause, fast-forward, rewind).
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

Laying out and animating the screen
Communicating with the TiVo box
Receiving events from the TiVo box
HmeEvent and subclasses:
Controlling media

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:


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:

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:

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 \ 
661ms: Registered 

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 \ \ 

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 

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:

    1. From TiVo Central, go to Music, Photos, & More.
    2. Select Enable Home Network Applications...
    3. Press THUMBS UP three times, then press ENTER to enable local HME applications.
    4. Return to TiVo Central, then Music, Photos, & More. The option should now appear as Disable Home Network Applications...
    5. 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.