Sonos Command Line Controller Available (Python soco-cli)

pwt
Userlevel 7
Badge +20
  • pwt
  • Virtuoso
  • 1873 replies

I’ve created a simple command line control program for Sonos, implemented in Python. I find it very useful for creating a variety of Sonos control scripts (e.g., using cron to run scripts at specific times), and sometimes just for quickly controlling my Sonos systems when I don’t want to start the app.

It works with S1, S2, and split Sonos systems, and it should run on any OS that supports Python 3.

If you’re comfortable using Python and the command line, you may find it useful, too. It’s quite powerful, with a wide range of control actions, yet simple to install and use.

GitHub: https://github.com/avantrec/soco-cli

PyPi: https://pypi.org/project/soco-cli

This is an early release, so expect some bugs and limitations. I’d welcome your feedback and suggestions.

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port

55 replies

pwt
Userlevel 7
Badge +20

For anyone using SoCo-CLI’s HTTP API server feature, I’ve now added the ability to parameterise macros. This is quite a powerful feature and is available in v0.4.38 and later. The details are in the documentation at:

https://github.com/avantrec/soco-cli/blob/master/README.md#macro-arguments

Any questions or problems, just let me know ...

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port
pwt
Userlevel 7
Badge +20

Only thing I’ve found so far that doesn’t seem to work, and is probably more of a documentation issue, is that the github page suggests you can run:
  sonos SPEAKER version
  This gives ‘Error: Action 'version' not found’.

Thank you very much for finding and reporting this. I’ve corrected the documentation now.

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port
pwt
Userlevel 7
Badge +20

How do you group more then 2 speakers? 

sonos -l "family room" group "media room"

combines 2 but I need 2 more rooms grouped.

The following will group sp2, sp3 and sp4 with sp1 as the group coordinator:

sonos -l sp2 group sp1 : sp3 group sp1 : sp4 group sp1

(The ‘ : ’ allows multiple sonos actions to be invoked as part of the same command, but it’s equivalent to issuing multiple separate sonos commands.)

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port
pwt
Userlevel 7
Badge +20

Also, it only seems to show me the first 100 songs in the playlist. Most of my playlists have considerably more than this. I seem to remember that soco displays 100 by default, but it can be increased I think?

Just FYI, v0.1.22_1 is released now, with a fix for the issue above.

There’s also a new ‘wait_stopped_for’ action, and the addition of a simple looping  primitive.

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port
pwt
Userlevel 7
Badge +20

The HTTP API Server macro feature is now released as part of SoCo-CLI v0.4.34. @FlipLewis , this should satisfy your doorbell use case.

Documentation is at:

https://github.com/avantrec/soco-cli/blob/master/README.md#macros-defining-custom-http-api-server-actions

Feedback welcome, and let me know of any issues (ideally over at the GitHub site, not here).

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port
R

Amazing utility! I’ve incorporated it into the Apple Home app via Homebridge with buttons to play a certain radio station and another for power nap - pause music, set a once only alarm, resume. A cron’ed job groups certain rooms. Command line rules!

F

Awesome PWT!  This is great.  Thank you.

T
Userlevel 1
Badge +1

Just wanted to say thanks for this!  I played around with it this morning expecting a moderately useful utility.  WOW was I surprised about how much work you have put into this - very comprehensive functionality.

Anyone with Sonos speakers who spends time at the CLI should grab this.

R

Fantastic,

used it to stereo pair a Five with a Play:5 gen2. 

Works great!

pwt
Userlevel 7
Badge +20

The HTTP server doesn’t currently accept sequential actions. I’ll have a think about how to add this, but it’s not particularly simple.

I’ve now added a ‘macros’ feature that allows one to define custom actions and sequences of actions to be executed by the HTTP API server. For example, for this use case one might define a ‘doorbell’ macro:

http://192.168.xx.xx:8000/macro/doorbell

This would invoke the necessary sequence of actions, defined in a local macros file at the server end.

I’ve implemented the feature and I’ll release it later today once it’s documented.

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port
pwt
Userlevel 7
Badge +20

SoCo-CLI versions 0.3.45+ introduce support for the track_follow action. This will print out the currently playing track, and each subsequent track when the track changes. e.g.:

(soco-cli) pwt@pwt-mba ~ % sonos study track_follow     

  Album:       Takk...
  Artist:      Sigur Rós
  Duration:    0:04:30
  Position:    30
  Title:       Hoppípolla

  Album:       OK Computer
  Artist:      Radiohead
  Duration:    0:04:27
  Position:    31
  Title:       Exit Music (For A Film)

  Album:       Heaven or Las Vegas
  Artist:      Cocteau Twins
  Duration:    0:04:58
  Position:    32
  Title:       Heaven or Las Vegas

  Playback is stopped or paused

  Album:       Heaven or Las Vegas
  Artist:      Cocteau Twins
  Duration:    0:04:58
  Position:    32
  Title:       Heaven or Las Vegas

...

track_follow is available in both command line and interactive modes.

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port
pwt
Userlevel 7
Badge +20

SoCo-CLI v0.1.46 now supports direct Sonos playback of local audio files, using the play_file action. I’ve included the documentation below:

Local Audio Files

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

This sets up a temporary local web server on the local host, from which Sonos can access the audio file and play it. The action will not terminate until playback has concluded. Example:

sonos Lounge play_file mozart.mp3

The host running soco-cli must remain switched on and connected to the network during playback. The web server is only active for the duration of the play_file action, and will only serve the specified audio file.

 

Full documentation can be found at: https://github.com/avantrec/soco-cli/blob/master/README.md 

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port
rleeden
Badge

Great work. I’ve been using soco for a while now, but this makes life a lot easier - thanks!

Only thing I’ve found so far that doesn’t seem to work, and is probably more of a documentation issue, is that the github page suggests you can run:

sonos SPEAKER version

This gives ‘Error: Action 'version' not found’.

Of course sonos --version works fine

1 x Arc | 1 x Sub (Gen 3) | 2 x One | 3 x Play:1 | 2 x Move | 1 x Roam | 2 x One SL
pwt
Userlevel 7
Badge +20

SoCo-CLI v0.4.18 adds the ability to play share links from Deezer. Share links can refer to tracks, albums or playlists, which are added to the Sonos queue. This feature is considered experimental and feedback is welcome.

Example:

> sonos Kitchen sharelink “https://www.deezer.com/en/playlist/5390258182”
> sonos Kitchen play_from_queue

Documentation: https://github.com/avantrec/soco-cli#spotify-tidal-and-deezer-share-links 

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port
pwt
Userlevel 7
Badge +20

Just to summarise recent changes: enhancements to queue management, selection from searches, favourite radio stations, and Line In control. Change log shown below. Feedback and enhancement requests are welcome.

v0.1.38   - Add search caching and indexed playback for 'tracks_in_album'
          - Add search caching and indexed playback for 'list_albums'
          - Add search caching and indexed playback for 'search_artists'
          - Add '--docs' option to print URL to online documentation
          - Add 'soco-discover' synonym for 'sonos-discover'
          - Add line_in 'right_input' parameter for stereo paired P:5/Fives
          - Behaviour change: Line-In starts playback after being selected
v0.1.37   - Fix 'play_favourite_radio_station'
          - Improve output from 'track' action for non-queue items
          - Add 'cue_favourite_radio_station' action
v0.1.36   - Add 'last_search' action to cache track and album searches
          - Add 'queue_last_search_number' action
v0.1.35   - Add 'queue_position' action
          - Add 'play_next' option to 'queue_track' and 'queue_album'
          - Add 'play_next' option for 'add_playlist_to_queue'
          - Add 'play_next' option for 'add_favourite_to_queue'
v0.1.34   - Add 'fade' synonym for 'cross_fade'
          - Add 'remove_current_track_from_queue' action
          - Add 'remove_last_track_from_queue' action
v0.1.33   - Add 'none' as a synonym for 'off', in the 'repeat' action
          - Add the ability to use sequences and ranges with 'remove_from_queue'

 Docs: https://github.com/avantrec/soco-cli/blob/v0.1.38/README.md

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port
R

How do you group more then 2 speakers? 

sonos -l "family room" group "media room"

combines 2 but I need 2 more rooms grouped.

pwt
Userlevel 7
Badge +20

FYI: SoCo-CLI v0.4.26 adds the ability to enable/disable subs and surround speakers.

Note to those upgrading: upgrade SoCo as well, to v0.25.0. (I forgot to update the version dependency before I made the release).

I’m currently working on a nice Plex integration, now that SoCo has a Plex plugin. More details once it’s released.

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port
pwt
Userlevel 7
Badge +20

With yesterday’s release of SoCo v0.20, I’m pleased to report that soco-cli now supports stereo pairing. Any pair of Sonos speakers can be stereo-paired, and it’s fast and simple to use.

Pairing:

sonos <left_speaker> pair <right_speaker>

Unpairing:

sonos <left_speaker> unpair

This is obviously mostly applicable to the case of pairing a Sonos One or One SL with a Play:1, but there may be other corner cases where it proves useful.

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port
pwt
Userlevel 7
Badge +20

I like this very much.  Now just need to whack a web server on it and a few web pages to call the python.  There goes my weekend....

Incidentally, there’s now a simple Python SoCo-CLI API that avoids the overhead of starting the program for each command (or command sequence). For example:

$ sonos Kitchen volume 30

becomes:

exit_code, output, error = api.run_command("Kitchen", "volume", "30")

The API call returns a three-tuple of exit code, output string, and error string. Assuming success (exit code 0), the output string contains exactly what would have been printed by the standalone command.

The command handles all the speaker discovery machinations behind the scenes, and caches discovery results. It also traps all exceptions, with the exception description appearing in the error string.

Docs at: https://github.com/avantrec/soco-cli#using-soco-cli-as-a-python-library

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port
P

Hi there! I have never used python and am a complete and absolute beginner. 

Is there a step by step instruction manual for a total idiot anywhere? 

pwt
Userlevel 7
Badge +20

Another quick update: I’ve now added direct shuffle and repeat actions to inspect and set your speakers’ shuffle and repeat modes, as follows:

sonos <speaker_name> shuffle <on|off>
sonos <speaker_name> repeat <off|one|all>

Using the actions without parameters will return the current state.

These actions are more convenient than the previous method, which combined the shuffle and repeat states (because this is how SoCo and the native Sonos API work).

The new actions are available in soco-cli v0.1.32 and later. Please see the (extensive) documentation for more details:

https://github.com/avantrec/soco-cli/blob/master/README.md 

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port
pwt
Userlevel 7
Badge +20

SoCo-CLI v0.3.31 introduces additional control over Sonos alarms.

In addition to being able to list alarms, it’s now possible to create alarms, delete alarms, and enable or disable alarms, using their alarm IDs. The new actions are: ‘create_alarm’, ‘remove_alarm’, and ‘enable_alarm’.

As always, feedback is welcome.

Version 0.3.34 adds the ability to copy and modify alarms, making it very quick and convenient to copy an alarm from one speaker to another, and then modify it if required. (I’ll also add a move_alarm function -- which I just thought of! -- in the next release.)

Example: sonos Kitchen copy_alarm 123 will copy the alarm with ID ‘123’ to the Kitchen speaker. (Alarm IDs are discovered using ‘list_alarms’.)

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port
F

First let me say great work @pwt on putting this all together.  It’s been very helpful.  

So I have 99% of this figured out, but am stuck on the last step of running a script from on the webserver I hope someone can help with a recommendation / advice.

Background:  I have configured a doorbell to chime the sonos speakers that is called via the API webserver.  I do all this using Container on my QNAP NAS and running the sonos-http-api-server.  That way I have a dedicated machine always waiting for a command.

A sample call would look something like this:

http://192.168.xx.xx:8000/Pool/play_file/Law-and-order-sound.mp3

So this is the same as sonos Pool play_file Law-and-order-sound.mp3 in Python.   

Pretty cool, it plays the Law and Order sound on my Sonos Speaker called Pool.  The problem i have is that I need to play the sound on all the speakers in the house.

So example would be:

sonos Pool group Garage : sp2 group Garage : Garage play_File Law-and-order-sound.mp3 : Garage ungroup

 

I just need to know how to call something like that from the Web Server.  Should I do a bash command to run a script?  Should I execute a python script to get it to work?   

Any advice or help would be appreciated.

 

pwt
Userlevel 7
Badge +20

I’m glad you’re finding SoCo-CLI useful. Thanks for the feedback.

The HTTP server doesn’t currently accept sequential actions. I’ll have a think about how to add this, but it’s not particularly simple.

So, as you’ve noted, three separate calls to the web server are required (as below).

http://192.168.xx.xx:8000/Pool/party_mode
http://192.168.xx.xx:8000/Pool/play_file/Law-and-order-sound.mp3
http://192.168.xx.xx:8000/Pool/ungroup_all

Right now, to perform this in one go via an HTTP call, you’d need to run your own simple web server with one or more GET paths that invoke the sonos sequential action lists that you require. This is not particularly hard to do, but does require a bit of know-how.

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port
pwt
Userlevel 7
Badge +20

Version 0.1.47 of SoCo-CLI adds the ability to play local M3U playlists, comprised of audio files stored on the local filesystem.

Example: sonos Kitchen play_m3u “Morning Mix.m3u”

The m3u filename can be followed by the `s` option to shuffle the playlist.

Example: sonos Kitchen play_m3u chilled.mp3 s

4 x P:5 | Sub | 4 x P:1 | 3 x Connect | 2 x Boost | Connect:Amp | 2 x One | Amp | Move | Port

Reply


Terms & ConditionsCookie settings