Inside TiVo's new Java SDK

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 slashdot , 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 http://tivohme.sourceforge.net 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 "java.net.MalformedURLException". 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:129.145.161.189  Bcast:129.145.161.255  Mask:255.255.254.0
> java -cp simulator.jar:samples/samples.jar
       com.tivo.hme.sim.Simulator com.tivo.hme.samples.hello.HelloWorld
       -i "129.145.161.189" -port 7288

TiVo's developer forum on sourceforge.net 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"));
        v1.setResource(text);

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

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 http://www.javazoom.net/javalayer/javalayerme.html for the latest information about that.