1.0 Introduction: The Roku Channel Developer Program
There are two methods for distributing Roku channels through the Roku Developer Site after they have been uploaded: the Roku Channel Store for Public Channels, or as a Private Channel.
Roku Public Channels
Public Channels created for the Channel Store should be those intended for the widest possible distribution, without restriction other than as required for business reasons, such as payment of a monthly subscription. Public channels should be submitted to Roku for acceptance into the Channel Store. If accepted by Roku, a channel is made available through the Channel Store to all Roku users.
Roku Private Channels
A channel may be uploaded to the Roku Developer Site and made available to users through the Private Channel mechanism. These channels are not available through the Channel Store, but can be accessed by Roku users by means of a unique channel access code provided to users. Channels intended for a very narrow audience, or carrying restrictions on access, such as membership in a group or organization, are better suited for Private Channels. There is no Roku approval process necessary to publish a Private Channel.
1.1 Welcome to the Roku Streaming Player Developer Guide
This Developer Guide is designed to help you quickly come up to speed on the Roku platform architecture, Channel Store, and the basics of how to develop and deploy an application to the Roku player in development mode, and to the Channel Store as a published application to end users. In this Developer Guide we refer to the development of new channels on the Roku player as "applications" since they consist of a set of scripts and related assets. Channels can access video streams, music, photos, or perform other functions enabled by the SDK.
1.2 Developing with the Roku SDK
The Roku SDK consists of a set of documentation, design guidelines, and sample applications that enable channels to be developed for the Roku Streaming Player. To understand the Roku SDK, here are the key documents:
- The Developer Guide covers the architecture, programming language, development process, and channel deployment requirements.
- The BrightScript Reference Manual will bring you up to speed on the language and serves as a reference for the core components. BrightScript is the programming language used to develop channel applications on the Roku Streaming Player. BrightScript is a scripting language optimized to be the high level glue that ties together BrightScript Components and the Internet.
- The Component Reference guide describes the Roku Streaming Player platform components that expose APIs to BrightScript.
The entire documentation set includes the following:
|Developer Guide||An introduction to developing for the Roku platform (this manual)|
|BrightScript Language Reference||BrightScript programming language reference information|
|Component Reference||Reference information for the components exposed to the BrightScript programming language|
|BrightScript Debug Console||Usage information for the BrightScript Debug Console|
|Channel Packaging and Publishing||Information on creating a channel package and uploading it to the Developer Site|
|Design Guidelines||User Experience guidelines and standard art dimensions|
|Device Registration and Linking||Linking the Roku Streaming Player channel to an account on your site|
|BIF File Specification||How to support Trick Mode for your streams|
|Encoding Guide||Creating Roku compatible streams|
|Eclipse Plugin Guide||Installing and using the Brightscript programming language in the Eclipse IDE|
|External Control Guide||Information on the external control protocol that allows control of the Roku player over the network|
|Closed Caption Support||Information on adding closed captions to Roku player streams|
|Web Service API||Information on the web service APIs developers can use to connect to the Channel Store|
|Scene Graph XML Guide||A guide for developing applications using the Roku Scene Graph XML APIs|
|Scene Graph Reference||Reference material for the Roku Scene Graph XML APIs|
|Scene Graph XML Tutorial||A tutorial walk-through that builds an entire application using the Roku Scene Graph XML APIs|
|Release Notes||A list of the SDK changes for each Roku player firmware revision|
In addition to the documentation, the SDK includes a set of application code samples that demonstrate some of the BrightScript and Roku Platform programming techniques. You may reuse any of the code found in these samples as a basis for your own development, subject to the terms of the Roku SDK License. A brief description of these samples follows:
|simpleposter||Very simple poster screen with a filter banner|
|simplevideoplayer||Uses the |
|videoplayer||Complete video channel using category based XML feeds|
|audioapp||Uses the |
|monitorsetup||Example use of the |
|deviantart||Example use of the |
|register||Rendezvous style registration and account linking|
|twitterOAuth||Uses the |
|clock||A screensaver that uses |
|paragraph||Displays images on the |
|customvideoplayer||Uses the |
|usbplayer||Plays media files from the USB drive, demonstrating the use of USB, |
|simplegrid||A barebones grid screen example|
|usbgrid||Uses the grid screen to browse a USB file system|
|simpleinfo||Example of using the Info Button to pop up contextual information|
|simple2d||A simple bouncing ball implementation using the 2D graphics system and the |
|bs2dtest||Sample 2D graphics tests|
|metadata||Shows getting EXIF metadata from images and tag information from audio files, demonstrating |
|launchparams||Example of a channel that accepts parameters from ECP, demonstrating channels that respond to remote apps and clickable ads|
|scroll||Scroll a large image on the viewable screen|
|snake||A sample 2D graphics game|
|socket_tests||Simple example using |
|web_server||Example of using |
|simpleInChannelPurchase||Example of using the channel store purchase APIs|
|ecp_client||Java examples utilizing the ECP protocol to control the Roku: a simple |
|CaptionRenderer||Demonstrates the latest API capabilities for adding captions to videos|
|InAppPurchase||A simple test channel application that allows users to purchase items within the application|
|CustomPlaybackScreen||Demonstrates how to create a custom video player for your application using the |
|ImageCanvas||Creates a custom image canvas using the |
|Collisions||Demonstrates how to handle collisions between sprites in the 2D API |
|SimpleAnimatedSprite||Demonstrates how to create a single animated sprite using the 2D API|
|Snowflakes||Creates multiple layers and several animated sprites using the 2D API double-buffering, animator, and compositor capabilities|
|TicTacToe||Demonstrates the basic concepts of the 2D API by creating a simple Tic-Tac-Toe game|
|WebServices||Demonstrates the Web Services API by downloading and playing content from an example web page|
|BasicNavigation||Demonstrates how to create navigation menus|
|Localization||Demonstrates localization techniques for the Roku platform|
|ListScreen||Demonstrates new capabilities for displaying lists in the |
|JSONParsing||Demonstrates the new native JSON parsing capability of the Roku platform|
1.3 What Do I Need to Get Started?
Here's a list of the things you'll need to get started writing applications for the Roku Streaming Player:
- Roku Streaming Player with Software Release 2.7 or later
- Roku SDK (Development Kit Documentation and Sample Applications)
- Development Workstation with Text Editor and Terminal Application
- Standard Web Browser (Firefox, Internet Explorer or equivalent)
1.4 Roku Models and Features
With the release of the Roku 2 platform, Roku's product line has expanded to the point that there are significant capability differences between many of the models. While all the models have the same basic streaming video playback support, the hardware internals of the models will support different levels of game play. There is even a new SDK method,
SetMaxVideoDecodeResolution() (a member of
roVideoPlayer), that only has an effect on units with an OpenGL implementation. Please see the Component Reference for more details on this method.
The Roku models ship with incompatible power supplies as specified in the table below. If the wrong power supply is used, there is a risk of damaging the Roku unit when the power current of the supply is greater than what is specified for your Roku unit. On the other hand, if the power supply current is less than the Roku's specified power current, you run the risk of spontaneous reboots when the Roku cannot draw enough current.
When publishing your channel, you will have the opportunity to specify hardware requirements like "USB", "Roku 2", or "Bluetooth Game Remote". The tables below should help you in determining the target models for your channel.
|Roku LT||Roku 1||Roku 2|
Roku 2 HD
Roku 2 XD
Roku 2 XS
|Roku 3||Roku 4||Roku TV|
5 V 2.5A
5 V 2.5A
|12 V 1 A|
MIPS 400MHz 1
|ARM dual core|
ARM quad core
Accelerated Graphics API
OpenGL ES 2.0 2
OpenGL ES 2.0 2
OpenGL ES 2.0 2
|OpenGL ES 2.0 2||OpenGL ES 2.0 2||none|
|512 MB||512 MB||512 MB|
|512 MB||1.5 GB||512 MB|
NVM (Flash) Storage
|256 MB||256 MB||256 MB|
|256 MB||256 MB|
Composite Video Out
HDMI 720p Video Out
HDMI 1080p Video Out
|HDMI 2160p Video Out||no||no||no||no||no||no||no||no||yes||no|
Wi-Fi (n 2x2)
Supports Games < 750K
Supports Games > 750K
Bluetooth Game Remote 4
Wi-Fi Direct Game Remote
|Voice Remote Search||no||no||no||no||no||no||no||no||yes||no|
1 Roku LT "2400X" started with the same ARM chip as Roku 2 models, but transitioned to the MIPS chip with model "2450X"
2 The OpenGL ES 2.0 API is currently only available under NDA to selected premium development partners. Roku desires to more openly share these low level APIs. We are hard at work tackling the security issues with this sharing that will simultaneously give content owners good reason to trust the uncompromising security of the box.
3 TV display resolution
4 Bluetooth Game Remote supports motion control and the instant replay button. The IR remote does not. The APIs for the motion control are only available under NDA at this time.
Roku HD Classic
Roku XD|S Classic
|Roku XD|S||Roku HD|
5 V 1 A
5 V 1 A
5 V 1 A
5 V 2.5 A
|5 V 2.5 A||5 V 2.5 A|
Accelerated Graphics API
|256 MB||256 MB|
NVM (Flash) Storage
|256 MB||256 MB|
Composite Video Out
HDMI 720p Video Out
HDMI 1080p Video Out
Wi-Fi (n 2x2)
Supports Games < 750K
Supports Games > 750K
1.5 Roku 4 Streaming Media Player Considerations
Support is now included for the Roku 4 Streaming Media Player. This Roku Player features greatly enhanced video resolution output up to 2160p (ultra-high definition, or UHD). This Roku Player also allows the creation and use of user interfaces with 1080p (full high-definition, or FHD) resolution. The Roku 4 Streaming Media Player includes a much more powerful quad core ARM processor and decoding support for the HEVC (high-efficiency video code) codec to allow efficient streaming of 2160p video content.
1.5.1 Compatibility with Existing Channels
All existing channels and applications are fully compatible with the Roku 4 Player. Special considerations apply if you want to stream 2160p content as part of your channel or application, or if you want to create and use a 1080p user interface for your channel or application.
1.5.2 Supported Formats
The following are the audio and video formats, and DRM and security formats, supported by the Roku 4 Streaming Media Player.
|video codec||HEVC: main 10 profile, level 5.1 VP9: profile 0|
|color depth||8-bit, 10-bit (HEVC only)|
|bit rate||40 Mbps|
|streaming||DASH, HLS, Smooth|
|frame rates||24, 30, 60 fps (30 fps with VP9)|
|audio codecs||AAC (HE-AACv2 and AAC-LC) pass-through: Dolby Digital, Dolby Digital Plus|
1.5.3 UHD Video Content Streaming Support and Recommendations
The following are the SDK changes and additions to support 2160p video content streaming:
- roDeviceInfo GetVideoMode() method returns the string "2160p"
- roDeviceInfo CanDecodeVideo() method
- roDeviceInfo CanDecodeAudio() method
- roDeviceInfo GetDrmInfo() method
- roDeviceInfo GetDisplayProperties() method
- Content Meta-Data attribute DisableOutputResolutionSwitching
The following are the recommendations for streaming 2160p video content using the Roku 4 Streaming Media Player.
- Always provide AAC 2-channel stereo as an alternate audio to surround sound
- DASH is the preferred adaptive streaming format
- HEVC is the preferred video codec
- The recommended bit rates are 8, 10, 15, and 20Mbps
- The recommended adaptive streaming segment sizes are 2.5, 3.3, or 5 seconds
- It is recommended the segment sizes be constant and the same for all bit rates for the best adaptive switching and trick play (with 10 second BIF files)
- It is recommended to provide all recommended bit rates for FHD, HD, and SD in the same DASH stream
The following are the supported and recommended DASH encoding considerations.
- Supported Profiles
- ISO Base Media File Format only
- VOD only
- Supported video formats: AVC, HEVC
- Supported audio formats: AAC, EAC-3
- Audio and Video Representations are carried in separate AdaptationSets
- MPD must contain either AVC or HEVC, not both
- SegmentTemplate tag must be present in MPD or Segment Index box to be present in the MP4 file
- Segment Size and Alignment
- Duration in SegmentTemplate must be same as key frame interval
- When encoding a Segment Index box
- Roku recommends key frame interval of 10 seconds
- All Representations must be encoded with the same key frame interval
- If SegmentTemplate tag is encoded, all Representations of a certain component must use the same SegmentTemplate
All encoded segments must start with an IDR frame
SegmentTemplate must use segment number
- Only PlayReady encryption is supported
- Lowest and Highest Bitrates
- Roku recommends the user have at least a 1.5Mbps connection
- Some customers will have low bitrate connections around 1Mbps or experience intermittent network load that causes drops below Roku recommended network speeds
- Roku recommends encoding a low bitrate stream around 600Kbps
1.5.4 FHD User Interface Requirements and Recommendations
The following are the requirements and recommendations for creating and using a 1080p user interface for your channel or application.
To create and use a 1080p user interface in a channel or application, you must set up the manifest file as described in Manifest File.
The following are the graphic image sizes and formats for a 1080p user interface.
|Channel logo||540x405 pixels||JPEG|
|Splash screen||1920x1080 pixels||JPEG|
|Roku Search channel buttons|
|Roku Search brand tiles|
2.0 Development Environment Overview
2.1 Architectural Overview
Diagram: Architecture Block Diagram
The diagram above provides a high-level overview of the main system components for the Roku Streaming Player platform. Developer applications are written using the BrightScript programming language. These applications are designed to be standalone entities that can be deployed to a running system with minimal impact.
BrightScript applications are dynamically loaded at runtime and run within a unique context within the BrightScript virtual machine. They are "sand-boxed" and run protected from other areas of the system. Scripts only have access to platform resources that are exposed to the scripting layer as BrightScript components. Developers have a wide selection of built-in elements from the BrightScript programming language, plus additional platform components to build their applications. See the BrightScript Reference and the Component Reference for additional information.
2.2 User Interface Elements / Object Model
The Roku SDK uses the BrightScript programming language for development and exposes a set of interfaces to platform services through BrightScript Components. These platform SDK services include capabilities such as networking, video playback, user interface, and data management. The objects in the Roku SDK are divided into two primary areas:
- Core Objects – Fundamental objects that exist on all Roku platforms and are device independent
- Platform Objects – Objects unique to a specific platform, such as the Roku Streaming Player
Developing an application for the Roku Streaming Player consists of writing a BrightScript application, packaging the application and associated resource files and deploying it to the platform. During development packaging consists of a structured ZIP file. For final deployment, tools are provided to create a signed and encrypted application package. At runtime, the player will enumerate the installed applications and display them on the main menu. When the user selects the application, the script(s) are loaded and control is passed to your application. When the user exits, the script is halted and control is returned to the user interface "shell".
User interface functionality available in the SDK includes:
- Top-Level Menu (Launch screen for applications with logo art)
- Poster Screen (Horizontally scrolling list of shows with poster art)
- Springboard (Detail screen with options for displaying individual shows)
- Video Player Screen (Video playback support with progress bar and trick mode support)
- PIN Entry Screen (User entry of PIN for purchase/rental verification)
- Message/Error Dialog (Dialog for display of errors and other user messages)
- Filter Widget (Selection widget for filtering content display by type)
- Rendezvous/Code Registration Screen (Display/validate registration codes)
- Username/Password Registration Screen
- Text Screen ( Display formatted text to the user and allow selection of options)
- Search Screen (Keyword based search with progressive disclosure of results)
Detailed information on all these screens can be found in the Component Reference.
2.3 Display Modes (HD/SD)
The user interface has been designed to support both High Definition (HD) and Standard Definition (SD) displays. By default the streaming player starts in SD mode, but allows the user the option to specify their display preferences. Display preferences are handled globally for all applications by selecting the "display type" option in "settings".
There are three possible modes:
- 4:3 standard-definition (480i/p)
- 16:9 anamorphic widescreen (480i/p)
- HDTV (720p)
The SDK UI objects are SD/HD aware and will automatically display in the correct mode. In some cases, the HD mode will allow the user to see more data on the screen. The SD UI is rendered natively at 480p and the HD UI at 720p. As a developer, no special programming is required to support these display modes. Any artwork used by the application (movie posters, logos, etc.) should be provided in both HD and SD versions and included with the application or downloaded dynamically at runtime. The screen objects will attempt to scale improperly sized artwork, but this could result in a loss of quality or degrade performance. It is strongly recommended that developers provide original artwork in both resolutions.
2.4 Top-Level Menu
The top-level menu provides a launch point for all applications. Applications must provide HD and SD versions of the application icon artwork for display on the top-level menu. When an application is selected from the top-level menu, the application is loaded and control is transferred to the application. The user may return to the top level at any time by pressing the Home button. Pressing the Home button will always exit the application and unconditionally return control back to the UI application shell.
2.5 User Interaction / Events
Roku SDK UI objects provide an event oriented model for user interaction. Instead of receiving and directly handling all of the IR events received by the application, the UI elements will handle all navigation commands directly and send higher level events to the script as the focus changes or the user makes a selection. Scrolling, trick modes and screen-to-screen navigation is handled by the SDK UI objects and the script generally only needs to interact when there is a change in context or the user highlights or selects new data elements. Refer to the Event Loops section or the Class Interface sections for additional information.
The objects in the user interface framework expose a set of screen types which standardize user interaction and make it easy for developers to quickly write and deploy applications. Screen types enforce a user interaction model and ensure consistency between applications. They may be customized to provide a unique, developer specific look-and-feel. Customization is currently focused on "re-skinning" the application and supports the following types of changes:
- Add an application specific image to the top-level menu
- Change the text to be displayed on the main menu to identify the application
- Change the application logo to be displayed in the header area for the screen
- Change the artwork used on the "overhang" or header area for the screen
- Change the background color for the screen
- Change the colors used for font rendering on text, buttons, and screens
Within the application the developer is free to combine the available screen types and controls as needed to implement their application. The hierarchy of screens is unique for an application and depends on the user experience desired. Some applications may be fairly "flat" while others may have a deeper hierarchy.
3.0 Video Streaming
3.1 Supported Video Formats
The following is a summary of supported video formats that have been tested and/or are currently in-use. Other formats or encodings may be supported, but should be evaluated on a case by case basis.
Various to 720x480
Various to 1280x720 and
.mp4 (MPEG-4 Pt 14), .mov .m4v
.mp4 (MPEG-4 Pt 14), .mov .m4v
23.976 fps or 29.97 fps
23.976 fps or 29.97 fps
Average Streaming Video Bitrate3
384Kbps - 1.6Mbps
1.6Mbps – 3.2Mbps
Average USB Video Bitrate3
384Kbps – 8.0Mbps
384Kbps – 8.0Mbps
Peak Video Bitrate
Key Frame Interval
AAC LC (CBR),
AAC LC (CBR),
Audio Bit Rate
Audio Sample Rate
44.1 Khz or 48Khz
44.1 Khz or 48 Khz
Audio Sample Size
1 The dimensions vary on a title-by-title basis depending on the source material and the target aspect ratio for the encoding (e.g. 4:3 or 16:9). Content should always be encoded at full width and the height is adjusted. For example, a 1.66 aspect ratio source is encoded as a 720x432 video and displayed as letterboxed for a 4:3 display.
2 The frame rate used for encoding depends on the source material. Film content is generally 23.976 fps, while video content is generally at 29.97.
3 For typical streaming video applications, we recommend a range of ~384Kbps to ~3.8Mbps. For USB playback, we recommend that you stay under 8.0 Mbps. This provides a good balance between quality and support for a wide number of users. In some cases lower and higher bitrates have been used, but this frequently results in poor quality, and/or reduces the number of Roku users that can view the encoded material.
3.2 Supported Image Formats
The following image formats are currently tested and in-use. Other formats or encodings may be supported, but should be evaluated on a case by case basis. The use of PNG is recommended for UI graphics due to the use of an alpha channel within the UI.
- JPG, JPEG
3.3 Trick Mode Support
Two types of trick mode support (FF/REW/SEEK) are provided. For developers who generate and publish image archives in Roku's BIF (Base Index Frame) file format, scene based trick-mode using index frames will be supported. A specification is available which details the BIF file format and data required. If this data is published and available for a given title, scene based trick-modes will be available. The content meta-data indicates the availability of this data on a per title basis by providing URL's for the HD and SD versions of these assets.
In cases where the BIF file is either not supported or unavailable, the system will present a time-based method of supporting trick modes. The user will be presented with a progress bar showing their location in the show and be allowed to seek using the normal trick play controls. Since scene information is not available, the user will only have a visual timeline and numeric time information to locate their desired position in the movie. Once the new location is selected, the system will buffer a minimal amount of stream data and begin playback.
4.0 Guided Setup and Registration
4.1 Guided Setup
Guided Setup is done only during the initial setup process or when the device has been reset to factory defaults. This process is designed to be developer independent and is performed one time. If reconfiguration of these attributes is needed, it can be done through the Settings option on the main menu. Guided Setup configures basic network services (wired or wireless) and performs a series of tests to ensure the device can communicate properly.
Guided Setup then takes the user through a rendezvous style registration process to link the Roku device to an account on
roku.com. An account defines a unique channel line-up for a user based on the channels they have selected. All devices linked to a specific account will receive the same channel line-up.
Developer applications may also wish to present a customized view to their individual users. The standard way to support this on the Roku Streaming Player is to provide a registration process that associates the device with a user-specific account on the developer's site. Each developer needing account registration will be required to implement a registration UI as part of their application. This UI may be called in one of two ways:
- On first use of any service, the system may detect that a service has not yet been configured and guide the user through the registration process for that developer. This method makes it easy for new services to be added to the device over time and presents a one-time configuration step on first use. The Netflix channel is a good example of this type of registration.
- On first use of an account specific feature, the user may be prompted to register their device and obtain access to these enhanced feature(s). An example of this approach would be a service that may be used without an account to provide a base level of functionality, but that requires account linking for advanced features such as personalization, favorites or other similar features. The Amazon channel is a good example of this type of registration. You can see it when entering "Your Video Library". Flickr also uses this approach and that source is available in the SDK examples.
The process of registration involves linking a device (identified by a unique electronic serial number) with an account on a specific service. Account registration and device linking can be accomplished in two ways. The preferred method is through the implementation of a code-based "rendezvous" style registration system. An alternative username/password style of registration may also be used.
A rendezvous registration system presents the user with a simple on-screen code on the device during registration. The user enters this code on the developer's website to establish a link between the device and the users account. This type of registration requires the third-party developer to implement the following features:
- A web services API for obtaining a registration code and specifying retry parameters
- A web services API for obtaining the registration result and associated user token
- Web pages to register/un-register a device on the developer's site
A username/password registration scheme may be desirable for some services. In these cases, the user will enter the username and password for their account during setup. This info will be used in subsequent calls to the third-party service to obtain the necessary credentials to make web services requests. This method is provided solely for compatibility with a variety of services. The rendezvous style registration is preferred both for its usability as well as the security benefits.
Any user account information or tokens exchanged during the registration process may be stored in the application specific portion of the registry as persistent data. This data may be accessed again at any time by the application when making web services calls to the developer's back-end service.
It is important not to keep any permanent device association stored on your server. Roku wants to give users the ability to do a "Factory Reset" and have any personally identifiable information wiped from the device. This includes removing any association with server side accounts. Account tokens stored in the device registry meet this requirement nicely as the device registry is removed with a "Factory Reset".
Details and a walkthrough of implementing device/account linking and registration can be found in the Device Linking and Registration Guide.
5.0 Security Overview
5.1 System Security
The Roku Streaming Player is designed to play a variety of streaming content directly from the Internet. We understand that this content is valuable to the content owners and must be protected from unauthorized access to prevent both casual and professional copying and distribution. Multiple types of security provisions are available if needed.
The system has been designed to be hardened against unauthorized attack. This process starts at the Roku factory as each system is individualized and uniquely keyed as a foundation for robust security. The platform supports a secure key store and hardware encryption engine. The core set of system software has been encrypted and is protected by a secure boot process and the use of signed binaries.
SSL is the primary method provided for developers to implement content and/or communications security for their application. The device supports both client and server authentication via SSL to provide a secure communications channel between trusted end-points.
5.2 Application Security
Applications which run on the player must be encrypted and signed using the developer's unique developer specific set of keys generated by the Roku Streaming Player in developer mode. Code signing is done automatically as part of generating a package and ensures the integrity of code. Application packages are also encrypted to ensure confidentiality of the source code. Packaging tools are available on the Developer web page of Roku Streaming Players. By default, the Developer page is not enabled. You must enter the remote code Home 3x, Up 2x, Right, Left, Right, Left, Right to enable it. A walkthrough of the packaging process is detailed later in this document.
The packaging process is designed to be lightweight and focuses on ensuring that an application originates from a known source and is protected against tampering. It is the responsibility of the developer to ensure that the application is properly tested, high quality, and provides a good user experience.
5.3 Protected Environment
BrightScript applications are run within a unique context in the BrightScript Virtual Machine. Applications are "sand-boxed" and run protected from other areas of the system. Scripts have limited access to platform resources and can only access functionality specifically exposed through the scripting layer as BrightScript components. This ensures the overall integrity of the platform and prevents unauthorized access to the operating system or any third party content. Applications are restricted from interacting with other applications on the system or accessing their private data. Applications store their data separately and securely in a unique area of the system registry. Suites of applications can share registry data by creating each application's package with the same developer ID keys.
6.0 Development Overview
6.1 Development and Deployment Process Overview
New applications or channels are written using the BrightScript programming language. BrightScript exposes platform functionality through BrightScript Components, which may be used by developers to create their application. These applications are designed to be standalone entities that can be deployed to a running system with minimal impact, no major software upgrades, and no downtime.
Applications consist of a set of BrightScript program files (text files), resources such as images (JPEG and PNG formats) and optionally, data unique to a specific application. Since BrightScript files are text files, you can use your text editor or IDE of choice for writing code. When the application is ready to be tested, web and command line based tools are available to make the process of packaging the application and deploying it to a development system fast and easy. Development builds are designed to be deployed to individual or small groups of systems where the developer has physical access. Wider deployment for beta and/or production releases can utilize the Roku developer website to upload channels for private or public access.
A walkthrough of installing to a local development enabled Roku Streaming Player can be found later in this document. A walkthrough of packaging your application and deploying privately to users who know your channel code or publicly to all users via publishing in the Channel Store is available in the Channel Packaging And Publishing guide. Details on developing with Roku Components and the APIs available can be found in the Component Reference.
7.0 Loading and Running your Application Walkthrough
7.1 Enabling Development Mode on your box
Before you are able to load a development application to your box, you must enable development mode on your Roku Streaming device. Development mode can be enabled only on a linked device. Your device must be linked to a Roku user account. You can link your device by either resetting it to factory defaults or going to Streaming Channels on your device.
To enable development mode, enter the special remote control sequence: Home 3x, Up 2x, Right, Left, Right, Left, Right.
You will be presented with the Developer Settings page where you can enable developer mode on the box. When developer mode is enabled, you can access the Application Installer page as specified in the next section.
If you would like to subsequently disable development mode on your box, simply enter the special remote code sequence again and select the "disable installer" option on screen.
7.2 Application Installer Page
Development applications are loaded onto the device using a standard web browser. When enabled for development mode the device hosts a web page for installing your application. To access the installer page, do the following:
- From your Roku Streaming Player, navigate to "Roku Player Settings", "player info" to find the IP address of your box.
- From your development workstation, open a standard web browser and type the following URL for the browser to open:
. For example:
- You should see a page like the one displayed in Figure 1 (Application Installer Page) below.
- Click the Browse button and navigate to the location of the application ZIP file on your development machine as shown in Figure 2 (Application File Browser). The full path to the application ZIP file should appear in the text field.
- Finally, click the Install button to deploy the application to the Roku player. The application should install and begin running immediately. You will see a message on the web page indicating it was successfully loaded as shown in Figure 3 (Application Installer Page – Installation Complete).
- Run the application with the application debug console open. When you Telnet to the Roku Streaming Player on port 8085 (see 8.1 Accessing the Debug Console) you will see the debug console from your application. If there are any errors in your code, they will show up on this console. There is even a debugger attached to this port that will give you source file and line number information for script errors.
The Application Installer page only accepts applications using the ZIP file format (
.zip). This process is often referred to as "side-loading" your application. It does not allow installation of signed applications package files (
.pkg). A package file must be distributed through the Channel Store mechanism, as either a published or private channel application.
The following image shows the Development Application Installer web page. At this point, there is no developer application on the device. If an application were present, it would be shown as installed when the page is initially opened. The application will continue to persist on the device until you delete it by using the Delete button shown below.
Figure 1: Application Installer Page
The following image shows the standard windows file browser. Your development environment may be on Windows, Linux or Mac, since all you need are text editing tools, a web browser and the ability to generate ZIP files containing your application. Select your application ZIP file and you are ready to install.
Figure 2: Application File Browser
The following image shows the Development Application Installer web page after you've successfully installed your application. If you attempt to reinstall an identical version of an application that is already installed on the box, you will receive an error. You can always delete and re-install any application at any time.
Applications are limited to a maximum of 2MB in size, due the the limited amount of flash storage available. In general, since these are internet enabled applications, they tend to be much smaller and are typically less than 300KB in size. Most of the space is consumed by artwork and the code size is minimal. If you find that your application is too large to install, look at removing some of the artwork from your application package and placing it on the web where it is easier to modify and it can be downloaded dynamically at runtime.
Figure 3: Application Installer Page – Installation Complete
7.3 Using the Makefile to "Side-Load" the channel
The SDK examples include Makefiles that can automate the steps needed to install the channel. The Makefiles use the
ROKU_DEV_TARGET environment variable to know the IP address of the Roku box to install on. Instead of following the steps in 7.2 Application Installer Page, you could use the Makefile from a shell as follows:
% export ROKU_DEV_TARGET=192.168.1.140
% cd <sdk>/examples/source/videoplayer
% make install
7.4 Building an Application
Now that you've installed some of the SDK examples, here's how to build a simple application from start to finish. We'll show you how to do it by building the simplest of all applications, an application that prints "Hello World!" on the screen.
First, create a directory named
helloworld, with a sub-directory named
source, such as:
% mkdir helloworld
% cd helloworld
% mkdir source
Using your favorite editor, create the manifest file for the Hello World application named
manifest in the
helloworld directory that contains the following content:
Now, create a BrightScript source code file named
helloworld.brs in the
helloworld/source directory that contains the following content:
Finally, use a ZIP program to create the compressed archive of your application, such as:
% zip -9 –r ../helloworld.zip .
Now you can follow the instructions in 7.2 Application Installer Page to install
helloworld.zip as a development application on a development test Roku device.
8.0 Debugging your Application
8.1 Accessing the Debug Console
Using a standard shell program and a Telnet client application, you can connect to the console for your application. The console provides you a window into the runtime environment for your application. By default, all console output from your application goes to the shell. You can learn a lot about your application just from the debug output. To access the console for your application:
- Open up a terminal shell application, for example, one of the following:
- Command.com or other terminal on Windows (All Programs -> Accessories -> Command Prompt)
- Gnome or other terminal on Linux
- Terminal on Mac
- Type the command:
telnet rokuPlayer-ip-address 8085
% telnet 192.168.1.100 8085
You should see the contents of the current application output buffer. Make sure your application is running, because you must run a development app to see output in this console. The console will not allow access to the output of other applications on the system. It will only allow debug access to your development application.
Figure 4: Connecting to the Application Debug Console
8.2 Script Output
The console shows you the output of your script during run time. If your application crashes, the debugger will display the line number of the error, as well as the contents of various variables at the time of the crash. If there is a syntax error in your code it will also be described here. You should have the developer console open whenever you install a new application to catch any startup errors.
8.3 The BrightScript Debugger
In addition to displaying console output, the shell can also be used as an interactive debugger. When your application is running, simply press CTRL-C to break the application and enter debug mode. You will see the BrightScript Debugger prompt where you can type in commands. You can also force your application to break at a specific location by placing the "stop" command anywhere in your script.
You can resume you application again by typing "c" or "cont". For a full list of options, type "help" in the debugger. You'll see options for inspecting variables, stepping through your code and looking at the backtrace of the current call stack.
Figure 5: A Sample Debug Session
8.4 Getting Packet Traces
It is sometimes useful to get packet traces from the Roku device in the process of debugging your application. Here are a couple of links to resources for doing this:
9.0 Top Development Tips for the Roku Platform
Make sure you capture all of the events sent by the
roVideoScreenor you may miss important playability information.
- Know the remote control codes for special screens:
- Dump Core: Home 5x, Up, Rew 2x, FF 2x
- Debug Info on screen: Home 5x, Rew 3x, FF 2x
- Channel Version Info: Home 3x, Up 2x, Left, Right, Left, Right, Left
- Developer Settings Page: Home 3x, Up 2x, Right, Left, Right, Left, Right
- The Developer Settings Page is necessary for enabling developer mode on your box.
- All file paths are prefixed by the device name and a colon:
pkg:/filename.txt. See File System for more information.
- Always use a screen facade object when launching your application so that it appears to the user that your channel launches immediately and avoids screen flicker when exiting. See Working with Screens for more information, see the simplevideoplayer sample application for a commented implementation of the technique.
- You can use the theme attributes of
roApplicationManager(see Component Reference) to create a new UI skin for your channel.
- When using rendezvous style registration and account linking, be sure to store the linking information in the device registry and not on your servers. We require that users are able to do a "Factory Reset" and be confident that no personally identifiable information is associated with the device. This is not possible if you have saved permanent serial number information on your servers.
- We are limited in the types of video content supported on the device. We currently support
.m4vfiles with H.264/AAC encoding as well as unencrypted WMV and HTTP Live Streaming.
- We only support
.mp3audio files in the audio player.
- Be sure to use a unique key for each application you publish and reuse this key each time you update your application using the "rekey" option. This ensures that all versions of your application will have access to the same registry data and avoid causing users to re-link after an update.
- When using the slide show component, a high resolution image may take a while to download. A good trick to provide quick feedback to the user is to put an image in your package (so it's not downloading) that may have your logo, and informs the user that the slideshow is "Retrieving…". This slide could be the first slide in your slideshow so that feedback to the user is instant, and the slideshow never appears "hung".
- We require that your web servers support range requests. If they do not, you may run into content that is not playable, or large images that do not display. The data will appear as a corrupted file format to our components, as the first block may be resent by the web server when we expect data at a particular range or offset.
- The screens are displayed in a LIFO (stack) order. If this behavior is causing your screen to flicker (perhaps you wanted to pop two screens after you are done with the current one) there is a
Close()method in the screen interface of all the screen and dialog components that deletes the screen out of the display stack. An example might be coming out of a Registration or Search page to a Springboard screen. From the Springboard screen, you might want to exit to your main screen, not the registration screen or search screen. The following is an example of how this would be coded:
10.0 Pre-Certification Checklist
Before your channel can be published to the Roku Channel Store, it must satisfy a set of quality, user interface, and performance criteria. This set of criteria is listed in the Channel_Checklist_v_1_14.xlsx. You can help speed the certification process by reviewing these requirements prior to developing your channel and checking that they are satisfied before submission.