Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jcarbaugh/python-roku

Screw remotes. Control your Roku with Python.
https://github.com/jcarbaugh/python-roku

Last synced: about 1 month ago
JSON representation

Screw remotes. Control your Roku with Python.

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.