Metadata-Version: 1.1
Name: roku
Version: 3.1.2
Summary: Client for the Roku media player
Home-page: https://github.com/jcarbaugh/python-roku
Author: Jeremy Carbaugh
Author-email: jcarbaugh@gmail.com
License: BSD License
Description: python-roku
        ===========
        
        Screw remotes. Control your `Roku <http://www.roku.com>`_ via Python.
        
        .. image:: https://travis-ci.org/jcarbaugh/python-roku.svg?branch=master
            :target: https://travis-ci.org/jcarbaugh/python-roku
        
        
        Installation
        ------------
        
        ::
        
            pip install roku
        
        
        Usage
        -----
        
        
        The Basics
        ~~~~~~~~~~
        
        To start, import the Roku object and create it with the IP 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 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)
        
        
        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')
        
        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.
        
        
        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.
        
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
