CLI profiling tool for Roku channels. Launches a local web server and opens a browser-based dashboard showing live performance metrics, SceneGraph UI events, and BrightScript console output.
On AI-assisted development: This tool was built with AI assistance. The architecture, ECP endpoint knowledge, SceneGraph diffing strategy, and developer workflow come from 7+ years of Roku development experience. The AI helped turn that into working code faster. Using better tools doesn't make the work less valid — it's the same reason nobody questions using libraries, Stack Overflow, or a nail gun instead of a hammer. What matters is: does it work, is it useful, can you contribute.
npm install -g rokuperf
# or use npx
npx rokuperf --device 192.168.0.30# Attach to the currently running app
rokuperf --device 192.168.0.30
# Sideload a zip then profile
rokuperf --load ./out/myapp.zip --device 192.168.0.30| Flag | Default | Description |
|---|---|---|
--load <path> |
Path to .zip to sideload before starting |
|
--device <ip> |
ROKU_DEVICE_IP env, then 192.168.0.30 |
Roku device IP address |
--port <n> |
4080 |
Local server port |
--no-open |
Don't auto-open browser | |
--poll-ui <ms> |
2000 |
SceneGraph poll interval |
--poll-fast <ms> |
500 |
Fast poll interval (active-app, media-player, rendezvous) |
--dev-password <pw> |
ROKU_DEV_PASSWORD env, then rokudev |
Roku dev password for sideloading |
ROKU_DEVICE_IP— Default device IPROKU_DEV_PASSWORD— Default dev password for sideloading
Copy Makefile.rokuperf into your project or include it:
include Makefile.rokuperfThen:
make profile # sideload + profile
make profile-attach # attach to running appFour tabs:
- Live — Real-time CPU%, heap, rendezvous/s metrics with 60s rolling timeline. UI event markers. BrightScript console stream.
- Trace — Drop zone for
.perfetto-tracefiles + link to ui.perfetto.dev. - Session — Timeline scrubber, event list, JSON export.
- Memory — Memory trend chart, current snapshot, high water mark, growth alert. Process-level stats (vsize, rss) on OS 15.2+.
| Feature | Minimum OS |
|---|---|
| Basic profiling (CPU, memory, UI events, console) | Any |
| SceneGraph rendezvous tracking | 11.5+ |
| Process-level memory stats (vsize, rss, pid) | 15.2+ |
Features degrade gracefully on older OS versions — no crashes, just reduced data.
rokuperf polls the Roku ECP (External Control Protocol) endpoints on your device:
- Slow loop (2s default):
/query/app-uifor UI tree diffing,/chanperffor CPU/memory - Fast loop (500ms default):
/query/active-app,/query/media-player,/query/sgrendezvous - Telnet (streaming): BrightScript console on port 8085
All data flows server → browser over a single WebSocket. The browser never talks to the Roku device directly.
npm install
npm run build
npm run test
npm start -- --device 192.168.0.30MIT