search

avantrec / soco-cli

Command Line Interface to Control Sonos Sound Systems
Apache License 2.0
224 stars 12 forks source link
automation cli command-line soco sonos sonos-controller sonos-speakers

readme

SoCo-CLI: Control Sonos from the Command Line

Overview

SoCo-CLI is a powerful command line wrapper for the popular Python SoCo library [1], for controlling Sonos systems. SoCo-CLI is written entirely in Python and is portable across platforms.

A simple sonos command provides easy control over a huge range of speaker functions, including playback, volume, groups, EQ settings, sleep timers, alarms, speaker settings, the playback queue, etc. Multiple commands can be run in sequence, including the ability to insert delays between commands, to wait for speakers to stop or start playing, and to create repeated action sequences using loops. Audio files from the local filesystem can be played directly on Sonos.

SoCo-CLI has an orderly command structure and consistent return values, making it suitable for use in automated scripts, cron jobs, etc.

For interactive command line use, SoCo-CLI provides a powerful Interactive Shell Mode that improves speed of operation and reduces typing.

SoCo-CLI can be imported as a streamlined, high-level API library by other Python programs, and acts as an intermediate abstraction layer between the client program and the underlying SoCo library, simplifying the use of SoCo.

SoCo-CLI can also run as a simple HTTP API server, providing access to a huge range of actions via simple HTTP requests. (Requires Python 3.7 or above.)

Supported Environments

Installation

Install the latest version from PyPI [2] using pip install -U soco-cli.

Soco-CLI can also be easily installed as a self-contained application with pipx using pipx install soco-cli.

Please see the CHANGELOG.txt file for a list of the user-facing changes in each release.

User Guide

The sonos Command

The installer adds the sonos command to the PATH. If the sonos command is not found, make sure your PATH is set up correctly for the Python installation you want to use.

All commands have the form:

sonos SPEAKER ACTION <parameters>

As usual, command line arguments containing spaces must be surrounded by quotes: double quotes work on all supported OS platforms, while Linux and macOS also support single quotes.

The soco command is also added to the PATH, and can be used as an alias for the sonos command if preferred.

Actions that make changes to speakers do not generally provide return values. Instead, the program exit code can be inspected to test for successful operation (exit code 0). If an error is encountered, an error message will be printed to stderr, and the program will return a non-zero exit code. Note that sonos actions are executed without seeking user confirmation; please bear this in mind when manipulating the queue, playlists, etc.

Speaker Discovery by Name

SoCo-CLI will try a number of approaches to find a speaker's IP address by speaker name, which escalate in cost until the speaker is discovered or discovery fails. If SoCo-CLI seems slow to find speakers (especially if you have a multi-household Sonos system), or if you occasionally experience problems with speakers not being found, please take a look at the generally faster Cached Discovery method.

Simple Usage Examples

The SPKR Environment Variable

To avoid typing the speaker name, or to parameterise the use of SoCo-CLI commands, it's possible to use the SPKR environment variable instead of supplying the speaker name (or IP address) on the command line.

Example: The following will set up all sonos commands to operate on the "Front Reception" speaker:

Linux and macOS:

$ export SPKR="Front Reception"
$ sonos play
$ sonos wait_stop : volume 10

Windows:

C:\ set SPKR="Front Reception"
C:\ sonos play
C:\ sonos wait_stop : volume 10

IP addresses also work, e.g.: $ export SPKR=192.168.0.50.

If you want to ignore the SPKR environment variable for a specific sonos invocation, use the --no-env command line option.

Using Shell Aliases

If your shell supports it, shell aliasing can be very convenient in creating shortcuts to SoCo-CLI commands. For example, I have the following in my .zshrc file:

# Sonos Aliases
alias s="sonos"
alias sk="sonos Kitchen"
alias sr="sonos 'Rear Reception'"
alias sf="sonos 'Front Reception'"
alias sm="sonos Move"
alias sb="sonos Bedroom"
alias sb2="sonos 'Bedroom 2'"
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), only for the first command in such a sequence. (Normal, mutiple sonos invocation, shell sequences using ; or && as separators will work, of course.)

Options for the sonos Command

The following options are for use with the cached discovery mechanism:

Note that the sonos-discover utility (discussed below) can also be used to manage the local speaker list. This is the recommended way of using cached discovery: first run sonos-discover to create the local speaker database, then use sonos with the -l option to use the local database when invoking sonos actions.

If you set the environment variable USE_LOCAL_CACHE=TRUE, the --use_local_speaker_list option will always be used.

Firewall Rules

If you're running on a host with its firewall enabled, note that some SoCo-CLI actions require the following incoming ports to be open: TCP 1400-1499, TCP 54000-54099.

The TCP/1400 range is used to receive notification events from Sonos players (used in the wait_stop action, etc.), the TCP/54000 range is used for the built-in Python HTTP server when playing files from the local filesystem (used in the play_file action).

When opening ports, SoCo-CLI will try port numbers starting at the beginning of the range and incrementing by one until a free port is found, up to the limit of the range. This allows multiple invocations of SoCo-CLI to run in parallel on the same host.

The standard speaker discovery mechanism uses SSDP multicast (multicast address 239.255.255.250 on UDP port 1900). The outgoing port chosen for the multicast request is variable and OS-dependent, e.g., for most Linux distributions it's in the ephemeral port range 32768–60999. Multicast responses are returned to the outgoing port, so if the firewall blocks incoming UDP traffic on the relevant port range, then standard discovery will fail. SoCo-CLI will automatically fall back to using network scan discovery if standard discovery fails, but this is slower, so either adjust your firewall to open the relevant ports or consider using SoCo-CLI Cached Discovery.

If using the HTTP API Server functionality, its listen port must be open to incoming TCP requests. The default port is 8000.

Operating on All Speakers: Using _all_

There is a limited set of operations where it can be desirable to operate on all speakers, e.g., muting every speaker in the house. This is done by using _all_ as the speaker name. Operations will be performed on all visible devices.

Examples: sonos _all_ mute on and sonos _all_ relative_volume -10.

Note that _all_ can be used with every sonos operation: no checking is performed to ensure that the use of all is appropriate, so use with caution.

Redirection of Actions to Coordinator Devices

If an action is applied to a non-coordinator device, there are some cases where the action is automatically redirected to the coordinator. For example, if lounge is the coordinator speaker and kitchen is a grouped speaker:

Guidelines on Playing Content

SoCo-CLI enables playback of content from the Sonos Favourites and Sonos Playlists collections, from local libraries, and from the TuneIn 'My Radio Stations' list. It also allows playback of audio files from the local filesystem, and can add sharelinks from the Spotify, Tidal, Apple Music, and Deezer music services to the Sonos queue. On macOS, the contents of physical CDs can be played direct to Sonos.

Radio Stations

Radio stations can be played by adding them to your Sonos Favourites, and then starting playback using play_fav. Alternatively, stations can be added to the TuneIn 'My Radio Stations' list, and played using play_favourite_radio_station.

Single Tracks

As with radio stations, add single tracks from local libraries and music services to your Sonos Favourites, and play them using play_fav.

sonos <speaker_name> play_fav <favourite_name>

Tracks from local music libraries can also be added to the queue using sonos <speaker> queue_track <track_name>, which returns the queue position of the track. It can then be played using sonos <speaker> play_from_queue <track_number>.

Albums and Playlists

Albums and playlists from local libraries or music services can be added to your Sonos Playlists, and then played by adding them to the queue, followed by playing from the queue. For example:

sonos <speaker_name> clear_queue : <speaker_name> add_playlist_to_queue <playlist> : <speaker_name> play_from_queue

Or, to add to the current queue, then play the first playlist track:

sonos <speaker_name> add_playlist_to_queue <playlist>
24 <-- Returns queue position of the first playlist track
sonos <speaker_name> play_from_queue last_added

To add imported playlists from local libraries to the queue, use the add_library_playlist_to_queue action.

Albums from local music libraries can also be added to the queue using sonos <speaker> queue_album <album_name>. The action returns the queue position of the first track in the album, which can then be played as in the example above:

Audio Files on the Local Filesystem

It's possible to play local audio files in MP3, M4A, MP4, FLAC, OGG, WMA, WAV, and AIFF formats directly on your Sonos speakers using the play_file (or play_local_file) action.

Example: sonos Lounge play_file mozart.mp3

SoCo-CLI establishes a temporary internal HTTP server from which the specified audio file can be streamed, and then instructs the speaker to play it. The play_file action will terminate once playback stops. Note that playback can be paused using a Sonos app (or SoCo-CLI), and the HTTP server will remain active so that playback can be resumed.

Unfortunately, one can pause but not fully stop playback when using the Sonos apps. Hence, stop playback by playing something else on Sonos, by issuing a 'CTRL-C' to the active play_file action, or by issuing sonos <SPEAKER> stop from another command line. Alternatively, use the _end_on_pause_ option to terminate the play_file action if playback is paused.

The host running SoCo-CLI must remain on and connected to the network during playback, in order to serve the file to the speaker. The internal HTTP server is active only for the duration of the play_file action. For security reasons, it will only serve the specified audio file, and only to the IP addresses of the Sonos speakers in the system.

Multiple files can be played in sequence by providing multiple audio file names as parameters.

Example: sonos Lounge play_file one.mp3 two.mp3 three.mp3

Local Playlists (M3U Files)

The play_m3u (or play_local_m3u) action will play a local filesystem playlist in M3U (or M3U8) format. Files in the playlist should be available on the local filesystem; any that are not will be skipped. Simple lists of audio files in non-M3U format can also be supplied. Comments can be inserted in the file by prefixing each comment line with #.

There are options to print the track filenames as they are played, to shuffle the playlist, and to select a single random track from the playlist. There is also an interactive mode option, which allows (N)ext track, (P)ause playback, and (R)esume playback, while the playlist is being played.

Example: sonos Lounge play_m3u my_playlist.m3u, or, to print filenames and invoke interactive mode: sonos Lounge play_m3u my_playlist.m3u pi.

This feature works by invoking the play_file action for each file in the playlist in sequence, so the same rules apply as for play_file. Note that play_m3u does not create a Sonos queue on the speaker -- the 'queue' is managed locally by SoCo-CLI -- so it's not possible to skip forward or back using a Sonos app.

Directories of Audio Files

To play every audio file in a local directory, use the play_directory (or play_dir) action. As with the play_m3u action this invokes play_file for each valid audio file in the directory. It does not traverse into subdirectories.

Example: sonos Lounge play_directory "Music/Mozart/The Magic Flute/CD 1"

On macOS (but not on Windows or Linux), if you have an attached CD drive, this action can be used to play a CD directly to your Sonos speakers, e.g.:

sonos Lounge play_dir "/Volumes/Audio CD".

The play_file action can be used to play individual tracks on the CD, e.g.:

sonos Lounge play_file "/Volumes/Audio CD/1 Audio Track.aiff".

Spotify, Tidal, Deezer, and Apple Music Share Links

The add_sharelink_to_queue (or sharelink) action can be used to add share links from Spotify, Tidal, Deezer, or Apple Music to the queue, provided the Sonos system has a subscription to the required service.

Links can refer to tracks, albums, or playlists. The position of the first track added to the queue is returned, which can then be played using play_from_queue. Share links can be of the form:

Example:

sonos Kitchen sharelink "https://open.spotify.com/track/6cpcorzV5cmVjBsuAXq4wD"
5 <-- Returns queue position of first track
sonos Kitchen play_from_queue 5

Complete List of Available Actions

Volume and EQ Control

Playback Control

Queue Actions

When adding items to the queue, the default is to add the items at the end of the queue unless an optional <position> parameter is supplied, which can take one of the following values:

Examples:

sonos lounge queue_search_results all start  <-- 'start' is equivalent to '1'
sonos lounge queue_search_results 1-5,9 next
sonos lounge queue_search_results 1,3,4 end  <-- Note: 'end' can be omitted
sonos kitchen queue_album zooropa next

When items are added to the queue successfully, the queue position of the first added track is returned. Use play_from_queue with this track number to commence playback of the added items.

The available actions are:

The following has issues and requires further development. For example, it's currently possible to add radio stations to the queue!

Favourites and Playlists

TuneIn Radio Station Favourites

The following operate on the stations in TuneIn's 'My Radio Stations' list.

Grouping and Stereo Pairing

Alarms

Some SoCo-CLI alarm actions below require an alarm specification (alarm_spec), a comma-separated list of exactly eight parameters (without spaces next to the commas), which defines all the properties of an alarm. The parameters are as follows:

  1. Alarm start time, in hours and minutes using the 24hr clock: HH:MM
  2. Alarm duration in hours and minutes: HH:MM
  3. Recurrence: A valid recurrence string is DAILY, ONCE, WEEKDAYS, WEEKENDS or of the form ON_DDDDDD where D is a number from 0-6 representing a day of the week (Sunday is 0, Monday is 1, etc.), e.g., ON_034 means Sunday, Wednesday and Thursday
  4. Whether the alarm is enabled: ON or OFF (or YES, NO)
  5. What to play: CHIME (or chime) for the standard Sonos alarm sound, or a choice from your Sonos Favourites. Sonos Favourite matching will use case-insensitive, partial matches.
  6. Play mode: one of NORMAL, SHUFFLE_NOREPEAT, SHUFFLE, REPEAT_ALL, REPEAT_ONE, SHUFFLE_REPEAT_ONE (note that SHUFFLE means SHUFFLE and REPEAT)
  7. The volume to play at: 0-100

  8. Whether to include grouped speakers: ON or OFF (or YES, NO)

    Examples of alarm specifications:

    • 07:00,01:30,WEEKDAYS,ON,"Radio 4",NORMAL,50,OFF
    • 06:30,00:01,WEEKDAYS,ON,CHIME,NORMAL,50,OFF

In actions which modify (or copy and modify) an existing alarm, values that are to be left unchanged are denoted by an underscore in the alarm_spec. E.g., to change only the duration and volume of an alarm, use an alarm spec such as: _,01:00,_,_,_,_,60,_.

The alarm actions are as follows:

Music Library Search Functions

The actions below search the Sonos Music library.

Speaker and Sonos System Information

Multiple Sequential Commands

Chaining Commands Using the : Separator

Multiple commands can be run as part of the same sonos invocation by using the : separator to add multiple SPEAKER ACTION <parameters> sequences to the command line. The : separator must be surrounded by spaces to disambiguate from other uses of : in sonos actions.

The benefit of using this approach instead of multiple separate sonos commands is that the cost of starting the program is only incurred once. In addition, it allows for the introduction of wait states and loops.

An arbitrary number of commands can be supplied as part of a single sonos invocation. If a failure is encountered with any command, sonos will report the error, but will generally attempt to execute subsequent commands.

Example: sonos Kitchen volume 25 : Kitchen play

Inserting Delays: wait and wait_until

sonos wait <duration>
sonos wait_until <time>

The wait <duration> (or wait_for) action waits for the specified duration before moving on to the next command. Do not supply a speaker name. This action is useful when, for example, one wants to play audio for a specific period of time, or maintain a speaker grouping for a specific period then ungroup, etc.

<duration> can be one of seconds, minutes or hours. Floating point values for the duration are acceptable. Examples: wait 10s, wait 30m, wait 1.5h. (If the s/m/h is omitted, s (seconds) is assumed.) The time duration formats HH:MM and HH:MM:SS can also be used. Examples are wait 2:30 (waits 2hrs and 30mins), wait 0:1:25 (waits 1min 25secs).

The wait_until <time> action pauses sonos command line execution until the specified time, in 24hr HH:MM or HH:MM:SS format, for example wait_until 16:30.

Examples:

Waiting Until Playback has Started/Stopped: wait_start, wait_stop and wait_end_track

sonos <speaker> wait_start
sonos <speaker> wait_stop
sonos <speaker> wait_stop_not_pause
sonos <speaker> wait_end_track

The <speaker> wait_start and <speaker> wait_stop actions are used to pause execution of the sequence of sonos commands until a speaker has either started or stopped/paused playback. The wait_stop_not_pause (or wsnp) action is the same as wait_stop but ignores the 'paused' state, i.e., it only resumes when a speaker enters the stopped state.

For example, to reset the volume back to 25 only after the Bedroom speaker has stopped playing, use the following command sequence:

sonos Bedroom wait_stop : Bedroom volume 25

Note that if a speaker is already playing, wait_start will proceed immediately, and if a speaker is already stopped, wait_stop will proceed immediately. If the behaviour you want is to continue after the next piece of audio ends, then you can chain commands as shown in the following example:

sonos <speaker> wait_start : <speaker> wait_stop : <speaker> vol 50

The wait_end_track action will pause execution of sonos commands until the current track has ended, or until playback has otherwise paused or stopped. This is useful, for example, when one want to stop playback after the current track has ended:

sonos <speaker> wait_end_track : <speaker> stop

The wait_stopped_for <duration> Action

sonos <speaker> wait_stopped_for <duration>
sonos <speaker> wait_stopped_for_not_pause <duration>

The <speaker> wait_stopped_for <duration> (or wsf) action will wait until a speaker has stopped playback for <duration> (which uses the same time parameter formats as the wait action). If the speaker stops playback, but then restarts (any number of times) during <duration>, the timer will be reset to zero each time. Processing continues once the speaker has been stopped for a continuous period equalling the <duration>.

The <speaker> wait_stopped_for_not_pause <duration> (or wsfnp) action is the same, but ignores the 'paused' state.

This function is useful if one wants to perform an action on a speaker (such as ungrouping it) only once its use has definitely stopped, as opposed to it just being temporarily paused, or stopped while switched to a different audio source. For example:

sonos Study wait_stopped_for 5m : Study line_in on : Study play

Repeating Commands: The loop Actions

loop
loop <iterations>
loop_for <duration>
loop_until <time>
loop_to_start

The loop action loops back to the beginning of a sequence of commands and executes the sequence again. Do not supply a speaker name. In the absence of errors, loop will continue indefinitely until manually stopped.

To loop a specific number of times, use loop <iterations>, giving an integer number of iterations to perform before command processing continues. The number of iterations includes the one just performed, i.e., in the sequence sonos <speaker> vol 25: wait 1h : loop 2, the commands preceding the loop 2 action will be performed twice in total.

To loop for a specific period of time, use loop_for <duration>, where the format for <duration> follows the same rules as wait. Note that timer starts from the point when the loop statement is reached, not from the overall start of command execution.

To loop until a specific time, use loop_until <time>, where the format for <time> follows the same rules as wait_until.

Multiple loop statements can be used in sonos command sequence. For any given loop statement, command execution returns to the command immediately after the most recent loop, i.e., the loop executes the commands between the current loop action and the previous one. Note that loop 1 can be considered a null loop action, and can be useful in restricting the scope of a subsequent loop action.

The loop_to_start action will loop back to the very start of a command sequence. It takes no parameters.

Examples:

sonos Study wait_start : Study wait_stopped_for 10m : Study volume 25 : loop
sonos wait_until 22:00 : Bedroom play_fav "Radio 4" : Bedroom sleep 30m : loop 3
sonos Bedroom play_fav Jazz24 : Bedroom sleep 30m : wait 1h : loop_for 3h
sonos wait_until 08:00 : Kitchen play_fav "World Service" : Kitchen sleep 10m : wait 1h : loop_until 12:01

Conditional Command Execution

The following modifiers are available that will invoke or suppress an action depending on the state of the target speaker:

sonos <speaker> if_stopped <action> <parameters>
sonos <speaker> if_playing <action> <parameters>
sonos <speaker> if_coordinator <action> <parameters>
sonos <speaker> if_not_coordinator <action> <parameters>
sonos <speaker> if_queue <action> <parameters>
sonos <speaker> if_no_queue <action> <parameters>

The if_stopped modifier will execute the action that follows it only if the speaker is not currently playing. If the speaker is playing, the action will be skipped, and the next command in the sequence (if applicable) will be executed immediately. For example, to set the volume of a speaker back to a default value only if the speaker is not playing, use:

sonos <speaker> if_stopped volume 25

No action will be taken if the speaker is playing, and the command will terminate immediately.

Similarly, the if_playing modifier will execute the action that follows it only if the speaker is currently playing.

The if_coordinator modifier will execute the action that follows only if the target speaker is a coordinator. The if_not_coordinator modifier will execute the action that follows only if the target speaker is not a coordinator. Note that many actions are automatically redirected to the coordinator speaker, so this modifier may not be required, depending on your use case.

The if_queue modifier will execute the action that follows it only if the speaker's queue has one or more items in it. Similarly, the if_no_queue modifier will execute the following action only if the speaker's queue is empty.

Modifiers can be combined and will be evaluated in left to right sequence. All modifiers must be true for the action to be invoked. E.g.:

sonos <speaker> if_no_queue if_stopped <action> <parameters>

Interactive Shell Mode

sonos -i <speaker_name>
sonos --interactive <speaker_name>
sonos -i

Description

Interactive shell mode creates a SoCo-CLI command line session for entering sonos commands. Compared to using individual sonos invocations, using the shell is faster to perform operations, and requires less typing.

Most sonos actions are accepted. Multiple actions can be submitted on a single command line using the : separator. Command aliases can be created for commonly used actions and sequences of actions. A single-keystroke mode allows action invocations using one touch of the keyboard.

Usage

Interactive mode is started with the -i or --interactive command line option. Optionally, a speaker name can be given, in which case all commands will be directed to that speaker (until changed in the shell).

Type help or ? at the sonos command line for more information on using interactive shell mode:

$ sonos -i

Entering SoCo-CLI interactive shell.
Type 'help' for available shell commands.

Sonos [] > help

This is SoCo-CLI interactive mode. Interactive commands are as follows:

    '1', ...     :  Set the active speaker. Use the numbers shown by the
                    'speakers' command. E.g., to set to speaker number 4
                    in the list, just type '4'.
                    '0' will unset the active speaker.
    'actions'    :  Show the complete list of SoCo-CLI actions.
    'alias'      :  Add an alias: alias <alias_name> <actions>
                    Remove an alias: alias <alias_name>
                    Update an alias by creating a new alias with the same name.
                    Using 'alias' without parameters shows the current list of
                    aliases.
                    Aliases override existing actions and can contain
                    sequences of actions.
    'cd'         :  Change the working directory of the shell, e.g. 'cd ..'.
                    Note that on Windows, backslashes must be doubled, e.g.:
                    'cd C:\\'
    'check_for_update' : Check whether an update is available
    'docs'       :  Print a link to the online documentation.
    'exec'       :  Run a shell command, e.g.: 'exec ls -l'.
    'exit'       :  Exit the shell.
    'help'       :  Show this help message (available shell commands).
    'pop'        :  Restore saved active speaker state.
    'push'       :  Save the current active speaker, and unset the active
                    speaker.
    'rescan'     :  If your speaker doesn't appear in the 'speakers' list,
                    use this to perform a more comprehensive scan.
    'rescan_max' :  Try this if you're still having trouble finding all your
                    speakers.
    'set <spkr>' :  Set the active speaker using its name.
                    Use quotes when needed for the speaker name, e.g.,
                    'set "Front Reception"'. Unambiguous, partial,
                    case-insensitive matches are supported, e.g., 'set front'.
                    To unset the active speaker, omit the speaker name,
                    or just enter '0'.
    'sk'         :  Enters 'single keystroke' mode. (Also 'single-keystroke'.)
    'speakers'   :  List the names of all available speakers.
    'version'    :  Print the versions of SoCo-CLI, SoCo, and Python in use.

    The action syntax is the same as when using 'sonos' from the command line.
    If a speaker has been set in the shell, omit the speaker name from the
    action.

    Use the arrow keys for command history and command editing.

    [Not Available on Windows] Use the TAB key for autocompletion of shell
    commands, SoCo-CLI actions, aliases, and speaker names.

Sonos [] >

Shell History and Auto-Completion

Commands in the shell history can be scrolled through by using the up/down arrows, and commands can be edited using the left/right arrows to position the cursor.

(Not available on Windows) Shell commands can be auto-completed using the TAB key. The shell history is saved between shell sessions in ~/.soco-cli/shell-history.txt.

Shell Aliases

Shell aliases allow the creation of shortcuts for individual actions or sequences of actions. Aliases are created using:

> alias <alias_name> <alias_action> [ : <alias_action>]

For example, to create an alias action sequence go that sets the volume of the active speaker to '50', starts playback, and then shows the track name, use:

> alias go volume 50 : play : track

Aliases are run by using the alias name, e.g.: > go.

Aliases are included in autocompletion results, and they override built-in commands and actions of the same name (so they can be used to remap commands and actions).

Aliases are saved between sessions, using a file in the ~/.soco-cli directory.

Push and Pop

The push and pop commands are useful in alias actions when one wants to target actions at other speakers, but keep the current active speaker when the action sequence ends. push saves the current speaker and unsets it, and pop reselects the saved speaker, e.g.:

> alias fv push : set "Front Reception" : volume 50 : pfrs "Jazz 24" : pop

This command sequence targets the 'Front Reception' speaker, but first saves the current active speaker, restoring it at the end. (This will, of course, still work if the current active speaker is 'Front Reception'.)

Alias Subroutines

Aliases can include other aliases in their sequences of actions, e.g.:

> alias alias_1 vol 30 : play
> alias alias_2 push : set Kitchen : alias_1 : pop 
> alias_2

Alias subroutines can be nested to an arbitrary depth. Loops are detected and prevented when an alias with a loop is invoked.

Alias Arguments

Aliases accept arguments when invoked, which is helpful in remapping existing actions to new alias names. Arguments are specified positionally using %1, %2, etc. For example:

> alias a1 pfq %1
> a1 5          <- Invokes 'pfq 5'
>
> alias a2 push : Kitchen volume %1 : Bathroom volume %1 : pop
>
> a2 30         <- Invokes 'Kitchen volume 30 : Bathroom volume 30'
                   (surrounded by a push/pop to save the current target
                   speaker).

If positional arguments are not specified, values will not be passed through. Unsatisfied positional arguments are ignored. For example:

> alias a1 vol %1 %2
>
> a1            <- Invokes 'vol'
> a1 50         <- Invokes 'vol 50'
> a1 50 50      <- Invokes 'vol 50 50' (and generates an error).

Positional arguments can be used multiple times within an action (unlikely to be useful) or within a sequence of actions.

Saving and Loading Aliases

sonos --save_aliases <filename>
sonos --load_aliases <filename>
sonos --overwrite_aliases <filename>

Aliases can be exported to, and loaded from, plain text files using the command line options above. The command will terminate once the file operation is complete. Option save_aliases will export the current aliases to the supplied filename; load_aliases will load a list of aliases and merge them with the current list (overwriting any duplicate alias names); overwrite_aliases will overwrite all current aliases with the list from the file.

The alias file format consists of lines containing <alias_name> = <alias actions>, e.g:

# This is a comment line
my_alias = vol 30 : play_fav "Radio 4"
p = pauseplay

# Blank lines are OK
m = mute on

Single Keystroke Mode

Single keystroke mode allows the shell to be controlled by single character presses on the keyboard, without requiring the return key to be pressed. This is useful for some headless automation use cases, as well as sometimes being convenient for interactive use. All single character actions are available, including aliases.

Enable by using the action sk or single-keystroke at the shell prompt. Type x to exit back to the normal shell.

To start SoCo-CLI in single keystroke mode, use the command line option --sk, along with the interactive (-i or --interactive) option.

Cached Discovery

SoCo-CLI uses the full range of speaker discovery mechanisms in SoCo to look up speakers by their names to determine their IP addresses.

First, the native Sonos SSDP multicast discovery process is tried.

If this fails, SoCo-CLI will try scanning every IP address on your local network(s) to find the speaker; it's likely to be doing this some of the time if your network contains multiple Sonos systems (multiple 'households'), or if the network has problems with multicast forwarding. This can be slower than is desirable, so SoCo-CLI also provides an alternative process that scans the complete local network for Sonos devices as a one-off process, and then caches the results in a local file for use in future operations.

It's often faster and more convenient to use the local cached speaker list. The disadvantage of using the cached discovery mechanism is that the speaker list can become stale due to speakers being added/removed/renamed, or IP addresses having changed, meaning the cached list must be refreshed. The sonos-discover command, discussed below, is a convenient way of doing this.

Usage

To use the cached discovery mechanism with sonos, use the --use-local-speaker-list or -l flag. The first time this flag is used, the discovery process will be initiated. This will take a few seconds to complete, after which the sonos command will execute. A local speaker list is stored in <your_home_directory>/.soco-cli/ for use with future invocations of the sonos command.

Example: sonos -l "living room" volume 50 uses the local speaker database to look up the "living room" speaker.

When executing a sequence of commands, supply the -l option only for the first speaker and it will be used for all speaker lookups, e.g.:

sonos -l kitchen wait_stop : kitchen vol 25 : study play_favourite "Radio 4"

Speaker Naming

Speaker naming does not need to be exact. Matching is case-insensitive, and works on substrings. For example, if you have a speaker named Front Reception, then "front reception" or just front will match, as will any unambiguous substring. If an ambiguously matchable name is supplied then an error will be returned.

Note that if you have speakers with the same names in multiple Sonos systems (Households), SoCo-CLI will fail because it cannot disambiguate the speakers. Speakers should have unique names within a network (or fall back on using IP addresses instead of speaker names).

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).

Example: sonos -lr "living room" volume 50 will refresh the discovery cache before executing the sonos command.

Discovery Options

The following flags can be used to adjust network discovery behaviour if the discovery process is failing:

These options only have an effect when combined with the -l and -r options.

Example: sonos -lr -t 256 -n 1.0 "living room" volume 50

The sonos-discover Command

sonos-discover is a separate command for creating/updating the local speaker cache, and for seeing the results of the discovery process. It's an alternative to using the sonos -r command. It accepts the same -t, -n and -m options as the sonos command.

Example: sonos-discover -t 256 -n 1.0 -m 24 will run sonos-discover with a maximum of 256 threads, a network timeout of 1.0s, a minimum netmask of 24 bits, and will print the result.

Options for the sonos-discover Command

Without options, sonos-discover will execute the discovery process and print out its results. It will create a speaker cache file, or replace it if already present.

Discovery works by interrogating all network adapters on the device running SoCo-CLI, to build a list of the IP addresses to search for Sonos speakers. If your speakers reside on a subnet that is not directly attached (e.g., they're on a separate VLAN), then use the --subnets option to specify manually which networks to search.

Options:

The SoCo-CLI HTTP API Server

(Note that this functionality requires Python 3.7 or above.)

sonos-http-api-server
soco-http-api-server

SoCo-CLI can be run as a simple HTTP API server, allowing most of its features to be accessed via HTTP requests. It's very simple to run the server and to construct HTTP requests that invoke it.

Server Usage

The server is started using the sonos-http-api-server or soco-http-api-server commands:

% sonos-http-api-server
SoCo-CLI: Starting SoCo-CLI HTTP API Server v0.4.41
SoCo-CLI: Finding speakers ... ['Bedroom', 'Front Reception', 'Kitchen', 'Study']
SoCo-CLI: Macro: Attempting to (re)load macros from '/Users/pwt/macros.txt'
SoCo-CLI: Macro: Loaded macros:
          ...
INFO:     Started server process [52137]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

By default, the server listens for incoming requests on port 8000. This can be changed using the --port (or -p) command line option (e.g., sonos-http-api-server -p 51000). The listen port must be available, otherwise the server will terminate with an error.

If accessing the HTTP server from another machine on the network, make sure that your firewall allows incoming TCP requests on your chosen port.

For each request, the server will report the equivalent sonos command line (if applicable), execute the sonos command, and report the exit code/error, followed by the URL requested and the HTTP response code, e.g.:

SoCo-CLI: Command = 'sonos Study volume', exit code = 0
INFO:     127.0.0.1:51017 - "GET /study/volume HTTP/1.1" 200 OK
SoCo-CLI: Command = 'sonos Study volume 30', exit code = 0
INFO:     127.0.0.1:64948 - "GET /Study/volume/30 HTTP/1.1" 200 OK

The server will continue running until stopped using CTRL-C (etc.).

Using the Local Speaker Cache

To use the local speaker cache file instead of speaker discovery, start the HTTP API server with the --use-local-speaker-list or -l command line option.

When using this option, it's also possible to supply a --subnets command line specification, which will be used in the event of a /rediscover operation. The use of this option is described in the usage guide for sonos-discover.

The --subnets option only has an effect when using the local speaker cache, and the results of any /rediscover operations will overwrite the existing local speaker cache file.

Example of use with both options:

sonos-http-api-server -l --subnets=192.168.0.1/24

HTTP Request Structure

All requests are simple HTTP GET requests. Request URLs have the form:

http://<server>:<port>/<speaker_name>/<action>[/parameter_1/parameter_2/parameter_3]

Strings with characters that are invalid within URLs should be substituted by their URL-friendly replacements (e.g., space should be replaced by %20, comma by %2C, apostrophe by %27, and colon by %3A).

Usage examples:

http://192.168.0.100:8000/Study/volume
http://192.168.0.100:8000/Study/volume/50
http://192.168.0.100:8000/Front%20Reception/pause
http://192.168.0.100:8000/Kitchen/group/Hallway
http://192.168.0.100:8000/Kitchen/line_in/Lounge/right_input

Return Values

Return values are supplied in JSON format, and always contain the same fields. A formatted example is shown below:

{
  "speaker": "Study",
  "action": "volume",
  "args": [],
  "exit_code": 0,
  "result": "35",
  "error_msg": ""
}

The speaker, action, and args fields confirm the data that was sent in the HTTP request, with the speaker's name replaced by its full Sonos name if a shortened version was used in the invocation URL.

The exit_code field is an integer. This will be zero if the command completed successfully, and non-zero otherwise. (Note that the HTTP response code will indicate success (200) even if the SoCo-CLI action fails, so inspect the exit_code for failure detection.)

If the command is successful, the result field contains the result string, which is exactly the string that would have been printed if the action had been performed on the command line.

If the command is unsuccessful, the error_msg field contains an error message describing the error.

Asynchronous Actions (Experimental)

It's sometimes useful for the HTTP API server to respond immediately while its invoked action continues to run in the background. For example, if one wants to invoke a play_file action, and have the server respond immediately while the file is played in separate process.

This can be achieved by prefixing the action with async_. For example:

http://192.168.0.100:8000/Kitchen/async_play_file/my_file.mp3

Note that the data returned in this case is probably not useful: it will simply indicate whether the background command was invoked successfully, not whether the command was successful.

Async actions are mutually exclusive for a given speaker: any running async action will be cancelled if a new async action is invoked.

The async_ functionality does not (yet) apply to the Macros feature described below.

Macros: Defining Custom HTTP API Server Actions

The macros feature allows the creation of custom actions or sequences of actions to be executed by the HTTP API server, and available at the /macro/<macro_name> endpoint. Macros are defined in a text file that is loaded when the server starts, and which can subsequently be reloaded using the /macros/reload endpoint.

Macro Definition and Usage

Macro definitions take the form of the macro name followed by an equals sign (=), then the action(s) to be performed. Comments can be included by using # as the first character of a line, and blank lines are ignored. For example, the contents of a macro definition file might be:

# SoCo-CLI HTTP API Server Macros file
# Format is:
#   macro_name = speaker <action> <parameters> [: speaker <action> <parameters> ...]

# Play the doorbell sound on all speakers
doorbell = Hallway party_mode : Hallway play_file doorbell.mp3 : Hallway ungroup_all

# Group speakers in the morning, and start a favourite radio station
morning = Bathroom group Bedroom : Kitchen group Bedroom : Bedroom play_favourite "Radio 4"

# Set the volume and start playback of a favourite
front_R3 = "Front Reception" volume 50 : "Front Reception" play_favourite "Radio 3"

The macros above would be invoked using URLs of the form:

http://192.168.0.100:8000/macro/doorbell
http://192.168.0.100:8000/macro/morning
http://192.168.0.100:8000/macro/front_R3

Macro names are case-sensitive, and should not contain spaces or special characters except for underscores (_) and dashes (-).

Speaker names should ideally use the exact speaker name, including capitalisation, and using enclosing quotes where necessary. Shortened names will work, but will be less efficient. (Note: this does not apply when using the local speaker cache option.)

Macro Arguments

Macros can be parameterised using up to twelve positional arguments, specified in macro definitions by the terms %1 to %12. The general form for supplying the arguments when the macro is invoked is:

http://192.168.0.100:8000/macro/<macro_name>/<arg_1>/<arg_2>/<arg_3>/<arg_4>/... etc.

For example, a macro definition to set all the speakers on one floor to a specified volume could be defined as:

lower_floor_volume = Kitchen volume %1 : Hallway volume %1 : "Living Room" volume %1

The macro is then invoked using:

http://192.168.0.100:8000/macro/lower_floor_volume/30

Or to use different volumes for each speaker, the macro definition might be:

lower_floor_volume = Kitchen volume %1 : Hallway volume %2 : "Living Room" volume %3

and the macro invocation would take the form:

http://192.168.0.100:8000/macro/lower_floor_volume/30/40/25

If a macro argument needs to be supplied, but should be ignored during macro processing, then use an underscore _ as the argument to be ignored. E.g. to ignore %2 when processing a macro, use a URL of the form:

http://192.168.0.100:8000/macro/lower_floor_volume/30/_/25

Using the Generic Macro

There's a built-in generic macro called __ that simply maps to %1 %2 %3 %4 %5 %6 %7 %8 %9 %10 %11 %12. This can be used to create arbitrary command sequences. For example, to run the equivalent of:

sonos diner volume 30 : diner play_favourite "radio 4"

use the following HTTP request (replacing the : command sequence separator with %3A):

http://192.168.0.100:8000/macro/__/diner/volume/30/%3A/diner/play_favourite/radio%204

Troubleshooting

There is comprehensive server-side logging that reports the macro being invoked, the arguments supplied, the substitutions performed, and the sonos command line that is assembled and executed. This is helpful for troubleshooting. E.g., processing the following URL:

http://192.168.0.100:8000/macro/test_1/Study/volume/_/Peter%27s%20Room/volume

might generate the following server-side output:

SoCo-CLI: Macro: Processing macro 'test_1' = '%1 %2 %3 : %4 %5'
SoCo-CLI: Macro: Parameter variables supplied: ['Study', 'volume', '_', "Peter's Room", 'volume']
SoCo-CLI: Macro: Parameter variables used: ['%1', '%2', '%4', '%5'] -> ['Study', 'volume', '"Peter\'s Room"', 'volume']
SoCo-CLI: Macro: Parameter variables ignored or not supplied for: ['%3']
SoCo-CLI: Macro: Parameter variables supplied but ignored or not used: ['%3'] -> ['_']
SoCo-CLI: Macro: Substituting speaker name 'Study' by IP address '192.168.0.39'
SoCo-CLI: Macro: Substituting speaker name 'Peter's Room' by IP address '192.168.0.42'
SoCo-CLI: Macro: Executing: 'sonos 192.168.0.39 volume : 192.168.0.42 volume' in a subprocess
SoCo-CLI: Macro: Exit code = 0
INFO:     192.168.0.100:61548 - "GET /macro/test_1/Study/volume/_/Peter%27s%20Room/volume HTTP/1.1" 200 OK

Specifying the Macro Definition File

By default, the HTTP API server will look for a file named macros.txt in the directory from which it's invoked (the presence of the file is optional). If instead you wish to use a specific macros file, use the --macros or -m option when starting the server, followed by the name of the macros file, e.g.:

sonos-http-api-server --macros my_macros.txt

Reloading the Macro Definition File

The macro file can be reloaded using the /macros/reload endpoint (e.g.: http://192.168.0.100:8000/macros/reload). This will reload the macros from the original macros file, and overwrite any that are already installed. The new list of macros will be returned in JSON format.

Return Values

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"}

Listing Macros

The macros/list endpoint (e.g.: http://192.168.0.100:8000/macros/list) will return a JSON list of the macros installed in the server.

Listing Speakers

To list the available speakers, use the /speakers endpoint, e.g.: http://192.168.0.100:8000/speakers. The returned JSON string will list the speakers.

Rediscovering Speakers

If the configuration of your speakers changes in some way (e.g., if speakers are renamed or if there are IP address changes), the server can be instructed to reload its speaker data using the /rediscover endpoint, e.g.: http://192.168.0.100:8000/rediscover. The returned JSON string will list the speakers discovered.

If using the local speaker cache option, the speaker cache file will be overwritten with the new discovery results.

Inspecting the HTTP API

The HTTP API can be inspected and tested using its OpenAPI live documentation, at the /docs endpoint, e.g.:http://192.168.0.100:8000/docs

Using SoCo-CLI as a Python Library

If you'd like to use SoCo-CLI as a high-level library in another Python program, it's simple to do so using its API capability. The goal is to provide the same added value, abstractions, and command structure as when using SoCo-CLI directly from the command line. Essentially, there is a single entry point that accepts exactly the same commands that would be used on the command line.

Using the SoCo-CLI API means that the expense of loading SoCo-CLI is incurred only once during the operation of your program, and speaker discovery results are cached for efficiency.

Note that the native SoCo library can be used alongside the SoCo-CLI API, as needed.

Importing the API

Import SoCo-CLI in your Python code as follows:

from soco_cli import api

Using the API

The API entry point is *`api.run_command(speaker_name, action, args, use_local_speaker_list)`**, which takes exactly the same parameters as would be provided on the command line:

Parameters:

Return Values:

Each run_command() invocation returns a three tuple consisting of exit_code (int), output_string (str), and error_msg (str). If the exit code is 0, the command completed successfully, and the command output (if any) is contained in the output_string. If the exit code is non-zero, the command did not complete successfully and error_msg will be populated while output_string will not.

The output_string return value contains exactly what would have been printed to the console if the command had been run from the command line.

The public API function definitions include type annotations, to enable type checking with the utility of your choice (e.g., mypy).

Examples of use:

exit_code, output, error = api.run_command("Kitchen", "volume")
exit_code, output, error = api.run_command("Study", "mute", "on")
exit_code, output, error = api.run_command("Study", "group", "Kitchen")
exit_code, output, error = api.run_command("Front Reception", "play_favourite", "Radio 6")

Convenience Functions

There are some simple additional convenience functions provided by SoCo-CLI. The use of these functions is optional.

Known Issues

Please report any problems you find using GitHub Issues [3].

Uninstalling

  1. Use the normal Pip approach to uninstall the SoCo-CLI package: pip uninstall soco-cli.
  2. As usual, Pip will not remove dependencies. If you'd like to perform an exhaustive removal, inspect the requirements.txt files for soco-cli, and for SoCo. Take care not to remove packages that may also be required by other installed packages.
  3. You may also need to remove the directory .soco-cli and its contents from your home directory.

Acknowledgments

Developed with PyCharm. Earlier versions benefited from a free Professional licence for open source development from JetBrains.

All trademarks acknowledged. Avantrec Ltd has no connection with Sonos Inc.

Resources

[1] https://github.com/SoCo/SoCo \ [2] https://pypi.org/project/soco-cli \ [3] https://github.com/avantrec/soco-cli/issues