soco-cli 0.4.83__tar.gz → 0.4.84__tar.gz

{soco_cli-0.4.83/soco_cli.egg-info → soco_cli-0.4.84}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soco-cli
-Version: 0.4.83
+Version: 0.4.84
 Summary: Sonos command line control utility, based on SoCo
 Author-email: Avantrec Ltd <soco_cli@avantrec.com>
 Project-URL: Homepage, https://github.com/avantrec/soco-cli
@@ -12,7 +12,7 @@ Requires-Python: >=3.5
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: soco==0.27.1; python_version < "3.6"
-Requires-Dist: soco>=0.30.13; python_version >= "3.6"
+Requires-Dist: soco>=0.31.0; python_version >= "3.6"
 Requires-Dist: ifaddr==0.1.7; python_version < "3.7"
 Requires-Dist: ifaddr>=0.2.0; python_version >= "3.7"
 Requires-Dist: tabulate

{soco_cli-0.4.83 → soco_cli-0.4.84}/README.md

@@ -29,7 +29,7 @@
       * [Queue Actions](#queue-actions)
       * [Favourites and Playlists](#favourites-and-playlists)
       * [TuneIn Radio Station Favourites](#tunein-radio-station-favourites)
-      * [Grouping and Stereo Pairing](#grouping-and-stereo-pairing)
+      * [Grouping, Stereo Pairing, and Surround (Satellite) Speakers](#grouping-stereo-pairing-and-surround-satellite-speakers)
       * [Alarms](#alarms)
       * [Music Library Search Functions](#music-library-search-functions)
       * [Speaker and Sonos System Information](#speaker-and-sonos-system-information)
@@ -85,7 +85,7 @@
    * [Resources](#resources)
 
 <!-- Created by https://github.com/ekalinin/github-markdown-toc -->
-<!-- Added by: pwt, at: Sun May 19 15:54:07 BST 2024 -->
+<!-- Added by: pwt, at: Sun Apr  5 10:16:32 BST 2026 -->
 
 <!--te-->
 
@@ -197,7 +197,7 @@ alias ss="sonos Study"
 alias sd="sonos-discover"
 ```
 
-This allows the use of shorthand like `sk stop`, to stop playback on the Kitchen speaker. Note, however, that this won't work with sequences of commands using a single `sonos` invocation, separated with ` : ` (see [Multiple Sequential Commands](#multiple-sequential-commands)), only for the first command in such a sequence. (Normal, mutiple `sonos` invocation, shell sequences using `;` or `&&` as separators will work, of course.)
+This allows the use of shorthand like `sk stop`, to stop playback on the Kitchen speaker. Note, however, that this won't work with sequences of commands using a single `sonos` invocation, separated with ` : ` (see [Multiple Sequential Commands](#multiple-sequential-commands)), only for the first command in such a sequence. (Normal, multiple `sonos` invocation, shell sequences using `;` or `&&` as separators will work, of course.)
 
 ### Options for the `sonos` Command
 
@@ -348,7 +348,7 @@ sonos Kitchen play_from_queue 5
 - **`bass`**: Returns the bass setting of the speaker, from -10 to 10.
 - **`bass <number>`**: Sets the bass setting of the speaker to `<number>`. Values must be between -10 and 10.
 - **`dialog_mode`** (or **`dialog`**, **`dialogue_mode`**, **`dialogue`**): Returns the dialog mode setting of the speaker, 'on' or 'off' (if applicable).
-- **`dialog_mode <on|off>`** (or **`dialog`**, **`dialogue_mode`**, **`dialogue`**): Sets the dialog mode setting of the speaker to 'on' of 'off' (if applicable).
+- **`dialog_mode <on|off>`** (or **`dialog`**, **`dialogue_mode`**, **`dialogue`**): Sets the dialog mode setting of the speaker to 'on' or 'off' (if applicable).
 - **`fixed_volume`**: Returns whether the speaker's Fixed Volume feature is enabled, 'on' or 'off'. (Applies to Sonos Connect and Port devices only.)
 - **`fixed_volume <on|off>`**: Sets whether the speaker's Fixed Volume feature is enabled.   
 - **`group_mute`**: Returns the group mute state of a group of speakers, 'on' or 'off'.
@@ -365,9 +365,9 @@ sonos Kitchen play_from_queue 5
 - **`night_mode <on|off>`** (or **`night`**): Sets the night mode setting of the speaker to 'on' or 'off' (if applicable).
 - **`playing_tv`** (or **`is_playing_tv`**): Returns whether the speaker is currently playing from its TV input source, 'yes' or 'no'.
 - **`ramp_to_volume <volume>` (or `ramp`)**: Gently raise or reduce the volume to `<volume>`, which is between 0 and 100. Returns the number of seconds to complete the ramp.
-- **`relative_bass <adjustment>` (or `rel_bass`, `rb`)** Increase or reduce the bass setting by `<adjustment>`, a value between -10 and 10.
-- **`relative_sub_gain <adjustment>` (or `rel_sub_gain`, `rsg`)** Increase or reduce a Sub's gain setting by `<adjustment>`, a value between -15 and 15.
-- **`relative_treble <adjustment>` (or `rel_treble`, `rt`)** Increase or reduce the treble setting by `<adjustment>`, a value between -10 and 10.
+- **`relative_bass <adjustment>` (or `rel_bass`, `rb`)**: Increase or reduce the bass setting by `<adjustment>`, a value between -10 and 10.
+- **`relative_sub_gain <adjustment>` (or `rel_sub_gain`, `rsg`)**: Increase or reduce a Sub's gain setting by `<adjustment>`, a value between -15 and 15.
+- **`relative_treble <adjustment>` (or `rel_treble`, `rt`)**: Increase or reduce the treble setting by `<adjustment>`, a value between -10 and 10.
 - **`relative_volume <adjustment>` (or `rel_vol`, `rv`)**: Raises or lowers the volume by `<adjustment>`, which must be a number from -100 to 100.
 - **`sub_enabled`**: Returns `on` if the zone's subwoofer is enabled, otherwise `off`.
 - **`sub_enabled <on|off>`**: Enables or disables a zone's subwoofer.
@@ -382,10 +382,10 @@ sonos Kitchen play_from_queue 5
 - **`surround_volume_tv`**: Reports the value of the volume level for surround speakers, when playing TV sources, from `-15` to `+15`.
 - **`surround_volume_tv <level>`**: Sets the value of the volume level for surround speakers, when playing TV sources, from `-15` to `+15`.
 - **`treble`**: Returns the treble setting of the speaker, from -10 to 10.
-- **`treble <number>`**: Sets the bass setting of the speaker to `<number>`. Values must be between -10 and 10.
+- **`treble <number>`**: Sets the treble setting of the speaker to `<number>`. Values must be between -10 and 10.
 - **`trueplay`**: Returns whether a speaker's Trueplay profile is enabled, 'on' or 'off'.
 - **`trueplay <on|off>`**: Sets whether a speaker's Trueplay profile is enabled. Can only be set to 'on' for speakers that have a current Trueplay tuning profile available.
-- **`volume` (or `vol`)**: Returns the current volume setting of the speaker (0 to 100)
+- **`volume` (or `vol`)**: Returns the current volume setting of the speaker (0 to 100).
 - **`volume <volume>` (or `vol`)**: Sets the volume of the speaker to `<volume>` (0 to 100).
 
 ### Playback Control
@@ -455,7 +455,7 @@ When items are added to the queue successfully, the queue position of the first
 The available actions are:
 
 - **`add_playlist_to_queue <playlist_name> [<position>]`** (or **`queue_playlist`, `add_pl_to_queue`, `apq`**): Add `<playlist_name>` to the queue. Name matching is case-insensitive, and will work on partial matches.
-- **`add_library_playlist_to_queue <playlist_name> ]<position>]`** (or **`alpq`**): As above, but targets local library imported playlists instead of Sonos playlists.
+- **`add_library_playlist_to_queue <playlist_name> [<position>]`** (or **`alpq`**): As above, but targets local library imported playlists instead of Sonos playlists.
 - **`add_sharelink_to_queue <sharelink> [<position>]`** (or **`sharelink`**): Add a **Spotify**, **Tidal**, **Deezer**, or **Apple Music** link (for a track, album, playlist, etc.) to the queue. Returns the queue position of the first track. Supported links formats are: `https://open.spotify.com/track/6cpcorzV5cmVjBsuAXq4wD`, `spotify:album:6wiUBliPe76YAVpNEdidpY`, `https://tidal.com/browse/album/157273956`, `https://www.deezer.com/en/playlist/5390258182`, `https://music.apple.com/dk/album/black-velvet/217502930?i=217503142`.
 - **`add_uri_to_queue <uri> [<position>]`** Adds a URI to the queue.
 - **`clear_queue`** (or **`cq`**): Clears the current queue
@@ -503,12 +503,14 @@ The following operate on the stations in TuneIn's 'My Radio Stations' list.
 - **`play_favourite_radio_station <station_name>`** (or **`play_favorite_radio_station`, `pfrs`**): Play a favourite radio station.
 - **`play_fav_radio_station_no <station_number>`** (or **`pfrsn`**): Play a favourite radio station by its number.
 
-### Grouping and Stereo Pairing
+### Grouping, Stereo Pairing, and Surround (Satellite) Speakers
 
+- **`add_satellite_speakers <left_rear_speaker> <right_rear_speaker>`** (or **`add_satellites`**): Bonds `<left_rear_speaker>` and `<right_rear_speaker>` as rear satellite speakers to the target soundbar. The target speaker must be a soundbar. Example: `sonos "Arc" add_satellites "Era 100 L" "Era 100 R"`.
 - **`group <master_speaker>`(or `g`)**: Groups the speaker with `<master_speaker>`, which acts as the coordinator.
 - **`multi_group <slave_speaker> [<slave_speaker> ...]`**: Groups one or more speakers with the target speaker, which acts as the coordinator.
 - **`pair <right_hand_speaker>`**: Creates a stereo pair, where the target speaker becomes the left-hand speaker of the pair and `<right_hand_speaker>` becomes the right-hand of the pair. Can be used to pair dissimilar Sonos devices (e.g., to stereo-pair a Play:1 with a One). The left-hand speaker becomes the coordinator speaker, and the stereo pair will adopt its name.
 - **`party_mode` (or `party`)**: Adds all speakers in the system into a single group. The target speaker becomes the group coordinator. Remove speakers individually using `ungroup`, or use `ungroup_all`.
+- **`separate_satellite_speakers`** (or **`separate_satellites`**): Removes all bonded satellite speakers from the target soundbar. The target speaker must be a soundbar. Note: this will reset the Trueplay tuning for the device.
 - **`transfer_playback <target_speaker>` (or `transfer_to`, `transfer`)**: Transfers playback to <target_speaker>. This is achieved by grouping and ungrouping the speakers, and swapping the group coordinator. It's a convenience shortcut for `speaker1 group speaker2 : speaker1 ungroup`.
 - **`ungroup` (or `ug`, `u`)**: Removes the speaker from a group.
 - **`ungroup_all`**: Removes all speakers in the target speaker's household from all groups.
@@ -932,7 +934,7 @@ Note that if you have speakers with the same names in multiple Sonos systems (Ho
 
 ### Refreshing the Local Speaker List
 
-If your speakers change in some way (e.g., they are renamed, are assigned different IP addresses, or you add/remove speakers), you can refresh the discovery cache using the `--refresh-speaker-list` or `-r` option. Note that this option only has an effect when combined with the `-l` option. You can also use the `sonos-discover` command (below).
+If your speakers change in some way (e.g., they are renamed, are assigned different IP addresses, or you add/remove speakers), you can refresh the discovery cache using the `--refresh-local-speaker-list` or `-r` option. Note that this option only has an effect when combined with the `-l` option. You can also use the `sonos-discover` command (below).
 
 **Example:** `sonos -lr "living room" volume 50` will refresh the discovery cache before executing the `sonos` command.
 
@@ -1203,7 +1205,7 @@ The macro file can be reloaded using the `/macros/reload` endpoint (e.g.: `http:
 Successful invocation of a macro will return the sonos command that was executed, and the result(s) of the actions that were performed (or the error output(s) in the case of a failure), in JSON format, e.g.:
 
 ```
-{"command": "sonos Kitchen volume", result": "30"}
+{"command": "sonos Kitchen volume", "result": "30"}
 ```
 
 #### Listing Macros

{soco_cli-0.4.83 → soco_cli-0.4.84}/requirements.txt

@@ -1,5 +1,5 @@
 soco == 0.27.1; python_version < "3.6"
-soco >= 0.30.13; python_version >= "3.6"
+soco >= 0.31.0; python_version >= "3.6"
 ifaddr == 0.1.7; python_version < "3.7"
 ifaddr >= 0.2.0; python_version >= "3.7"
 tabulate

{soco_cli-0.4.83 → soco_cli-0.4.84}/soco_cli/__init__.py

@@ -10,4 +10,4 @@ server, to control Sonos via HTTP requests.
 For more information, please see: https://github.com/avantrec/soco-cli
 """
 
-__version__ = "0.4.83"
+__version__ = "0.4.84"

{soco_cli-0.4.83 → soco_cli-0.4.84}/soco_cli/action_processor.py

@@ -929,6 +929,22 @@ def group_or_pair(speaker, action, args, soco_function, use_local_speaker_list):
     return True
 
 
+@two_parameters
+def add_satellite_speakers(
+    speaker, action, args, soco_function, use_local_speaker_list
+):
+    left_rear = get_speaker(args[0], use_local_speaker_list)
+    if not left_rear:
+        error_report("Speaker '{}' not found".format(args[0]))
+        return False
+    right_rear = get_speaker(args[1], use_local_speaker_list)
+    if not right_rear:
+        error_report("Speaker '{}' not found".format(args[1]))
+        return False
+    getattr(speaker, soco_function)(left_rear, right_rear)
+    return True
+
+
 @one_or_more_parameters
 def multi_group(speaker, action, args, soco_function, use_local_speaker_list):
     """
@@ -2991,6 +3007,16 @@ actions = {
     "groups": SonosFunction(groups, "groups"),
     "pair": SonosFunction(group_or_pair, "create_stereo_pair"),
     "unpair": SonosFunction(no_args_no_output, "separate_stereo_pair"),
+    "add_satellite_speakers": SonosFunction(
+        add_satellite_speakers, "add_satellite_speakers"
+    ),
+    "add_satellites": SonosFunction(add_satellite_speakers, "add_satellite_speakers"),
+    "separate_satellite_speakers": SonosFunction(
+        no_args_no_output, "separate_satellite_speakers"
+    ),
+    "separate_satellites": SonosFunction(
+        no_args_no_output, "separate_satellite_speakers"
+    ),
     "delete_playlist": SonosFunction(playlist_operations, "remove_sonos_playlist"),
     "remove_playlist": SonosFunction(playlist_operations, "remove_sonos_playlist"),
     "clear_playlist": SonosFunction(playlist_operations, "clear_sonos_playlist"),

{soco_cli-0.4.83 → soco_cli-0.4.84}/soco_cli/interactive.py

@@ -37,10 +37,12 @@ from soco_cli.keystroke_capture import get_keystroke
 from soco_cli.utils import (
     RewindableList,
     docs,
+    get_ctrl_c_interrupted,
     get_readline_history,
     get_speaker,
     local_speaker_list,
     save_readline_history,
+    set_ctrl_c_interrupted,
     set_interactive,
     set_single_keystroke,
     set_suspend_sighandling,
@@ -311,8 +313,8 @@ def interactive_loop(
                     continue
 
                 if command_lower == "exec":
-                    if len(command) > 1:
-                        _exec(command[1:])
+                    if len(command) > 1 and _exec(command[1:]):
+                        break
                     continue
 
                 if command_lower == "cd":
@@ -489,7 +491,8 @@ def interactive_loop(
                         action in ACTIONS_TO_EXEC
                         or action in ACTIONS_TO_EXEC_NO_SPEAKER
                     ):
-                        _exec_action(speaker.ip_address, action, args)
+                        if _exec_action(speaker.ip_address, action, args):
+                            break
                     else:
                         exit_code, output, error_msg = run_command(
                             speaker,
@@ -820,11 +823,14 @@ def _rescan(use_local_speaker_list=False, max_scan=False):
         print("Rescan failed: please check your network connection [{}]".format(e))
 
 
-def _exec(command_args: List[str]) -> None:
+def _exec(command_args: List[str]) -> bool:
     """Runs a command as a subprocess, in its own shell.
 
     Args:
         command_args (list): The command to execute.
+
+    Returns:
+        bool: True if the subprocess was interrupted by CTRL-C, False otherwise.
     """
 
     # Check for spaces within any of the command line args,
@@ -836,6 +842,7 @@ def _exec(command_args: List[str]) -> None:
     # Convert command list to a unified command line
     command_line = " ".join(command_args)
 
+    set_ctrl_c_interrupted(False)
     set_suspend_sighandling(suspend=True)
     try:
         logging.info("Running command: '{}'".format(command_line))
@@ -843,12 +850,13 @@ def _exec(command_args: List[str]) -> None:
     except Exception as e:
         print(e)
     set_suspend_sighandling(suspend=False)
+    return get_ctrl_c_interrupted()
 
 
 CTRL_C_MSG_ISSUED = False
 
 
-def _exec_action(speaker_ip: str, action: str, args: List[str]) -> None:
+def _exec_action(speaker_ip: str, action: str, args: List[str]) -> bool:
     # Commands to run in a subprocess, to allow CTRL-C
     # to exit the subprocess only, and not the shell.
 
@@ -865,7 +873,7 @@ def _exec_action(speaker_ip: str, action: str, args: List[str]) -> None:
         print("(Use CTRL-C to return to the Sonos shell prompt.)")
         CTRL_C_MSG_ISSUED = True
 
-    _exec(command_line)
+    return _exec(command_line)
 
 
 def _exec_command_line(command_line: str) -> None:

{soco_cli-0.4.83 → soco_cli-0.4.84}/soco_cli/utils.py

@@ -260,6 +260,19 @@ def set_suspend_sighandling(suspend=True):
     suspend_sighandling = suspend
 
 
+# Flag set when CTRL-C interrupts a suspended-sighandling subprocess
+_ctrl_c_interrupted = False
+
+
+def set_ctrl_c_interrupted(value=True):
+    global _ctrl_c_interrupted
+    _ctrl_c_interrupted = value
+
+
+def get_ctrl_c_interrupted():
+    return _ctrl_c_interrupted
+
+
 # Stop a stream if playing a local file
 speaker_playing_local_file = None
 
@@ -279,6 +292,8 @@ def sig_handler(signal_received, frame):
     logging.info("Caught signal: {}".format(signal_received))
 
     if suspend_sighandling:
+        if signal_received == signal.SIGINT:
+            set_ctrl_c_interrupted(True)
         logging.info("Signal handling suspended ... ignoring")
         return
 

{soco_cli-0.4.83 → soco_cli-0.4.84/soco_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soco-cli
-Version: 0.4.83
+Version: 0.4.84
 Summary: Sonos command line control utility, based on SoCo
 Author-email: Avantrec Ltd <soco_cli@avantrec.com>
 Project-URL: Homepage, https://github.com/avantrec/soco-cli
@@ -12,7 +12,7 @@ Requires-Python: >=3.5
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: soco==0.27.1; python_version < "3.6"
-Requires-Dist: soco>=0.30.13; python_version >= "3.6"
+Requires-Dist: soco>=0.31.0; python_version >= "3.6"
 Requires-Dist: ifaddr==0.1.7; python_version < "3.7"
 Requires-Dist: ifaddr>=0.2.0; python_version >= "3.7"
 Requires-Dist: tabulate

{soco_cli-0.4.83 → soco_cli-0.4.84}/soco_cli.egg-info/SOURCES.txt

@@ -35,4 +35,5 @@ soco_cli.egg-info/entry_points.txt
 soco_cli.egg-info/requires.txt
 soco_cli.egg-info/top_level.txt
 tests/test_cli.py
+tests/test_comprehensive.py
 tests/test_utils.py

{soco_cli-0.4.83 → soco_cli-0.4.84}/soco_cli.egg-info/requires.txt

@@ -9,7 +9,7 @@ soco==0.27.1
 ifaddr==0.1.7
 
 [:python_version >= "3.6"]
-soco>=0.30.13
+soco>=0.31.0
 
 [:python_version >= "3.7"]
 ifaddr>=0.2.0