Metadata-Version: 2.1
Name: heospy
Version: 0.1.0
Summary: Control Denon's HEOS speakers with Python.
Home-page: http://pypi.python.org/pypi/heospy/
Author: Stephan Heuel
Author-email: mail@ping13.net
License: LICENSE.txt
Platform: UNKNOWN
Requires-Dist: six
Requires-Dist: future

# Control an HEOS player with a Python script

## Requirements

You have an [HEOS][] speaker in your local network and Python 2.7 or
Python 3.

## Usage

0. Install the package with 

```
python setup.py install
```

1. Create a `config.json` file, which may reside in the current directory, in
   `$HOME/.heospy` or in a directory wich is specified by the environment
   variable `$HEOSPY_CONF`. The config file contains the name of the lead
   [HEOS][] player you want to control and the username and password of your
   [HEOS account][]. See `example-config.json` for an example.

2. Run the script for the first time to see how this works:

        $ heos_player
        2017-02-12 20:32:29,880 INFO Starting to discover your HEOS player 'Living room' in your local network
        2017-02-12 20:32:36,824 INFO Found 'Living room' in your local network
        $

3. Now you can call any command from the [CLI specs][specs], see also `docs/`
   folder. Additional arguments are given with `-p`. The player id will be
   automatically submitted. Some examples:

        heos_player player/toggle_mute
        heos_player player/set_volume -p level=19
        heos_player player/play_preset -p preset=3
        heos_player player/set_play_state -p state=stop
        heos_player group/toggle_mute 
        heos_player group/toggle_mute -p gid=-1352658342

    Use the flag `--help` for a detailed help.

4. You can also execute a sequence of commands at once. The sequence can be
   given in a file:

        heos_player -i cmds.txt

   An example for `cmds.txt` is:

        system/heart_beat
        # let's set a volume
        player/set_volume level=10
        # let's check if the volume is correct
        player/get_volume 

   Note that comments are possible and start with a `#`. You can also get the
   sequence of commands from `stdin`:

        printf "system/heart_beat\nplayer/set_volume level=10\nplayer/get_volume" | heos_player -i -

[specs]: http://rn.dmglobal.com/euheos/HEOS_CLI_ProtocolSpecification.pdf
[HEOS]: http://heoslink.denon.com
[HEOS account]: http://denon.custhelp.com/app/answers/detail/a_id/1968

## Main player setting

The class `HeosPlayer` assumes a main HEOS player, stored in the config
file. For commands starting with `player/`, we assume that this player should
be used, otherwise you need to specify the player id explicitly as a parameter.

If this player is a lead player in a group, this group is also the main group
for commands starting with `group/`. Again, you can override this setting be
explicitly mention the group id as a  parameter.


## Usage with Raspberry Pi and Kodi

If you have [OSMC][] or any other [Kodi Media center][Kodi] implementation on
your [Raspberry Pi][raspi], you can map certain actions for your HEOS on a
[keymap][].

[OSMC]: https://osmc.tv
[raspi]: https://www.raspberrypi.org
[Kodi]: http://kodi.wiki/view/Kodi
[keymap]: http://kodi.wiki/view/Keymaps

Example `keyboard.xml`-file:
```
<keymap>
  <global>
    <keyboard>
      <F1>RunScript(heos_player, player/play_preset, -p, preset=1)</F1>
      <F2>RunScript(heos_player, player/play_preset, -p, preset=2)</F2>
      <F3>RunScript(heos_player, player/play_preset, -p, preset=3)</F3>
      <F4>RunScript(heos_player, player/play_preset, -p, preset=4)</F4>
      <F12>RunScript(heos_player, player/set_play_state, -p, state=stop)</F12>
    </keyboard>
  </global>
  <Home>
  </Home>
</keymap>
```

## Credits

- first code from <https://github.com/mrjohnsen/heos-python>
- the SSDS discovery library is from
  <https://gist.github.com/dankrause/6000248>, with an additional modification
  by Adam Baxter to get this working for Python 3.


