Arturo Cuya

Join the weekly newsletter

Not a subscriber?

Every week I'll send you cutting edge advice and actionable tips about modern Roku development. State-of-the-art knowledge that you won't find anywhere else — For free.

March 5, 2024 | 5 min read

Get Pixel Perfect Designs in Roku Every Time: A Step-by-Step Guide

By Arturo Cuya

@arturo__cuya

Roku development can be notoriously slow. A simple one-line modification, followed by the app reload and navigation back to the necessary screen, can consume up to thirty seconds of valuable time.

Achieving an implementation that’s pixel-perfect presents an even greater challenge: Having a physical device separated from your screen complicates things, to the point where I’ve found myself using my ol’ 12in school ruler to check for alignment.

We were in the dark ages and we didn’t know it.

Fortunately, nowadays, we Modern Roku Developers can do things differently. Let me show you how to get pixel-perfect implementations in three simple steps, without even reloading the app.

Step 1: Use a Video Capture Device

There is an underrated piece of tech that is an absolute game-changer for us Roku developers. This device is called a Video Capture Card, and it allows connecting our Roku devices to a computer by simulating that we’re connecting it to a TV’s HDMI port.

These devices have become very popular in the gaming community in the last decade because they allow streamers to record the output of their gaming consoles. That means they have become crazy expensive to support 4K outputs at 200fps.

But you don’t need to be so fancy. A full HD, 60fps card is good enough for your endeavors. And those come at around $16.

You can show the output of the Video Capture device on your computer using a media player that supports it: I recommend QuickTime Player for Mac and OBS for Windows/Linux.

Portable laptop + Roku Stick + Video Capture Device = Work while sipping pina coladas at the beach.

I use Linux (btw) so I’ll give you quick instructions on how to implement these steps with OBS:

  1. Download OBS here: https://obsproject.com/download
  2. Connect the USB side of your Video Capture Device to your computer.
  3. Connect your Roku device to the HDMI port of your Video Capture Device.
  4. Open OBS and in the Sources panel select Add Source > Video Capture Device > Ok.
  5. Select the right device. Your webcam might appear in the options too.
  6. Choose the right video format until you see that the output from the Roku changes in real time when you use the remote.

Step 2: Use software to superpose an image

The technique we’ll use to compare design vs. implementation is to superpose an image over our app and reduce the opacity of the target layout so that we can easily spot the differences.

Export the design to an image file and download it to your computer. I recommend you export an image of the full screen instead of a piece of it. Then you’ll need to import it into your media player software and put it on top of the Roku device output with half of the opacity.

To do this in OBS:

  1. Go again to Sources and select Add Source > Image > Ok.
  2. Select Browse and find your image file in the file explorer.
  3. Right-click your image source and select Filters then click the plus sign and select Chroma Key.
  4. Use the slider to reduce the opacity to at least 50% and then click Close.

Tip: You could also add a Color Correction filter to add even more contrast between your image and the app.

Step 3: Use SceneGraph Inspector to match the alignments

The last source of friction in our iterative process is to try different values for sizes and dimensions until our implementation fits with the design. We can solve this problem and try out different values without reloading the app by using the SceneGraph Inspector tool.

This feature is available in the Run & Debug panel, under the SceneGraph Inspector section. If you have never used it before, follow the steps that appear in the same section to set it up.

This tool allows you to inspect the node tree of your app and change the translation field of your nodes in real time. You can also change most other values like text for a Label or width/height for a Rectangle. There are some values that can’t be changed in runtime though, like the animation style of a RowList.

Bonus step: When everything else fails…

Our current setup should allow us to quickly iterate between values to match our design with pixel-perfect precision. However, even in the Roku world, the phrase “It works on my machine” ¯\_(ツ)_/¯ applies.

It is possible that when you share your application, someone finds that there’s still a couple of pixels of misalignment between the design and your implementation.

This is usually because you forgot (or were unaware of) the Rule of Three:

Position and dimension values are downscaled by dividing them by three. Decimal values are not allowed, and will be floored to the nearest integer.

This means that if you have a nice 1px wide separator component that was designed for an FHD (1920x1080) screen, when someone else sees it on an HD (1280x720) screen, the Roku OS will downscale it by dividing the value by three. The new width of the separator will be 0.3px. But since decimal values are not allowed, this will be rounded to 0px, resulting in an annoyed reviewer wondering why you forgot to include the separator.

And of course, it means that your position values can suddenly lose 1px when downscaled too. So beware of the Rule of Three and explain to your team this behavior when encountered.

Tip: If you want to programmatically adjust dimensions depending on the current screen resolution, you can use roDeviceInfo’s GetUIResolution

In Summary

  • Utilize a Video Capture Device to connect your Roku to a computer.
  • Use software to superimpose an image for precise design comparison.
  • Leverage SceneGraph Inspector for real-time alignment adjustments.
  • Remember the Rule of Three for consistent scaling across devices.

Remember, the key to success lies in meticulous attention to detail and the efficient use of available resources.

Happy coding!


Some other ways I can help you:

1. Course: A Modern Introduction to Roku Development (Coming April 2024)

For absolute beginners, this course is meant to set you in the right path to make use of modern tools and best practices from day one. Subscribe to the newsletter to get notified when it's available.

2. Open Source tools to boost your productivity:

Use these tools to 10x your workflows. Free and open source forever.

  • create-roku-app: A CLI tool to quickly scaffold Roku apps using the best practices.
  • SceneGraph Flex: A flexbox component for Roku Scenegraph applications.
  • Roku Animate: Define complex Roku Scenegraph animations in one line of code.