https://github.com/jcarbaugh/python-roku
Screw remotes. Control your Roku with Python.
https://github.com/jcarbaugh/python-roku
Last synced: about 1 year ago
JSON representation
Screw remotes. Control your Roku with Python.
- Host: GitHub
- URL: https://github.com/jcarbaugh/python-roku
- Owner: jcarbaugh
- License: bsd-3-clause
- Created: 2014-01-04T19:09:41.000Z (over 12 years ago)
- Default Branch: main
- Last Pushed: 2023-07-25T21:37:57.000Z (almost 3 years ago)
- Last Synced: 2025-05-10T04:48:59.564Z (about 1 year ago)
- Language: Python
- Homepage: https://pypi.python.org/pypi/roku
- Size: 138 KB
- Stars: 320
- Watchers: 19
- Forks: 97
- Open Issues: 14
-
Metadata Files:
- Readme: README.rst
- License: LICENSE
Awesome Lists containing this project
README
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
[, , ]
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']
>>> roku[2285]
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
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()
[]
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)
[, ]
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
~~~~~~~~~~~~
* `pyrokuserve `_
* `Home Assistant `_
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.