python-roku

Screw remotes. Control your Roku <http://www.roku.com>_ 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 <http://abc.go.com/shows/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 <http://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol>`_. 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 <https://github.com/dankrause>`_ for his `SSDP code <https://gist.github.com/dankrause/6000248>`_.


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 <https://github.com/lingster/pyrokuserve>_
Home Assistant <https://www.home-assistant.io/components/roku/>_

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 <http://sdkdocs.roku.com/display/sdkdoc/External+Control+Guide#ExternalControlGuide-31ExternalControlInputCommandConventions>`_.


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.