Mark Ethan Trostler


TiVo::HME::Application - Perl implementation of TiVo's HME protocol See


  use TiVo::HME::Application;
  our @ISA(TiVo::HME::Application);

  sub init {
    my($self, $context) = @_;

    my $mpg =  $T_RESOURCE->image_file('examples/myloop.jpg');

    sub handle_event {
        my($self, $resource, $key_action, $key_code, $key_rawcode) = @_;
        print "You pressed the $key_code key on the remote!\n";


    Perl on your TiVo in 11 Steps!!

    Step 1: Go to
    Step 2: Go to Step 1
    Step 3: Go to Step 2 (seriously)
    Step 4: Congratulations on making it here!
    Step 5: Really, go to, download the
        SDK, read the PDF files (don't worry about the protocol PDF,
        that's what this is for).
    Step 6: Learn about Views & Resources
    Step 7: Learn about the Application cycle (init then event loop)
    Step 8: Learn about Events
    Step 9: Learn how the Perl stuff differs from the Java stuff
        (mainly only in naming)
    Step 10: View & understand the perl examples - especially how they
        related to the Java examples (they do the same thing!).
    Step 11: Use your imagination to create a kick-arse Perl-based HME app!!

Start the Server

    First you must start up the HTTP daemon - your TiVo (or Simulator) wants 
    to connect to us at port 7288 if you're curious.
    The '' script start ups the Server & waits for a connection from
    a TiVo or simulator.
    When one comes it, the URL is pulled off & is taked for the name of
    the app.
    SO after starting the server, in the Simulator you type in:
    http://localhost/myapp & hit return.
    The Perl HME stuff will now try to find a module named ''.
    Obviously needs to be in @INC - so your start script should
    'use lib qw(...)' to point to where your TiVo HME app lives.

Write your App

    Your TiVo HME app should subclass TiVo::HME::Application.

    use TiVo::HME::Application;
    our @ISA = qw(TiVo::HME::Application);

    The entry point to your app is the 'init' function call.  Hopefully
    by now it's starting to sound similar to mod_perl.
    You get a reference to $self & $context as the parameters.
    We'll talk about contexts laters as you most likely don't need
    anything from that object.
    In $self you stash thing that you want to persist beyond the init
    call.  Mostly that'll be Views, Resources, & Application state.


    Views are containers for Resources.  A View has exactly 1 parent view and
    any number of childen views.
    Views have stuff like bounds, scale, translation, and transparency.
    They can be visible or not, they can be painted on or not.
    And they can have exactly 1 Resource.

Creating a new View

    my $view = TiVo::HME::View->new(
        x => MIN_X_VALUE,
        y => MIN_Y_VALUE,
        width => MAX_WIDTH,
        height => MAX_HEIGHT,
        visible => [ 0 | 1 ],
        [ parent => $parent_view ]

    x, y, width, height are the bounding rectangle of the view.  
    Anything drawn outside of that box will be clipped.
    If you do not specify the parent it will be set to the root view.
    There are accessor methods for each of the view's properties.

    You MUST 'add' the View after you create it!!


The Root View

    There is 1 Root view whose bounds are the entire screen (640x480).
    This view is INVISIBLE by default.  Mostly like you will want to
    make it visible as soon as your done adding resources if not sooner:


Manipulating Views

    See the sourceforge page for details about what this stuff means.

Adding the View


Set the View's Resource

    $view->set_resource(<resource>, [ flags ]);
    <resource> is the resource - see below
    [ flags ] if present is OR'ed together flags from
        set to HALIGN_LEFT by default


    $self->visible([ 0 | 1], [animation]);


    $self->bounds(x, y, width, heigth, [animation]);


    $self->scale(scale_x, scale_y, [animation]);
    scale_x & scale_y are floats


    $self->translate(t_x, t_y, [animation]);
    Translate origin


    $self->transparency(transparency, [animation]);
    0 = opaque
    1 = transparent


    $self->painting([ 0 | 1], [animation]);
    Set painting


    Remove view


    There are 9 Resources:

        True Type Font

    See for details about what these
        are & how they are used.

Image Resource

    my $img = $T_RESOURCE->image_file(<filename>);
    Can be a PNG, JPEG, or MPEG file (for setting video backgrounds)

Sound Resource

    my $sound = $T_RESOURCE->sound_file(<filename>);
    Has to be a 8-bit PCM file

Font Resource

    my $font = $T_RESOURCE->font(<name>, <point size>, <style>);
    Where <name> is 'system' or 'default'
    <point size> is a float (have no idea why)
    <style> is $T_CONST->FONT_PLAIN

TTF Resource

    my $ttf_font = $T_RESOURCE->ttf_file(<filename>);
    Pass a TTF file

Color Resource

    my $color = $T_RESOURCE->color(<red>, <green>, <blue>, <alpha>
    All values are 0-255
    Alpha = 255 = opaque
    Alpha = 0 = transparent

Text Resource

    my $text = $T_RESOURCE->text(<font>, <color>, <string>);
    Where <font> is a font or TTF resource,
    color is a color resource & string is yer string

Stream Resource

    my $stream = $T_RESOURCE->stream(<url>, <content-type>, <play>);
    <url> points to a streamable resource
    <content-type> is the content type hint
    <play> = 1 = play
    <play> = 0 = pause

Manipulating Resources

    Again see the sourceforge page for what these mean

Make active

    $resource->active([ 0 | 1 ]);
    Make a resource active or not

Set position


Sets the position at which the resource is played back. Resources which are playing are immediately repositioned. Resources which are not yet started will begin playing at this position.

Set speed

    $resource->set_speed([ 0 .. 1 ]);





Send Event

    Only key events are supported (HME limitation not mine)
    $resource->send_event(<target>, <animation>, <data>);
    <target> currently can only be 1
    <animation> is an animation resource
    <data> is see 'make_key_event'

Make Key Event

    $self->make_key_event(<target>, <action>, <code>, <rawcode>);
    <target> can only be 1
    <action> is $T_CONST->KEY_PRESS
    <code> is a key code - look in for all of 'em
    <rawcode> is whatever the heck you want it to be

Default resources

    All of the default resources (sounds) are available in the
        @TiVo::HME::DEFAULT_RESOURCES array indexed by the
        constants ID_BONK_SOUND etc... - see




Exporting is Bad. Bad. Bad. Bad. And Yet this modules exports 3 symbols. That's how important they are. You will use them many times in your app & will thank me someday. Really.

$T_RESOURCE is a handle to 'TiVo::HME::Resource' $T_VIEW is a handle to 'TiVo::HME::View' $T_CONST is a handle to 'TiVo::HME::CONST'

You really don't want to be writing:

my $r = TiVo::HME::Resource->color(222. 32, 20, 0xff);

when you can just write

my $r = $T_RESOURCE->color(222. 32, 20, 0xff);

Or for constants:

my $bonk = TiVo::HME::CONST->ID_BONK_SOUND;


my $bonk = $T_CONST->ID_BONK_SOUND;

Isn't that worth Exporting??



Mark Ethan Trostler, <>


Copyright 2005 by Mark Ethan Trostler

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.