Skip to main content

Inside TiVo's new Java SDK

Posted by hansmuller on February 1, 2005 at 3:09 PM PST

On Monday, TiVo announced a Java SDK called the Home Media Engine
(HME) and a corresponding simulation tool, all for writing PC
applications that target their digital recorder box. The announcement
has been heralded in many forums, notably


, the New York Times, EWeek, Yahoo News, etc. You'd be hard pressed
to discover the fact that TiVo's new SDK is a set of Java APIs and a
new J2SE-based tool in most of the coverage, so naturally I'll try to
fill that embarrassing lacuna here.

The TiVo SDK and simulator tool run on
J2SE 1.4.2 or 1.5 and they're available for free on

now. The documentation appears to be comprehensive enough and there
are enough examples to kick-start development. Plus the source code
for the entire SDK is provided. The only thing lacking for yours
truly is a TiVo box at home to really complete the experience. Sadly,
that will have to wait.

Fortunately one can obtain a reasonable TiVo developer experience
facsimile by running applications against the simulator
(check out a

screenshot here

). Just for the record, I wasn't able to run the samples "right out
of the box" on my Java Desktop System laptop due to some confusion about
the IP address for my machine's ethernet port. The symptom was
a "". The fix was to
lookup the eth0 address using ifconfig and pass that
as well as a port number to the sample app on the command line:

> /sbin/ifconfig eth0 | fgrep "inet addr"
    inet addr:  Bcast:  Mask:
> java -cp simulator.jar:samples/samples.jar
       com.tivo.hme.sim.Simulator com.tivo.hme.samples.hello.HelloWorld
       -i "" -port 7288


developer forum

on was helpful for sorting this little snafu out.

What may be becoming clear from all of this is that TiVO HME
applications are actually servers that the TiVo box or the simulator
tool discover and connect to. You don't download applications into
the box, the application or application service running on your PC
sends commands to the box and receives events, roughly like an X11
client would. Unlike an X11 client, an HME service includes a factory
that generates a new instance of your application for each TiVo box
that connects to it. This aspect of the HME SDK will not be much of a
concern while you're prototyping an app for the TiVo box in your
living room. If you wanted to turn your creation into a service for
all, then you'd have to think carefully about the sorts of scaling
issues that application server folks worry about.

The HME SDK is a small API. It makes it possible for an app
running on your PC to map data from the internet to a visualization
that's appropriate for your TV. HME applications
build hierarchies of translucent rectangular View objects where each
View contains one image, text, or color resource. A View corresponds
to the essence of a GUI component, it just defines a 2D coordinate
system and a clip rectangle. There's an HME Application class which
defines a root view and you override its init() method to add your own
views to that, e.g.:

public class MyApplication extends Application {
    protected void init(Context context) {
        View v1 = new View(this.root, 0, 100, this.width, 100);
        View v2 = new View(this.root, 0, 200, this.width, 200);

        Resource text = createText("default-36.ttf", Color.white, "Hello"));

        ImageIcon icon = new ImageIcon("myImageFile.png");
        Resource image = createImage(icon.getImage());

In this example the Resource createXXX methods create text and image
resources on the TiVo box synchronously. It's also possible to stream
images resources from an arbitrary URI to the box. At the moment there's no
support for streaming or playing videos, an unusual limitation for a
TV device. There's no way to gain access to the TiVo's archive of
recorded material either; of course this is only an "early access"
release of the SDK.

Event dispatching is a similarly no-frills affair. The TiVo box sends
events for everything from the TV keyboard and remote control to
progress reports per downloading a streamed resource, back to the
application. The application can deal with them by overriding an
Application method called handleEvent().

One novel feature of the HME SDK is support for animation. Some of the
methods that set View properties take an extra string argument that
specifies how to animate the transition from the properties current
value to the new one. For example to "fade in" a View over
a period of 500 milliseconds one could write:

myView.setTransparency(1.0f); // initially transparent
myView.setTransparency(0.0f, "*500");  // 500ms, linear ramp

One can animate changes in a View's bounds, origin, scale, and
transparency. One can also specify a second animation parameter
(also part of the string) that defines how fast the
animation accelerates and decelerates to/from the linear ramp.

I suspect that's enough of an introduction to this new SDK.
I didn't cover the support for loading/streaming audio clips
however it was nice to see that the TiVo folks picked up the
JLayerME MP3 decoder (featured in the

Swing Sightings column

back in April 2002) from
JavaZoom, see

for the latest information about that.

Related Topics >>