BrightScript Engine API

The engine worker library (brs.worker.js), has a programmable interface (brs.api.js), built in packages/browser/lib/, with the goal to facilitate the integration of the engine into web based applications.

Check the documentation to learn how to start using it. The only pre-requisites are to expose, on the default document, a canvas object named display and a video object named player, and optionally, if you want to show the performance statistics, you also need to expose a div object named stats.

Methods

Method	Description	Parameters / Details
initialize(customDeviceInfo?, options?)	Initializes the engine simulated device	customDeviceInfo? (object): customized device information, see /src/core/common.ts for valid properties. options? (object): init options, valid properties are: - showStats(boolean): if true the performance statistics overlay will be shown over the display when the app is running, default is false. - disableDebug(boolean): if true prevents any debug command/data to be sent or received by the engine, for production to avoid code injection, default is false. - debugToConsole(boolean): if false prevents messages to be sent to the console, you still can debug messages via debug event, default is true. - disableKeys(boolean): if the engine is running on a device with no keyboard, or you don't need keyboard control, set this option to true to disable keyboard control, default is false - customKeys(Map): a custom map of keyboard keys to add/remove from the remote control simulation, see /src/api/control.ts for the default mappings. - disableGamePads(boolean): Set this option to true if you want to disable the game pad control support, default is false - customPadButtons(Map): a custom map of GamePad buttons (0-31) to add/remove from the remote control simulation, see /src/api/control.ts for the default mappings.
subscribe(observerId, observerCallback)	Subscribes to the engine events (see list below)	observerId (string): identifier of the subscriber process. observerCallback (function): callback function to receive the events from the engine.
unsubscribe(observerId)	Unsubscribes to the engine events	observerId (string): identifier of the subscriber process.
execute(filePath, fileData, options?, deepLink?)	Loads and run an app package (.zip/.bpk), a source code file (.brs) or plain text BrightScript code	filePath (string): path of the loaded file, make sure extension is .zip or .bpk if loading a full app. fileData (ArrayBuffer/Blob/string): contents of the file or just a string with BrightScript code. options? (object): execution options, valid properties are: - clearDisplayOnExit (boolean): if false the display will keep the last image when app ends, default is true. - muteSound (boolean): if true the engine will mute all audio but events are still raised, default is false. - entryPoint (boolean): Change the property in DeviceInfo with same name, if true will raise a warning when the app has no entry point, functions Main() or RunUserInterface(), default is true. - debugOnCrash (boolean): Change the property in DeviceInfo with same name, if true stops on the Micro Debugger when a crash happens, default is false. - password (string): the password to decrypt a .bpk, or encrypt a .zip package, default is "". deepLink? (Map): Parameters to be passed to the application as deep link.
terminate(reason)	Terminates the current app/source code execution	reason (string): the reason for the termination to be shown on debug.
redraw(fullScreen, width?, height?, dpr?)	Requests a display redraw (always keeps the aspect ratio based on display mode)	fullScreen (boolean): Flag to inform if the full screen mode is activated. width? (number): width of the canvas, if not passed uses globalThis.innerWidth. height? (number): height of the canvas, if not passed uses globalThis.innerHeight. dpr? (number): device pixel ratio, if not passed uses globalThis.devicePixelRatio.
setDisplayMode(mode)	Configures the display mode (if an app is running will reset the simulated device)	mode (string): supported modes are "480p" (SD), "720p" (HD) or "1080p"(FHD).
getDisplayMode()	Returns the current display mode.
setOverscanMode(mode)	Configures the overscan mode.	mode (string): supported modes are "disabled", "guidelines" or "overscan".
getOverscanMode()	Returns the current overscan mode.
setCaptionMode(mode)	Configures the closed caption mode.	mode (string): supported modes are "Off", "On", "Instant replay" or "When mute".
getCaptionMode()	Returns the current closed caption mode.
setCaptionStyle(style)	Configures the closed caption style options.	style (object[]): The caption styles array with each option as {id: string, style: string}, see options in Roku Documentation.
getScreenshot()	Returns an ImageData with the latest rendered screenshot or null if not available.
enableStats(state)	Enables or disables the performance stats overlay	state (boolean): if true performance statistics will be shown over the display, on the top left.
setAudioMute(mute)	Mutes or un-mutes the audio during app execution	mute (boolean): if true the executing app audio and video will be muted.
getAudioMute()	Returns true if the audio is muted
getSerialNumber()	Returns the device serial number, this value changes when the deviceData.deviceModel is updated.
setControlMode(controls)	Enable/Disable the remote control simulation	controls (object) contains following properties: keyboard (boolean): if true enables the keyboard control. gamePads (boolean): if true enables game pad control.
getControlMode()	Returns an object with the control mode flags	Same options sent to the setControlMode above.
setCustomKeys(keysMap)	Sends a custom map of keyboard keys to add/remove from the remote control simulation	keysMap (Map): see /src/api/control.ts for the default mappings.
setCustomPadButtons(buttonsMap)	Sends a custom map of game pad buttons to add/remove from the remote control simulation	buttonsMap (Map): see /src/api/control.ts for the default mappings.
sendKeyDown(key, remote?, index?)	Sends a remote control key down event to the engine	key (string): one of valid key codes (see Roku doc). remote (number): one of valid remote types (see /src/api/common.ts) default is ECP. index (number): The index of the remote control, default is 0.
sendKeyUp(key, remote?, index?)	Sends a remote control key up event to the engine	key (string): one of valid key codes (see Roku doc). remote (number): one of valid remote types (see /src/api/common.ts) default is ECP. index (number): The index of the remote control, default is 0.
sendKeyPress(key, delay?, remote?, index?)	Sends a remote control key press event to the engine	key (string): one of valid key codes (see Roku doc). delay (number): the delay (in milliseconds) between sending Key Up and Key Down (default is 300ms). remote (number): one of valid remote types (see /src/api/common.ts) default is ECP. index (number): The index of the remote control, default is 0.
sendInput(params)	Sends custom events to the current application to be raised by roInput component	params (object): An object with the parameters in the format {'string': 'string', ...}
mountExt(zipData)	Mounts a zip file as the external volume ext1:	zipData (ArrayBuffer): The contents of a zip file to be mounted by the engine File System
umountExt()	Unmounts the external volume ext1:
updateMemoryInfo(used, total)	A method for the host application to inject memory usage information to the engine.	used (number): Memory used by the app (in KB) total (number): Total memory available for the app (in KB)
debug(command)	Sends a debug command to the Engine	command (string): the Micro Debugger can be enabled sending break command, and after that, any valid BrightScript expression or debug commands can be sent. You can also send pause to interrupt the interpreter, for instance, when the app loses focus. The command cont restarts the app. You can use this method on the browser console to debug your app.
getDebugState()	Returns true if debug functionality is enabled, false if disabled
setDebugState(enabled)	Enables or disables the debug functionality	enabled (boolean): if true enables debug commands and data to be sent/received by the engine, if false disables debug functionality for production to avoid code injection.
getVersion()	Returns the version of the API library

Events

Event	Description	Data Type
loaded	Triggered when the source code data has finished loading	object: {id: string, file: string, title: string, subtitle: string, version: string, running: boolean}
icon	Triggered when the zip file is loaded and manifest links to a valid icon for the app	base64: A base64 string of the app icon, extracted from the zip file.
registry	Triggered when the app updates the registry	Map: the registry with all recent recent updates.
started	Triggered when the engine started running the source code	object: {id: string, file: string, title: string, subtitle: string, version: string, running: boolean}
closed	Triggered when the engine terminated the execution of the source code	string: the exit reason based on Roku documentation
reset	Triggered when the RebootSystem() function is executed from the engine	null: Nothing is returned as data
control	Triggered when a control key is sent to the engine	object: {key: string, mod: number}. The property key contains an ECP key code and mod contains 0 for key down or 100 for key up
captionMode	Triggered when the closed caption mode is changed	string: The new caption mode, options are "Off", "On", "Instant replay", "When mute"
redraw	Triggered when the display canvas is redrawn/resized	boolean: If true the display canvas is in full screen mode
resolution	Triggered when the emulated screen resolution changes (controlled via BrightScript)	object: {width: integer, height: integer}
launch	Triggered when the methods roAppManager.launchApp() or roNDK.start() (with SDKLauncher app) are called from BrightScript	object: {app: string, params: Map}.
browser	Triggered when the library sub RokuBrowser is called from BrightScript	object: {url: string, width: integer, height: integer}. The parameters width and height defines the dimensions of the browser window
debug	Triggered when debug messages arrive from the worker library (BrightScript Interpreter)	object: {level: string, content: string}, levels are: print, beacon, warning, error, stop, pause, continue
error	Triggered when the any execution exception happens on the API library	string: The message describing the error