Roku platform notes

Roku is different from every other connected TV platform in one fundamental way: you do not write web apps. There is no browser engine, no HTML, no CSS, no JavaScript. Roku apps (called “channels”) are built with BrightScript (a scripting language unique to Roku) and SceneGraph (an XML-based UI framework). This makes Roku development a distinct discipline, even for teams with deep experience on other TV platforms.

Runtime environment

Roku OS is a custom Linux-based operating system. Channels run in a sandboxed environment with limited access to system resources. The key components:

BrightScript is the programming language. It is dynamically typed, has a syntax that feels somewhat like BASIC, and runs in a single-threaded interpreter. If you are coming from JavaScript or Python, the concepts transfer but the syntax takes getting used to.

SceneGraph is the UI framework. You define UI nodes in XML and control their behavior with BrightScript. SceneGraph provides built-in components for common TV UI patterns: grids, lists, poster displays, keyboards, and dialog boxes.

Render thread and task thread: SceneGraph separates rendering from data fetching. The render thread handles UI updates and must not be blocked. Data fetching, API calls, and other I/O operations happen in Task nodes that run on separate threads. Communication between tasks and the render thread happens through field observation, where you observe changes to a node field and the callback fires on the appropriate thread.

This threading model is a common source of confusion. If you try to make a network request on the render thread, it blocks the UI. If you try to update UI nodes directly from a task thread, you get errors. Understanding the boundary between these threads is essential.

Channel architecture

A well-structured Roku channel typically follows this pattern:

Scene graph: a root Scene component that manages top-level navigation and hosts child components for each screen (home, browse, detail, player, settings).

Screen components: each screen is a SceneGraph component with its own layout, data bindings, and key handling. Navigation between screens is managed by the parent Scene, usually through a stack-based approach.

Content nodes: ContentNode is Roku’s data model for content metadata. You populate ContentNode trees with your catalog data and bind them to UI components. The binding system is straightforward but rigid: ContentNode fields are predefined, and extending them requires custom fields.

Task nodes: all network operations, parsing, and data transformation happen in Task nodes. Each Task runs asynchronously and communicates results back via field observation. Structure your tasks to be reusable and independently testable.

Playback on Roku

Roku’s Video node handles media playback. You set the content URL, DRM configuration, and playback properties on the Video node, and Roku’s system player handles the rest.

Format support: HLS and DASH are both supported. Roku’s player handles ABR switching, buffer management, and basic trick play internally. You configure it through node fields rather than imperative API calls.

DRM: Widevine and PlayReady are supported, depending on the Roku device model. Configuration happens through DRM parameters on the Video node. Testing DRM on multiple Roku hardware generations is important because older devices may have different security levels.

Ad insertion: Roku provides the RAF (Roku Advertising Framework) for ad integration. If your channel runs ads, RAF is the expected approach and is part of Roku’s certification requirements for ad-supported channels.

Playback callbacks: the Video node fires state change events (buffering, playing, paused, error, finished) that your channel observes to update UI, log analytics, and handle errors. Response time to these events matters: if your error handler takes too long, the viewer sees an unresponsive screen.

Performance constraints

Roku devices range from entry-level sticks with 512 MB of RAM to high-end streaming players with 2 GB. Your channel needs to work on the low end.

Memory: the Roku OS enforces memory limits per channel. Exceeding the limit crashes the channel. The limit varies by device but is typically in the 100-200 MB range for the channel itself. This is tight. Large image caches, deep ContentNode trees, and unoptimized BrightScript data structures can push you over the limit quickly.

Image management: poster art is one of the biggest memory consumers. Use Roku’s built-in image caching (it handles texture memory management) and resize images to the display resolution rather than loading full-resolution artwork.

BrightScript performance: the interpreter is not fast. Complex data transformations, large string operations, and deeply nested loops can cause visible UI sluggishness. Profile with Roku’s built-in performance tools and move heavy computation into Task nodes so it does not block the render thread.

Channel startup: Roku measures channel startup time and displays a system loading screen while your channel initializes. Minimize the work done before showing the first usable screen. Defer non-critical initialization.

Certification and submission

Roku’s channel store review checks for:

• Correct deep linking implementation (Roku’s deep linking protocol must work)
• Proper use of the RAF framework if ads are shown
• No crashes or hangs during standard user flows
• Accessibility: screen reader support through Roku’s built-in accessibility framework
• Content compliance with Roku’s content policies
• Correct channel manifest configuration

Common rejection reasons: deep linking failures (the channel cannot navigate to a specific piece of content from a Roku search result), unhandled error states (network failure shows a blank screen instead of a message), and accessibility violations.

Submit early in your release cycle to account for review times and potential rejection-resubmission cycles. Roku review typically takes 2-5 business days.