Roku Remote TUI

A powerful terminal-based remote control for Roku devices with fuzzy search, favorites, and advanced features.

✨ Features

🚀 Quick Launch System

• Fuzzy Launcher (/) - Instant search across all apps with smart matching
  • Try typing "nflx" to find Netflix
  • Shows favorites first
  • Real-time filtering as you type
• Favorites - Save up to 9 apps for one-key launch
  • Press F then 1-9 to set a favorite
  • Press 1-9 anytime to launch
  • Favorites highlighted in yellow in apps list

🎮 Full Remote Control

• Complete directional pad (↑↓←→)
• OK, Back, Home buttons
• Playback: Play/Pause, Rewind (b), Fast Forward
• Volume: -/= for down/up, m for mute
• Info (i) and Replay (r) buttons

💬 Text Input

• Typing Mode (t) - Send text to Roku for search
• Perfect for entering search queries, passwords, etc.

🖱️ Mouse Support

• Mouse wheel scrolls apps list (super fast, continuous wrap-around)
• Mouse wheel in Remote mode sends navigation to Roku
• Intelligent debouncing prevents command spam

🎨 Beautiful Interface

• Three-panel layout: Quick Keys | Remote | Apps
• Color-coded elements
  • Favorites in yellow with [F1-F9] markers
  • Selected items highlighted
  • Online/offline status indicator
• Real-time status messages
• Help overlay (?) with all shortcuts

📦 Installation

Prerequisites

# Roku CLI tool (required)
npm install -g @dlenroc/roku

# Or check: https://github.com/dlenroc/node-roku

Setup

# Clone
git clone git@github.com:Extended3652/roku_control.git
cd roku_control

# Run
python3 roku_remote_tui_main.py

⌨️ Keyboard Shortcuts

Navigation & Launch

Key	Action
Tab	Switch focus (Remote ↔ Apps)
↑↓←→	Navigate (context-aware)
Enter	OK / Launch selected
Backspace	Back
/	Open fuzzy launcher

Remote Control

Key	Action
h	Home
Space	Play/Pause
r	Replay (in Remote mode)
i	Info
b	Rewind
m	Mute
- / =	Volume down/up

Favorites & Features

Key	Action
F	Enter favorite assign mode
1-9	Launch favorite (or set if in assign mode)
t	Typing mode (send text)
r	Refresh apps (in Apps mode)

General

Key	Action
?	Toggle help overlay
q	Quit

🏗️ Architecture

roku_remote_tui/
├── app.py                  # Main application & event loop
├── __main__.py             # Entry point
│
├── roku/
│   └── cli.py              # Roku CLI wrapper with error handling
│
├── ui/
│   ├── renderer.py         # All drawing/display (3-panel layout, overlays)
│   └── input_handler.py    # Keyboard & mouse with debouncing
│
├── state/
│   └── app_state.py        # Application state & business logic
│
├── storage/
│   └── favorites.py        # Persistent favorites (JSON)
│
└── utils/
    └── fuzzy.py            # Fuzzy search algorithm

Design Principles

• Modular: Clean separation of concerns
• Responsive: Debounced inputs, fast UI updates
• Stateful: Remembers favorites, scroll positions
• Robust: Error handling, graceful offline mode

📁 Configuration

• Favorites: ~/.config/roku_remote_tui/favorites.json
• Cache: ~/.cache/roku_remote_tui/

🎯 Usage Tips

1. First time? Press ? to see all shortcuts
2. Can't find an app? Press / and start typing
3. Set up favorites for your most-used apps (Netflix, Hulu, etc.)
4. Mouse wheel works great for scrolling long app lists
5. Typing mode (t) is perfect for search boxes in apps

🐛 Troubleshooting

Apps not loading?

• Ensure Roku is on same network
• Run roku apps to test CLI connection
• Check Roku IP in ~/.roku/config.json

Mouse wheel too slow/fast?

• Adjust _wheel_min_gap_apps in ui/input_handler.py

🤝 Contributing

Contributions welcome! This project uses:

• Python 3.7+ with curses
• No external dependencies beyond roku CLI

📄 License

MIT

🙏 Credits

Built with:

• Python's curses library for TUI
• @dlenroc/roku CLI tool