search

jcarbaugh / python-roku

Screw remotes. Control your Roku with Python.
https://pypi.python.org/pypi/roku
BSD 3-Clause "New" or "Revised" License
288 stars 94 forks source link

readme

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:

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