pytheos.api Package¶

`pytheos.api.browse` Module¶

class pytheos.api.browse.BrowseAPI(conn)¶

Bases: object

MAX_QUERY_RESULTS = 50¶

MAX_SEARCH_LENGTH = 128¶

async add_to_queue(player_id: str, source_id: str, container_id: str, media_id: Optional[str] = None, add_type: pytheos.models.browse.AddToQueueType = <AddToQueueType.PlayNow: 1>)¶

Adds the specified container or track to the playback queue. If media_id is provided it will add the track specified by that ID, otherwise it will add the container specified by container_id.

Parameters

player_id – Player ID
source_id – Source ID
container_id – Container ID
media_id – Media ID
add_type – Type of add to perform

Returns

None

async browse_source(source_id: int, options: Optional[int] = None, create_criteria: Optional[int] = None, item_range: Optional[tuple] = None) → list¶

Browses a music source and retrieves a list of the media it contains

Parameters

source_id – Source ID
options – Optional features
create_criteria – Options for creating new stations
item_range – Tuple specifying the start and end range to query

Returns

list of SourceMedia

async browse_source_container(source_id: Optional[int] = None, container_id: Optional[str] = None, item_range: Optional[tuple] = None) → list¶

Browses the specified Container on the specified Source.

Parameters

source_id – Source ID
container_id – Container ID
item_range – Tuple specifying the start and end range to query

Returns

list of SourceMedia

async delete_playlist(source_id: int, container_id: int)¶

Deletes a playlist container.

Parameters

source_id – Source ID
container_id – Container ID

Returns

None

async get_music_sources() → list¶

Retrieve a list of music sources.

Returns: list

async get_search_criteria(source_id: int) → list¶

Retrieves the search criteria settings for the specified music source.

Parameters: source_id – Source ID
Returns: list of SearchCriteria

async get_source_info(source_id: int) → Optional[pytheos.models.source.Source]¶

Retrieve information on the specified Source ID

Parameters: source_id – Source ID
Returns: MusicSource or None if not found

async play_station(player_id: int, source_id: int, container_id: str, media_id: str, name: str)¶

Starts playing the specified music station. Media ID must be from media of the ‘station’ type.

Parameters

player_id – Player ID
source_id – Source ID
container_id – Container ID
media_id – Media ID
name – Station name returned by browse

Returns

None

async play_preset(player_id: int, preset: int)¶

Plays one of the configured presets/favorites.

Parameters

player_id – Player ID
preset – Preset number

Returns

None

async play_input(player_id: int, input_name: str, source_player_id: Optional[int] = None)¶

Plays the specified input source on the provided Player ID. Other speakers can be targeted if the optional Source Player ID is provided.

Parameters

player_id – Player ID
input_name – Input name
source_player_id – Source Player ID

Returns

None

async play_url(player_id: str, url: str)¶

Play the specified URL

Parameters

player_id – Player ID
url – URL string

Returns

None

async rename_playlist(source_id: int, container_id: int, name: str)¶

Renames a playlist container.

Parameters

source_id – Source ID
container_id – Container ID
name – New playlist name

Returns

None

async retrieve_metadata(source_id: int, container_id: int) → list¶

Retrieves image data for a specific container. This only applies to Rhapsody and Napster.

Parameters

source_id – Source ID
container_id – Container ID

Returns

AlbumMetadata

async search(source_id: int, query: str, search_criteria_id: int) → list¶

Search the source for a given string using the specified search criteria ID.

FIXME: Can’t get this working with my current setup - keep getting a -10 system error when searching Plex.

Parameters

source_id – Source ID
query – String to search for. May include wildcards if the search criteria does.
search_criteria_id – Search Criteria ID

Returns

list of SourceMedia

async set_service_option(source_id: int, option: pytheos.models.browse.ServiceOption, **kwargs) → pytheos.models.heos.HEOSResult ¶

Sets a service option.

Parameters

source_id – Source ID
option – Option to set
kwargs – Optional parameters used by individual service options

Returns

HEOSResult

`pytheos.api.group` Module¶

class pytheos.api.group.GroupAPI(conn)¶

Bases: object

API interface for the ‘group’ command group

VOLUME_MIN = 0¶

VOLUME_MAX = 100¶

VOLUME_STEP_MIN = 1¶

VOLUME_STEP_MAX = 10¶

async get_groups() → list¶

Retrieves a list of all groups.

Returns: list

async get_group_info(group_id: int) → pytheos.models.group.Group ¶

Retrieves the group information for the specified group.

Parameters: group_id – Group ID
Returns: Group

async get_mute(group_id: int) → bool¶

Returns whether or not the group is currently muted

Parameters: group_id – Group ID
Returns: bool

async get_volume(group_id: int) → int¶

Retrieves the current volume

Parameters: group_id – Group ID
Returns: int

async set_group(leader_id: int, member_ids=None) → Optional[pytheos.models.group.Group]¶

Sets up a group leader and associated member players.

Parameters

leader_id – Leader ID
member_ids – List of Member IDs or None to delete the group

Returns

Group if a group was created or modified, None if it was deleted

async set_mute(group_id: int, enable: bool) → None¶

Enables or disables mute on the specified group

Parameters

group_id – Group ID
enable – True or False

Returns

None

async set_volume(group_id: int, level: int) → None¶

Sets the volume level on the group

Parameters

group_id – Group ID
level – Volume level

Raises

ValueError

Returns

None

async toggle_mute(group_id: int) → None¶

Toggles mute on the group

Parameters: group_id – Group ID
Returns: None

async volume_up(group_id: int, step_level: int = 5) → None¶

Turn the volume up by the specified step level.

Parameters

group_id – Group ID
step_level – Step level

Raises

ValueError

Returns

None

async volume_down(group_id: int, step_level: int = 5) → None¶

Turn the volume down by the specified step level.

Parameters

group_id – Group ID
step_level – Step level

Raises

ValueError

Returns

None

`pytheos.api.player` Module¶

Provides the API abstraction for the ‘player’ command group

class pytheos.api.player.PlayerAPI(conn)¶

Bases: object

API interface for the ‘player’ command group

VOLUME_MIN = 0¶

VOLUME_MAX = 100¶

VOLUME_DEFAULT_STEP = 5¶

async check_update(player_id: int) → bool¶

Checks whether or not there is an update available for the player

Parameters: player_id – Player ID
Returns: bool

async clear_queue(player_id: int) → None¶

Clears the current play queue

Parameters: player_id – Player ID
Returns: None

async get_mute(player_id: int) → bool¶

Returns whether or not the player is currently muted

Parameters: player_id – Player ID
Returns: bool

async get_now_playing_media(player_id: int) → pytheos.models.media.MediaItem ¶

Returns details of the currently playing media

Parameters: player_id – PlayerID
Returns: MediaItem

async get_players() → List[pytheos.models.player.Player]¶

Retrieves a list of players that are available

Returns: list

async get_player_info(player_id: int) → pytheos.models.player.Player ¶

Retrieves the Player information for a given ID

Parameters: player_id – Player ID
Returns: Player

async get_play_mode(player_id: int) → pytheos.models.player.PlayMode ¶

Returns the current play mode flags - repeat & shuffle

Parameters: player_id – Player ID
Returns: PlayMode

async get_play_state(player_id: int) → pytheos.models.player.PlayState ¶

Retrieves the current playing state (e.g. play, pause, stop)

Parameters: player_id – Player ID
Raises: InvalidResponse
Returns: str

async get_queue(player_id: int, range_start: int = 0, number_to_retrieve: int = 100) → list¶

Retrieves the current play queue

Parameters

player_id – Player ID
range_start – Optional range to start retrieving from
number_to_retrieve – Number of items to retrieve

Raises

ValueError

Returns

list

async get_quickselects(player_id: int, quick_select_id: Optional[int] = None) → list¶

Retrieves a list of quick select entries - LEGO AVR or HEOS BAR only

Parameters

player_id – Player ID
quick_select_id – QuickSelect ID

Raises

ValueError

Returns

list

async get_volume(player_id: int) → int¶

Retrieves the current volume

Parameters: player_id – Player ID
Returns: int

async move_queue_item(player_id: int, queue_ids: tuple, destination_queue_id: int)¶

Moves the specified queue IDs to the location specified by the destination queue ID.

Parameters

player_id – Player ID
queue_ids – Tuple of Queue IDs
destination_queue_id – Destination Queue ID

Raises

ValueError –

Returns

None

async play_next(player_id: int) → None¶

Plays the next item in the play queue

Parameters: player_id – Player ID
Returns: None

async play_previous(player_id: int) → None¶

Plays the previous item in the play queue

Parameters: player_id – Player ID
Returns: None

async play_queue(player_id: int, queue_entry_id: int) → None¶

Plays the specified queue item

Parameters

player_id – Player ID
queue_entry_id – Queue entry ID

Returns

None

async play_quickselect(player_id: int, quick_select_id: int) → None¶

Play the specified QuickSelect ID

Parameters

player_id – Player ID
quick_select_id – QuickSelect ID

Raises

ValueError

Returns

None

async remove_from_queue(player_id: int, queue_ids: Union[list, tuple, set]) → None¶

Remove a set of items from the queue

Parameters

player_id – Player ID
queue_ids – Queue IDs

Returns

None

async save_queue(player_id: int, playlist_name: str) → None¶

Saves the current queue as a playlist

Parameters

player_id – Player ID
playlist_name – Playlist name

Raises

ValueError

Returns

None

async set_mute(player_id: int, enable: bool) → None¶

Enables or disables mute on the specified player

Parameters

player_id – Player ID
enable – True or False

Returns

None

async set_play_mode(player_id: int, play_mode: pytheos.models.player.PlayMode) → None¶

Sets the play mode for the specified player - repeat & shuffle

Parameters

player_id – Player ID
play_mode – PlayMode

Returns

None

async set_quickselect(player_id: int, quickselect_id: int) → None¶

Selects the specified Quick Select

Parameters

player_id – Player ID
quickselect_id – QuickSelect ID

Raises

ValueError

Returns

None

async set_play_state(player_id: int, state: pytheos.models.player.PlayState) → None¶

Set the current playing state for the player

Parameters

player_id – Player ID
state – Play state

Raises

ValueError

Returns

None

async set_volume(player_id: int, level: int) → None¶

Sets the volume level on the player

Parameters

player_id – Player ID
level – Volume level

Raises

ValueError

Returns

None

async toggle_mute(player_id: int) → None¶

Toggles mute on the player

Parameters: player_id – Player ID
Returns: None

async volume_up(player_id: int, step_level: int = 5) → None¶

Turn the volume up by the specified step level.

Parameters

player_id – Player ID
step_level – Step level

Raises

ValueError

Returns

None

async volume_down(player_id: int, step_level: int = 5) → None¶

Turn the volume down by the specified step level.

Parameters

player_id – Player ID
step_level – Step level

Raises

ValueError

Returns

None

`pytheos.api.system` Module¶

Provides the API abstraction for the ‘system’ command group

class pytheos.api.system.SystemAPI(conn)¶

Bases: object

API interface for the ‘system’ command group

async check_account() → tuple¶

Determines whether or not the system is currently signed in

Returns: (status, username)

async heart_beat() → None¶

Executes the heart_beat command

Returns: None

async prettify_json_response(enable: bool) → None¶

Enables or disables pretty JSON responses

Parameters: enable – True or False
Returns: None

async reboot() → None¶

Forces the system to reboot

Returns: None

async register_for_change_events(enable: bool) → None¶

Registers the current connection to receive events from HEOS.

Parameters: enable – True or False
Returns: None

async sign_in(username: str, password: str) → None¶

Commands the system to sign-in to HEOS

Parameters

username – Username
password – Password

Raises

SignInFailedError

Returns

None

async sign_out() → None¶

Commands the system to sign out of HEOS.

Returns: None

pytheos.api Package¶

`pytheos.api.browse` Module¶

`pytheos.api.group` Module¶

`pytheos.api.player` Module¶

`pytheos.api.system` Module¶

Table of Contents

Previous topic

Next topic

This Page

pytheos.api Package¶

pytheos.api.browse Module¶

pytheos.api.group Module¶

pytheos.api.player Module¶

pytheos.api.system Module¶

`pytheos.api.browse` Module¶

`pytheos.api.group` Module¶

`pytheos.api.player` Module¶

`pytheos.api.system` Module¶