Release 1.0.0

This version implements all of the functionality documented in the HEOS CLI Protocol specification (version at this time 1.21 dated 10/06/2024). There are breaking changes from previous versions. See notes below.

Fixes/improvements: 🐛

• Invocation of the command_error callbacks now occur outside of the held lock for commands so that other commands could be called within the callback.
• When matching players after a refresh, serial is first used (if available), before matching on player_id or name.
• Connection retry logic now implements a doubling incremental backoff with a maximum delay of 10min.

New: 🚀

const Module:

• Added service option constants (e.g. SERVICE_OPTION_THUMBS_UP)

error module:

• Added CommandAuthenticationError a subclass of CommandFailedError which is raised when an auth-related error occurs calling a command.

Heos class:

• Added get_group_info method to retrieve or refresh a specific group. If all groups are loaded, this will retrieve the cached instance, unless refresh=True.
• Added get_player_info function to retrieve a specific player and optionally refresh and update an existing instance.
• Added check_update that returns True is a firmware update is available for the player, otherwise False.
• Added player_get_queue to retrieve the specified player's queue items.
• Added player_play_queue to play a specific queue index on the specified player.
• Added player_remove_from_queue to remove one or more items from the specified player's queue
• Added player_save_queue to save the specified player's queue as a playlist.
• Added player_move_queue_item to move items in the specified player's queue.
• Added get_music_source_info to retrieve or refresh a specific music source.
• Added get_search_criteria to obtain search options for a given source.
• Added search to perform a search against a source with specific criteria.
• Added rename_playlist to rename a playlist.
• Added delete_playlist to delete a playlist.
• Added retrieve_metadata to retrieve album metadata.
• Added set_service_option to call a service option, such as thumbs up.
• Added multi_search to search multiple sources and criteria.
• Added add_search_to_queue to add items to the queue for the specified player based on the search string.

HeosGroup class:

• Added parameter refresh_base_info: bool = True to refresh method to include updating the base information about the group (name, id, leader, members) in addition to mute and volume.

HeosPlayer class:

• Added parameter refresh_base_info: bool = True to refresh to optionally pull the latest player information, such as name.
• Added group_id field to represent the group reference the player is a member of, otherwise None.
• Added check_update that returns True is an update is available for the player, otherwise `False.
• Added get_queue to retrieve the player's queue items.
• Added play_queue to play a specific queue index on the player.
• Added remove_from_queue to remove one or more items from the player's queue
• Added save_queue to save the current queue as a playlist.
• Added move_queue_item to move items in the queue.
• Added control property to indicate the volume control type when lineout is Fixed.
• Added add_search_to_queue to add items to the queue for the current player based on the search string.

HeosNowPlayingMedia class:

• New attribute options: Sequence[ServiceOption] to list available service options.

Media module:

• New class ServiceOption for describing a service option.
• BrowseResult now has options: Sequence[ServiceOption] attribute to list available service options.
• New classes ImageMetadata, AlbumMetadata, and RetreiveMetadataResult to represent album metadata.

Search module:

• New classes SearchCriteria, SearchResult, MultiSearchResult, and SearchStatistic to represent output of search commands.

types Module:

• Contains all of the enumeration types, centralized from the library.
• Added ConnectionState enum to replace connection state constants (e.g. STATE_CONNECTED)
• Added ControlType enum to replace play control constants (e.g. CONTROL_PLAY)
• Added NetworkType enum to replace network connection constants (e.g. NETWORK_TYPE_WIFI)
• Added SignalType enum to replace signal constants (e.g. SIGNAL_HEOS_EVENT)
• Added SignalHeosEvent enum to replace event constants (e.g. EVENT_CONNECTED)
• Added LineOutLevelType and VolumeControlType

Changed ⏸️

const module:

• Removed connection state const (e.g. STATE_CONNECTED). Use ConnectionState instead.
• Removed control consts (e.g. CONTROL_PLAY). Use ControlType instead.
• Removed network connection constants (e.g. NETWORK_TYPE_WIFI). Use NetworkType instead.
• Removed signal constants (.e.g SIGNAL_HEOS_EVENT). Use SignalType instead.
• Removed dispatched event consts (.e.g EVENT_CONNECTED). Use SignalHeosEvent instead.

Heos class:

• Function load_players now returns an instance of PlayerUpdateResult instead of a dictionary.

HeosPlayer class:

• Field lineout is now an enum of type LineOutLevelType

Full Changelog: 0.9.0...1.0.0

RC1 1.0.0

Release Candidate 1 for version 1.0.0.

What's Changed

• Fix deadlock when calling command within command_error handler by @andrewsayre in #59
• Add remaining Group commands by @andrewsayre in #61
• Add Get Player Info by @andrewsayre in #63
• Add check update command by @andrewsayre in #64
• Add Player Queue Commands by @andrewsayre in #65
• Add remaining browse commands by @andrewsayre in #68
• Refactor consts by @andrewsayre in #71
• Add enums for player fields by @andrewsayre in #73
• Refactor internals by @andrewsayre in #76
• Add incremental backoff by @andrewsayre in #78
• Add add_search_to_queue by @andrewsayre in #80
• Combine mixins with command creation by @andrewsayre in #82

Full Changelog: 0.9.0...1.0.0-rc1

Release 0.9.0

What's Changed

Fixed

• url is no longer quoted in play_url

New

General

• Python 3.13 support
• Updates for HEOS CLI 1.21

const module:

• MediaType added to represent media types.
• RepeatType added to represent repeat options.
• AddCriteriaType added to represent queue add criteria.
• PlayState added to represent play state.
• MUSIC_SOURCE_CONNCECT for Tidal/Sonos connect
• INPUT_SOURCE_1 through INPUT_SOURCE_18

media module:

• New class Media represents a common base-type for music sources and media items.
• MediaMusicSource represents a root-level music source, returned from Heos.get_music_sources and includes function browse to enumerate child items.
• MediaItem represents non-root sources, and all other media types (containers, playlists, albums, stations, etc...). Function browse is used to enumerate child items when browsable=True
• BrowseResult represents the result of a browse operation and includes the items returned as well as record count information.

Heos class:

• New update_credential parameter to sign_in and sign_out to indicate that the set credential should be updated and used on a reconnect attempt. Defaults to True.
• current_credentials property exposes the currently stored credentials, whether passed in through options, or updated as the result of a sign_in or sign_out call.
• browse for browsing media item by identifiers.
• browse_media for browsing a MediaMusicSource or MediaItem.
• play_media for playing an instance of MediaItem. This function will call the correct underlying function to switch the input, play the stream, or add the item to the queue.
• play_input_source to play an specific input source.
• play_station to play a station
• play_preset_station to play a favorite
• play_url to play a URL
• add_to_queue to add an item to the queue
• reboot to reboot the connected device.
• add_on_controller_event, add_on_heos_event, add_on_connected, add_on_disconnected, add_on_user_credentials_invalid for connecting event handlers.

MediaItem class:

• play_media for playing the current item on a player. This function will call the correct underlying function to switch the input, play the stream, or add the item to the queue.

HeosPlayer class:

• add_to_queue to add an item to the player queue
• play_media for playing an instance of MediaItem. This function will call the correct underlying function to switch the input, play the stream, or add the item to the queue.
• add_on_player_event for connecting event handlers

Breaking changes

The following items were changed or removed in the library and may represent a breaking change, depending on usage.

const module:

• SOURCE_CONTROLS now uses enum values from const.MediaType instead of discrete music source constants.
• Removed music source constants: TYPE_MUSIC_SERVICE, TYPE_STATION, TYPE_SONG, TYPE_HEOS_SERVICE, TYPE_PLAYLIST. Use const.MediaType instead.
• Removed repeat constants: REPEAT_ON_ALL, REPEAT_ON_ONE, REPEAT_OFF, VALID_REPEAT_MODES. Use const.RepeatType instead.
• Removed queue criteria constants: ADD_QUEUE_PLAY_NOW, ADD_QUEUE_PLAY_NEXT, ADD_QUEUE_ADD_TO_END, ADD_QUEUE_REPLACE_AND_PLAY, and VALID_ADD_QUEUE_OPTIONS. Use the new enum AddCriteriaType.
• Removed player state constants: PLAY_STATE_PLAY, PLAY_STATE_PAUSE, PLAY_STATE_STOP, and VALID_PLAY_STATES. Use the new enum PlayState.

Heos class:

• get_music_sources now returns dict[int, MediaMusicSource]
• get_input_sources now returns Sequence[MediaItem]
• get_favorites now returns dict[int, MediaItem]
• get_playlists now returns Sequence[MediaItem]
• music_sources now returns dict[int, MediaMusicSource]

HeosPlayer class:

• set_play_mode method parameter repeat is now of type const.RepeatType
• play_input_source method parameter input_source is now of type MediaItem
• add_to_queue method parameter source renamed to media: MediaItem
• repeat property is now of type const.RepeatType
• Renamed play_input to play_input_source for consistency.
• Renamed play_favorite to play_preset_station for consistency.

source module:

This entire module has been removed. The functionality has been replaced by the media module. In most cases, this represents a change to the class only -- property name and functions remain the same from their former counterparts.

• Removed HeosSource. Root level music sources are now represented by MediaMusicSource. All other source and media types are now represented by MediaItem
• Removed InputSource. Now represented by MediaItem.

Detailed changes

• Add ability to update credentials by @andrewsayre in #36
• Add media browsing support by @andrewsayre in #37
• Enhance play media commands by @andrewsayre in #39
• Improve test suite by @andrewsayre in #42
• Refactor player commands by @andrewsayre in #44
• Refactor system commands by @andrewsayre in #46
• Change message encoding to support URLs with ? by @Michcioperz in #47
• Refactor group commands by @andrewsayre in #49
• Allow controls for TIDAL Connect by @klada in #31
• Add Python 3.13 support by @andrewsayre in #50
• Updates for HEOS CLI 1.21 by @andrewsayre in #52
• Feature auth failure eventing by @andrewsayre in #54
• Enhance eventing by @andrewsayre in #56
• Version v0.9.0 by @andrewsayre in #57

New Contributors

• @Michcioperz made their first contribution in #47
• @klada made their first contribution in #31

Full Changelog: 0.8.0...0.9.0

Release 0.8.0

Breaking changes

• The constructor of the Heos class has changed and now accepts an instance of HeosOptions instead of individual parameters.

What's Changed

• fix URL in setup.py by @dotlambda in #30
• Fix for incorrect connection status by @olalid in #29
• Add initial devcontainer file by @andrewsayre in #32
• Improve connection management logic and add login feature by @andrewsayre in #34
• Add feature to test a connection and obtain system info by @andrewsayre in #35

New Contributors

• @dotlambda made their first contribution in #30
• @olalid made their first contribution in #29

Full Changelog: 0.7.4...0.8.0

Release 0.7.4

What's Changed

• Update the available inputs for the HEOS CLI Protocol Specification Version 1.17. #23 and #27
• Replace lint and formatters with Ruff by @andrewsayre in #28

New Contributors

• @omarlatief made their first contribution in #23

Full Changelog: 0.7.3...0.7.4

Release 0.7.3

• Updated supported Python versions to 3.11 and 3.12
• Updated test dependencies

Release 0.7.2

• Update dependencies and environments (#17)

Release v0.7.1

• Remove tests from package distribution

Release v0.6.0

• Exceptions during connection and commands are now wrapped in an exception deriving from HeosException to prevent leaking of internal implementation. This is a breaking change.
• Conformity to v.1.14 of the CLI
• Updated requirements
• Fix get_playlists not populating source_id

Release 0.5.2

• Fix edge case where get_now_playing_media returns an empty payload and would result in a KeyError during load/refresh