Skip to main content

An async python library for controlling HEOS devices through the HEOS CLI Protocol

Project description


CI Status codecov image image image

An async python library for controlling HEOS devices through the HEOS CLI Protocol (version 1.17 for players with firmware 2.41.140 or newer).


pip install pyheos


pip install --use-wheel pyheos

Getting Started

The Heos class is the implementation providing control to all HEOS compatible devices on the local network through a single network connection. It is suggested to connect to a device that is hard-wired.

pyheos.Heos(host, *, timeout, heart_beat, all_progress_events, dispatcher)

  • host: str: The IP Address or hostname of a HEOS device on the local network. This parameter is required.
  • timeout: float: Number of seconds to wait during connection and issuing commands. Default is pyheos.const.DEFAULT_TIMEOUT = 5.0. This parameter is required.
  • heart_beat: Optional[float]: Number of seconds since last activity to issue a heart-beat command. Default is pyheos.const.DEFAULT_HEART_BEAT = 60.0. Set this parameter to None to disable heart-beat.
  • all_progress_events: Set to True to receive signals for each media play-back progression or False to only receive a signal when media state transitions to playing or changes. Default is True. This parameter is required.
  • dispatcher: Optional[pyheos.Dispatcher]: An instance of dispatcher to use for raising signals. The default is None which results in use of the default dispatcher implementation.

pyheos.Heos.connect(*, auto_reconnect, reconnect_delay)

Connect to the specified host. This method is a coroutine.

  • auto_reconnect: bool: Set to True to automatically reconnect to the host upon disconnection. The default is False.
  • reconnect_delay: float: The number of seconds to wait before attempting to reconnect upon a connection failure. The default is DEFAULT_RECONNECT_DELAY = 5.0


Disconnect from the specified host. This method is a coroutine.

pyheos.Heos.get_players(*, refresh)

Retrieve the available players as a Dict[int, pyheos.Heos.HeosPlayer] where the key represents the player_id and the value the HeosPlayer instance. This method is a coroutine. This method will populate the players property and will begin tracking changes to the players.

  • refresh: Set to True to retrieve the latest available players from the CLI. The default is False and will return the previous loaded players.
import pyheos

heos = Heos('')

await heos.connect(auto_reconnect=True)
players = await heos.get_players()
await heos.disconnect()

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyheos-0.7.4.tar.gz (30.6 kB view hashes)

Uploaded Source

Built Distribution

pyheos-0.7.4-py3-none-any.whl (25.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page