Home Gallery FAQ Download SDK Sourceforge
1. Introduction
2. Development
3. Troubleshooting
1. Introduction
What is HME?

HME is TiVo's powerful new open platform for applications that are displayed and controlled by broadband-connected TiVo Series2 DVRs. HME applications are written using the Java programming language and can run on home PCs or remote servers hosted by TiVo. HME applications cannot control any of the TiVo DVR's scheduling, recording, or video playback capabilities.

Developers use the HME software developer kit (SDK) to create these applications. The SDK is released under the Common Public License (CPL).

Does HME work with all TiVo DVRs?

To use HME your TiVo DVR must be:
  • A TiVo HD, Series 3 or Series2 DVR (not supported on DirecTV or Series 1 DVR).
  • Connected to your home network.
  • Running TiVo service update 7.2-X or higher.
What about the screenshots in the gallery?

The screenshots in the gallery represent what is possible with the HME SDK today. They are taken from various developer projects and the samples included in the SDK.

I'm a developer. How do I get started?

Great! Download the SDK and start with the README and the HME SDK Developer's Guide.

What can I do with HME?

The HME SDK can be used to create great looking applications that display on TV and interact with the user through the TiVo remote control. You can also stream mp3 files to the TiVo DVR for playback.

I have more questions...

Use our mailing list, tivohme-developer@lists.sourceforge.net. You can also join the list yourself.

Who are you?

The HME SDK was released by TiVo in early 2005 based on technology acquired from Strangeberry in early 2004. This page is maintained by Bob Poniatowski.

2. Development
How can I distribute my application to other developers?

The easiest way to distribute your application is to make the JAR file available for download. You can also use Java Web Start or build an installer around the JAR file.

Will we be able to host our own HME application servers?

YES. In the future, end users will be able to access 3rd party applications over the internet. One example of this is www.apps.tv. TiVo will also host applications on our servers, and users will be able to access applications running on a local network.

I have developed a cool application. Can I put it in the gallery?

Yes. Please send mail to our mailing list at tivohme-developer@lists.sourceforge.net and let us know how we can run your application.

How do I create an application with a TiVo look-and-feel?

Check out the Bananas UI Toolkit, which makes it easier for you to create applications that have a familiar TiVo-like interface

Can I download video to the DVR?
The HME SDK does not support video streaming or direct downloading of video to the DVR. It is however possible to use HME to interface to and control TiVoToGo content. For a good example of this visit galleon.sourceforge.net.

Can HME applications play video?
Can HME applications pop up over Live TV?
Can HME applications schedule recordings?
Can HME applications use multiframe video as a background?

Not at this time. The HME SDK does not support controlling the DVR features of the recorder or playing back video today.

How do I get the percent complete on a ResourceStream?

public boolean handleEvent(HmeEvent event) {
    if (event instanceof HmeEvent.ResourceInfo) {
        System.out.println(getPercent((HmeEvent.ResourceInfo)event));
    }
    ...
}

float getPercent(HmeEvent.ResourceInfo event) {
    String pos = (String) event.map.get("pos");
    if (pos != null) {
        int slash = pos.indexOf('/');
        long off = Long.parseLong(pos.substring(0, slash));
        long len = Long.parseLong(pos.substring(slash + 1));
        return (float)off / (float)len;
    }
    return 0;
}

Please clarify the need to remove resources. Is there any kind of garbage collection at work on the TiVo DVR, or will a resource remain until I explicitly remove it (or my app exits)? It appears to be removed automatically if it's garbage collected on the server, is that correct?

Yes. 100% correct. You can remove a resource manually if you want and that sometimes helps if you are doing something like a photo viewer, where the resources are potentially huge. Otherwise you're depending on the Java GC to remove them, which may or may not be timely enough. Applications that use many resources for short periods of time are good candidates for explicitly disposing of resources.

To dispose of a resource, use the remove method: com.tivo.hme.sdk.Resource.remove()

Does the TiVo DVR cleanup all resources when the application is closed?

YES. The TiVo DVR will dispose of and remove all resources when an application is closed or the connection is dropped.

What are the limitations of the graphics hardware in a TiVo Box?

HME uses the graphics hardware to render basic HME objects, and here's how it breaks down:
  • Alpha 1 surface: for color resources.
  • Alpha 2 surface: for text.
  • RGB565 surface for all opaque images
  • ARGB32 surface for all images with transparent pixels
There's no 8-bit support right now. The hardware has the following limitations:
  • a maximum of 8 surfaces can be used per scanline
  • a maximum of 4 surfaces can contribute to any pixel (3 on some hardware)
  • a maximum of depth of 128 bits is allowed (56 on some hardware)
These constraints should be observed in order for the screen to be drawn correctly. You can tell what regions of the screen are being rendered in software by invoking the CLR CLR ThumbsUp backdoor whenever you're running an HME app. It will display plain rectangles for all surfaces that are be rendered entirely by the hardware, and it will show actual bits for the regions that are being rendered in software.

3. Troubleshooting
My application appears in Music, Photos, & More, but the icon doesn't draw and the application doesn't run.

The HME connection is being blocked by Windows Firewall or some other networking snafu. The application is discovered but the TiVo DVR can't connect back to your PC.

If you are running Windows XP SP2, try adding a firewall exception for HME. See Understanding Windows Firewall for more details.

My application isn't showing up in Music, Photos, & More!

Follow this simple checklist:
  1. You can connect to your application with the Simulator.
  2. You are using a Series2 DVR.
  3. The DVR is connected to your home network.
  4. You are running software release 7.1-x or higher (see the System Information screen).
  5. TiVo Central shows "Music, Photos, & More".
Still not showing up? The TiVo DVR uses multicast DNS to find HME applications that are running nearby on your home network. If the DVR and the application bind to different network interfaces, the DVR will not be able to discover the application. This can happen if you use multiple network interfaces on your development PC, or if you use a VPN.

Use the -i argument to force your HME application to bind to a specific network interface. See the SDK for more information.

The Simulator isn't discovering my application, but I can connect to it directly.

See the previous question.

My application doesn't display anything.

This is usually caused by one of these issues:
  • Your application is throwing an exception somewhere inside init(). You may have better luck running with -d on the command line.
  • You called setPainting(false) somewhere and forgot to call setPainting(true). In general, setPainting calls should come in pairs and use try ... finally.
  • You forgot to make the view visible?
When in doubt, try looking at the view hierarchy in the Simulator.

My application throws an exception when the user navigates to another screen on the TiVo DVR.

When an application is closed you may see this exception or one similar:

java.net.SocketException: Socket closed
        at java.net.SocketOutputStream.socketWrite(SocketOutputStream.java:99)
        at java.net.SocketOutputStream.write(SocketOutputStream.java:136)
        at com.tivo.hme.io.FastOutputStream.flushBuffer(FastOutputStream.java:311)
        ...

Your stack trace may differ but it is probably the same issue. These exceptions are harmless and can be ignored. This is something we are cleaning up for a future release.

When I run the HME sample applications the SDK throws a java.net.BindException.

You probably have multiple network interfaces, and the Listener does not know which address to bind to. Try using the -i argument to the Factory to specify the IP address of the network interface you wish to bind to. You can edit the runsample.sh that comes with the SDK. Here is an example:

java -cp ../hme.jar:samples.jar com.tivo.hme.host.sample.Main -launcher launcher.txt -i <ip-address-of-your-intf-here>



Questions? Feedback? Use our mailing list, tivohme-developer@lists.sourceforge.net
Please DO NOT contact TiVo Customer Support with questions about HME. They will be unable to help you in any way.
©2003-2005 TiVo Inc. TiVo and the TiVo logo are registered trademarks of TiVo Inc.