Custom Tidbyt Apps

I’ve had my Tidbyt for almost a year now, and generally speaking I really like it. But one of its biggest gaps (in my opinion) is the lack of support for custom apps. Tidbyt apps are relatively easy to write, (they’re written in Starlark, a dialect of Python). They also have a directory of Community Apps which anyone can contribute to. However, if you just want to build a silly custom app that you have no intention of sharing, (or you just can’t imagine other people getting use out of it), then your options are fairly limited. You can render a WebP image from a Starlark source file and push it to your device, but if you want it to continuously update there’s not much you can do. This is unfortunate, because I was trying to build a custom countdown clock for my daughter based entirely on an inside joke, (her favorite musician is Nick Rattigan, and one of her friends called him “rat man” at some point and it stuck). So when we recently got tickets to Adjacent Fest in Atlantic City (where he was playing), I decided to create a modified version of the Countdown Clock app with an image I cobbled together of a rat with a man, counting down to the days left before the concert. I ended up solving this problem by writing a script to generate the WebP image, pushing it to my device, and triggering it to run every 90 seconds by a LaunchD job on one of my Mac mini servers. Since I’m also passing the -i option along with an installation ID to pixlet push, it also shows up in the Tidbyt mobile app, as seen below.

Rat Man Tidbyt App Screenshot

Here’s how I did it:

Tidbyt App Source

load("", "render")
load("", "time")
load("", "schema")
load("", "math")
load("encoding/", "base64")
load("encoding/", "json")

RAT_MAN_ICON = base64.decode("""

def main(config):
    timezone = config.get("timezone") or "America/New_York"
    now =

    DEFAULT_TIME ="2006-01-02T15:04:05Z07:00")

    future = time.parse_time(config.str("event_time", DEFAULT_TIME))
    dateDiff = future -
    days = math.floor(dateDiff.hours / 24)
    hours = math.floor(dateDiff.hours - days * 24)
    minutes = math.floor(dateDiff.minutes - (days * 24 * 60 + hours * 60))

    fadeList = []  # The list of the fading text near the bottom, or a static date if the event has passed
    dayString = "IS HERE!"  # The amount of days left, or a static message if the event has passed

    if ( < future):
        # Create the lists that will make the fading text
        dayString = "{} {}".format(str(days), "day" if days == 1 else "days")
        fadeList = appendFadeList(fadeList, "{} {}".format(str(hours), "hr" if hours == 1 else "hrs"), 30)
        fadeList = appendFadeList(fadeList, "{} {}".format(str(minutes), "min" if minutes == 1 else "mins"), 20)
        # Event date has already passed, so show the date of the event
        fadeList.append(render.Text(future.format("01-02-2006"), font = "CG-pixel-4x5-mono", color = "#888888"))

    # Create event text widget based on text length
    eventText = config.str("event", "Event")

    if len(eventText) < 14:
        eventWidget = render.Text(content = eventText, font = "5x8", color = "#21631a")
        eventWidget = render.Marquee(
            child = render.Text(content = eventText, font = "5x8", color = "#21631a"),
            width = 64,

    return render.Root(
        delay = 100,
        child = render.Box(
                children = [
                        expanded = True,
                        main_align = "center",
                        cross_align = "center",
                        children = [
                            # render.Text(content = dayString, font = "5x8"),
                            render.Text(content = dayString, font = "tb-8"),
                            render.Box(width = 64, height = 1),
                                children = fadeList,

# Create an fading animation
def appendFadeList(fadeList, text, cycles):
    for x in range(0, 10, 2):
        c = "#" + str(x) + str(x) + str(x) + str(x) + str(x) + str(x)
        fadeList.append(render.Text(text, font = "CG-pixel-4x5-mono", color = c))
    for x in range(cycles):
        fadeList.append(render.Text(text, font = "CG-pixel-4x5-mono", color = "#888888"))
    for x in range(8, 0, -2):
        c = "#" + str(x) + str(x) + str(x) + str(x) + str(x) + str(x)
        fadeList.append(render.Text(text, font = "CG-pixel-4x5-mono", color = c))
    return fadeList

def get_schema():
    return schema.Schema(
        version = "1",
        fields = [
                id = "event",
                name = "Event",
                desc = "The event text to display.",
                icon = "cog",
                id = "event_time",
                name = "Event Time",
                desc = "The time of the event.",
                icon = "cog",

LaunchD plist Source

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">

Shell Script Source


/opt/homebrew/bin/pixlet render event="Rat Man" event_time="2023-05-27T12:00:00Z"
/opt/homebrew/bin/pixlet push --installation-id RatManClock confidently-realistic-replete-alewife-bb3 rat_man.webp

Now I have an automatically updated, custom Tidbyt app without having to publish it as a community app. :)

Rat Man In Action

The source code and instructions are available on my GitHub profile. It should go without saying that this will work on other platforms besides macOS, (e.g., with a cron job), but I was just trying to get something working. Hope this helps!

comments powered by Disqus