python-roku
Screw remotes. Control your Roku via Python.
Supports Python 3.7 to 3.11.
Installation
pip install roku
Usage
The Basics
To start, import the Roku object and create it with the IP address or hostname of your Roku.
>>> from roku import Roku
>>> roku = Roku('192.168.10.163')
The Roku object has a method for each of the buttons on the remote.
>>> roku.home() >>> roku.right() >>> roku.select()
To support keyup and keydown events simply pass "keyup" or "keydown" when you call the command.
>>> roku.right("keydown")
>>> roku.right("keyup")
To see a full list of available commands, use the commands property.
>>> roku.commands ['back', 'backspace', 'down', 'enter', 'forward', 'home', 'info', 'left', 'literal', 'play', 'replay', 'reverse', 'right', 'search', 'select', 'up']
If you are following along on your home network and are connected to your Roku, you should see it doing stuff. Cool!
Apps
The apps property will return a list of the applications on your device.
>>> roku.apps [<Application: [2285] Hulu Plus v2.7.6>, <Application: [13] Amazon Instant Video v5.1.3>, <Application: [20445] VEVO v2.0.12092013>]
Apps have id, name, and version properties.
>>> app = roku.apps[0] >>> print(app.id, app.name, app.version) 2285 Hulu Plus 2.7.6
You can get an individual app from the Roku object by either its name or id.
>>> roku['Hulu Plus'] <Application: [2285] Hulu Plus v2.7.6> >>> roku[2285] <Application: [2285] Hulu Plus v2.7.6>
Seeing the reference to this Hulu Plus app makes me really want to watch the latest episode of Nashville. Let's launch it!
>>> hulu = roku['Hulu Plus'] >>> hulu.launch()
Again, if you are following along at home, you should see that your Roku has launched the Hulu Plus app. Want to see the app's entry in the Channel Store?
>>> hulu.store()
You can also get the app's icon.
>>> with open('hulu.png', 'w') as f:
... f.write(hulu.icon)
>>> print hulu.icon_url
http://0.0.0.0:8060/query/icon/2285
You can get the current running app.
>>> roku.active_app <Application: [12] Netflix v4.2.75015046>
Entering Text
Okay, I've already seen all of the available episodes of Nashville, so I'm going to search for Stargate. With the search open and waiting for text entry:
>>> roku.literal('stargate')
What if I now want to watch The Informant!? Again, with the search open and waiting for text entry:
>>> roku.literal('The Informant!')
This will iterate over each character, sending it individually to the Roku.
Advanced Stuff
Discovery
Roku devices can be discovered using SSDP. A class method is available on the Roku object that will return Roku object instances for each device found on the same network.
>>> Roku.discover() [<Roku: 192.168.10.163:8060>]
It may take a few seconds for a device to be found. You can call discover again or change the timeout or retries parameters on the discover method. This will take longer, but will find more devices.
>>> Roku.discover(timeout=10) [<Roku: 192.168.10.163:8060>, <Roku: 192.168.10.204:8060>]
Thanks to Dan Krause for his SSDP code.
Sensors
Newer Roku remotes have extra sensors built into them that measure acceleration, orientation, and other things.You can mimic these sensors using the provided helper methods.
>>> roku.orientation(1, 1, 1)
The parameters to all of the sensor methods are x, y, and z values. Available methods include:
- acceleration - in each dimension relative to free fall measured in meters/sec^2
- magnetic - magnetic field strength in microtesla
- orientation - angular displacement from flat/level and north in radians
- rotation - angular rotation rate about each axis using the right hand rule in radians/sec
Touch
Some Roku input devices support touch. The parameters to the touch method are the x and y coordinates of the touch.
>>> roku.touch(10, 40)
You can change the event triggered by passing an optional op parameter.
>>> roku.touch(10, 40, op='up')
Supported events are:
- down
- up
- press (down and up)
- move
- cancel
Multitouch is not yet supported in this package.
Integrations
Generic Input
Both the sensor and touch methods rely on the generic input method for sending data to a running application. If you refuse to use covenience methods because they make people lazy and weak, you can call the sensor and touch methods directly.
>>> params = {'touch.0.x': 10, 'touch.0.y': 20, 'touch.0.op': 'press'}
>>> roku.input(params)
More information about input, touch, and sensors is available in the Roku External Control docs.
TODO
- Tests, of course.
- Multitouch support.
- A Flask proxy server that can listen to requests and forward them to devices on the local network. Control multiple devices at once, eh?
- A server that mimics the Roku interface so you can make your own Roku-like stuff.
- A task runner that will take a set of commands and run them with delays that are appropriate for most devices.