Sonos command line utility, based on SoCo
Project description
Soco CLI: Control Sonos Systems from the Command Line
Warning: Please consider this utility to be experimental at the moment. The code is immature and requires cleanup, and the command line structure and return values are not yet fully stable.
Overview
Soco CLI is a command line wrapper for the popular Python SoCo library [1], used to develop control programs for Sonos systems. Soco CLI is written entirely in Python and is portable across platforms.
A simple sonos
command is provided which allows easy control of speaker playback, volume, groups, EQ settings, sleep timers, etc.
Sonos CLI aims for an orderly command structure and consistent return values, making it suitable for use in scripted automation scenarios, cron
jobs, etc.
Sonos CLI depends on the speaker discovery mechanisms in SoCo (unless one knows and uses the speaker IP addresses directly). This should work for most people, but there are issues (related to multicast forwarding) on some networks that cause problems. There is also an issue if there is more than one Sonos system ('Household') on the same network, as would be the case with a 'split' S1/S2 Sonos system: SoCo discovery will pick one of the systems, and your required speaker may not be in that system.
To overcome these issues, Soco CLI provides an alternative discovery mechanism that scans the network for Sonos devices without depending on multicast, and which works with multiple systems on the same network. See Alternative Discovery below if the standard SoCo discovery doesn't work for you.
Supported Environments
- Requires Python 3.5 or greater.
- Should run on all platforms supported by Python. Tested on various versions of Linux, macOS and Windows.
Installation
Install from PyPi [2] using pip install soco-cli
.
User Guide
The installer puts the sonos
command on the PATH. All commands have the form:
sonos SPEAKER ACTION <parameters_required_by_action>
SPEAKER
identifies the speaker, and can be the speaker's Sonos Room name or its IPv4 address in dotted decimal format. Note that the speaker name is case sensitive (unless using alternative discovery, discussed below).ACTION
is the operation to perform on the speaker. It can take zero or more parameters depending on the operation.
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, a short error message will be printed to stderr
, and the program will return a non-zero exit code.
Simple Usage Examples:
sonos "Living Room" volume
Returns the current volume setting of the Living Room speaker.sonos Study volume 25
Sets the volume of the Study speaker to 25.sonos Study group Den
Groups the Study speaker with the Den.sonos 192.168.0.10 mute
Returns the mute state ('on' or 'off') of the speaker at the given IP address.sonos 192.168.0.10 mute on
Mutes the speaker at the given IP address.
Available Actions
balance
: Returns the balance setting of the speaker as a pair of values (L, R) where each of L and R is between 0 and 100.balance <L:number> <R:number>
: Sets the balance of the speaker to. L and R must be between 0 and 100. (Examples: L=100, R=100 is level balance; L=0, R=100 drives the right channel only, etc.)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.cross_fade
: Returns the cross fade setting of the speaker, 'on' or 'off'.cross_fade <on|off>
: Sets the cross fade setting of the speaker to 'on' of 'off'.favourite <favourite_name>
(orfavorite
,fav
): Plays the Sonos favourite identified by<favourite_name>
. The name is loosely matched; if<favourite_name>
is a (case insensitive) substring of a Sonos favourite, it will match. In the case of duplicates, the first match encountered will be used. Note: this currently works only for certain types of favourite: local library tracks and playlists, radio stations, single Spotify tracks, etc.group <master_speaker>
: Groups the speaker with<master_speaker>
.group_mute
: Returns the group mute state of a group of speakers, 'on' or 'off'.group_mute <on|off>
: Sets the group mute state of a group of speakers to 'on' or 'off'.groups
: Lists all groups in the Sonos system. Also includes single speakers as groups of one, and paired/bonded sets as groups.group_relative_volume <adjustment>
(orgroup_rel_vol
): Raises or lowers the group volume by which must be a number from -100 to 100.group_volume
(orgroup_vol
): Returns the current group volume setting of the speaker's group (0 to 100)grouo_volume <volume>
(orgroup_vol
): Sets the volume of the speaker's group to<volume>
(0 to 100).info
: Provides detailed information on the speaker's settings, current state, software version, IP address, etc.line_in
: Returns a speaker's Line-In state, 'on' if its input is set to Line-In, 'off' otherwise.line_in on
: Switch a speaker to its Line-In input (if applicable). Note that this does not start Line_in playback; issue theplay
action to start Line-In playback.line_in on <line_in_speaker
: Switch a speaker to the Line-In input of<line_in_speaker>
(if applicable). Note that this does not start Line_in playback; issue theplay
action to start Line-In playback.loudness
: Returns the loudness setting of the speaker, 'on' or 'off'.loudness <on|off>
: Sets the loudness setting of the speaker to 'on' of 'off'.mute
: Returns the mute setting of the speaker, 'on' or 'off'.mute <on|off>
: Sets the mute setting of the speaker to 'on' of 'off'.next
: Move to the next track (if applicable for the current audio source).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.party_mode
(orparty
): Adds all speakers in the system into a single group. The target speaker becomes the group coordinator. Remove speakers individually usingungroup
.pause
: Pause playback (if applicable for the audio source).pause_all
: Pause playback on all speakers in the system. (Note: only pauses speakers that are in the same Sonos Household.)play
: Start playback.playback
: Returns the current playback state for the speaker.play_mode
(ormode
): Returns the play mode of the speaker, one of NORMAL, REPEAT_ONE, REPEAT_ALL, SHUFFLE or SHUFFLE_NO_REPEAT.play_mode <mode>
(ormode
): Sets the play mode of the speaker to<mode>
, which is one of the values above.play_uri <uri> <title>
(alsouri
): Plays the audio object given by the<uri>
parameter (e.g., a radio stream URL).<title>
is optional, and if present will be used for the title of the audio stream.previous
(orprev
): Move to the previous track (if applicable for the audio source).ramp_to_volume <volume>
(orramp
): Gently raise or reduce the volume to<volume>
, which is between 0 and 100. Returns the number of seconds to complete the ramp.reindex
: Start a reindex of the local music libraries.relative_volume <adjustment>
(orrel_vol
): Raises or lowers the volume by which must be a number from -100 to 100.seek <HH:MM:SS>
: Seek to a point within a track (if applicable for the audio source).sleep_timer
(orsleep
): Returns the current sleep timer remaining time in seconds; 0 if no sleep timer is active.sleep_timer <seconds>
(orsleep
): Set the sleep timer to<seconds>
seconds.status_light
(orlight
): Returns the state of the speaker's status light, 'on' or 'off'.status_light <on|off>
(orlight
): Switch the speaker's status light on or off.stop
: Stop playback.track
: Return information about the currently playing track.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.ungroup
: Removes the speaker from a group.unpair
: Separate a stereo pair. Can be applied to either speaker in the pair.volume
(orvol
): Returns the current volume setting of the speaker (0 to 100)volume <volume>
(orvol
): Sets the volume of the speaker to<volume>
(0 to 100).zones
(orvisible_zones
,rooms
,visible_rooms
): Returns the room names (and associated IP addresses) that are visible in the Sonos controller apps. Useall_zones
(orall_rooms
) to return all devices including ones not visible in the Sonos controller apps.
Alternative Discovery
If the standard SoCo discovery method doesn't work for you, an alternative discovery mechanism is provided. This scans your local network(s) for Sonos devices and caches the results for use in subsequent sonos
calls.
You can see the results of a network scan by using the sonos-discovery
utility.
To use this 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. The results of the discovery scan are 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".
If your speakers subsequently change (e.g., they are renamed or their IP addresses change), you can force a refresh of 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.
Example: sonos -lr "living room" volume 50
will refresh the discovery cache before executing the sonos
command.
(Note: this approach will shortly be improved so that sonos-discover
can be used separately to create or refresh the discovery cache.)
Resources
[1] https://github.com/SoCo/SoCo
[2] ToDo: Add PyPi link
Acknowledgments
All trademarks acknowledged. Avantrec Ltd has no connection with Sonos Inc.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.