Getting Started with Sonospy
(Early incomplete draft)
Mark Henkelis started developing Sonos related programs in 2009, and over time his work has grown to create the potential for a wide range of Sonos add-on extension & replacement facilities.
The project containing this ReadMe is a tested and packaged subset of Mark's work. Essentially this subset works through the existing Sonos controllers, removing a number of limitations caused by the lack of resources in Sonos hardware. The current release of this project provides solutions to the following long standing community enhancement requests:
-
removal of the Sonos 65,000 track capacity limitation.
-
support multi-value tags, for example a track may be stored under both "Rock" and "Live Music" genres, or tracks or albums resulting from artist collaborations can be listed in the artist index under each separate artist.
-
improved and flexible music browsing capabilities, for example albums can be sorted by Date Released, and/or by Date Ripped, rather than just be listed in alphabetical sequence.
-
databases can be filtered for recently added music to your overall library.
-
playlists can be promoted to virtual album status, so that they appear in the indices as normal albums
-
the major works of classical composers can become visible and selectable in the Sonos indices
-
the range of music file types playable by Sonos is extended for Linux users, for example high-res flac files can be transcoded on-the-fly into something which Sonos can play
-
a Linux user can stream any music playing through their PC's sound-card, and have that music transported via their Sonos system <<<< is this an acceptable short description of what is offered? >>>>
Sonospy provides a facility to index your local music library, and it then mimics something which Sonos will accept as a source of local library music. The standard Sonos controllers (CR200, CR100, Sonos Desktop Controller, Android, iPhone & iPad controllers) run without change, but are extended by the richer index which is served up to them.
The project is entirely standalone. It does not update your music tracks, nor does it alter any Sonos supplied software. The native Sonos controls and indices remain available, but new and more powerful facilities are available alongside them in the Music Services section of the controller.
The project is programmed in Python, stores its database using SQLite, and implements a proxy server facility for WMP.
It is cross platform project, and has been tested running in Linux and Windows environments.
It is built on top of the BRisa UPnP framework, with extensions added for Sonos ZonePlayers and the content they can serve/render.
You will need to download the following dependencies. Installation instructions for them for your platform can be found on the link pages.
Python 2.6 or later
Linux: from your distro or get the source tarball from http://www.python.org/download/releases/2.6.4/
Mac: http://www.python.org/download/releases/2.6.4/ - select the Mac installer
Windows: http://www.python.org/download/releases/2.6.4/ - select the windows installer
(for Windows, remember to set the path environment variable so it can find Python)
To play files locally on the machine running pycpoint (linux only):
* gstreamer 0.10+ - http://gstreamer.freedesktop.org/download
* gmediarender-0.0.6 - http://gmrender.nongnu.org/#dl
To transcode file types on-the-fly that Sonos doesn't support (linux only)
* lame (for converting mp2 to mp3)
* sox (for downsampling FLAC)
* parec (to send PC output to ZP)
The following packages are bundled with sonospy (no need to download/install):
circuits.web: Python-circuits 1.2.1 (All platforms: http://bitbucket.org/prologic/circuits/downloads/)
cherrypy: cherrypy WSGI server 3.1.2 (All platforms: http://www.cherrypy.org/wiki/CherryPyDownload)
python-brisa: python-brisa Framework 0.10.0 python-brisa Qt Reactor 0.10.0 (All platforms: http://brisa.garage.maemo.org/installation.html)
The current stable release of the project can be found at https://github.com/henkelis/sonospy <<<<<<<<< Branch Name ? >>>>>>>>>>>>>>> Press the Downloads button, and take the Download.zip option for Windows, and the Download.tar.gz option for Linux.
Extract the download into your directory of choice.
The following ports need to be open in the firewall on the machine you are running Sonospy on. Most are standard UPnP/WMP ports, with additional ones for the BRisa framework and the proxy.
Note that you may need to open ports specific to other UPnP media servers too (if you are using them).
1900 UDP
2149 UDP (current M-SEARCH send port so WMP is picked up)
2869 TCP
10243 TCP
10244-+n TCP (proxy internal WMP server, inc for multiple, can be changed in ini)
10280-10284 UDP
50101-50102 TCP (control point and proxy, can be changed in ini)
Ensure that your Sonos system is set up to play music from UPnP servers:
- on the Destop Controller go to File|Preferences, and press Advanced Options on the General tab. Make sure the "Show music from Windows Media Servers" is checked
- or with the CR200 go to Settings|AdvancedSettings, and make sure that Display Windows Media Servers is set to On.
1> The first step is to create the Sonospy index over your local library music shares.
2> You then start the Sonospy proxy server to make your new index available to the Sonos controllers
3> You can immediately use the new facilities via your Sonos controllers, as the Sonospy server is automatically detected
4> Periodically you run an short update scan, causing the Sonospy index to pick up newly ripped items, new music downloads, and to see any tag changes or other changes that you have made in your music.
Sonospy is highly configurable, to suit a wide variety of user preferences.
Indexing your whole library is just one command, but it may take a while depending upon the size of your library and the speed of your computer. The Sonospy index design has traded off index size for processing speed. As a rule of thumb each track will take about 5k to 6k of disk storage for the index.
For the above two reasons it is recommended that you initially just index a manageable subset of your local library to get an initial taste of what Sonospy can offer. This way, before committing to indexing your whole collection, you can make sure that you have Sonospy configured the way that you want it, and you can also verify that your installed copy of Sonospy is working correctly.
Identify a path, or a couple of paths, containing a subset of your local music library. Ideally the directory tree beneath the chosen path(s) should contain at least a couple of albums. If your music library isn't segmented into separate paths, you could copy some tracks to a path somewhere else on your disk. Scan will work recursively to scan any subfolders from the origination of the scan.
The general form of the index command is: scan -d
Here are some example commands to create the initial database as recommended above. In this case, the database that will be generated is named Sonospy.db, and will be placed in the the sonospy/sonospy directory. In this example the music tracks are located in, or beneath, "/mnt/nas/music/Bert Jansch" ("C:\music\Bert Jansch" for a Windows example, or "\MyNAS\music\Bert Jansch" for a Windows example when using a NAS):
For Linux:
./scan -v -d Sonospy.db /mnt/nas/music/Bert\ Jansch > test.log
For windows with a NAS:
python scan -v -d Sonospy.db \\\\MyNAS\\music\\Bert\ Jansch >Test.log
Or windows without a NAS
python scan -v -d Sonospy.db c:\\music\\Bert\ Jansch >Test.log
(note the way that any embedded blank in a directory name needs to be preceded by a backslash, and that in Windows the other backslashes need to be doubled up)
Another thing to note is that the -v option places Sonospy into verbose logging mode. The Test.log file may prove useful if there is a set up problem. You shouldn't use the -v setting when you scan your whole library as the log will be too large to be of any use.
If you want to extend your test database with further music, you can run the scan command multiple times, each time to the same Sonospy.db database, but pulling in music from a different music location (ie. add music from another artist, to the Bert Jansch music already indexed by the above example).
You have now created the Sonospy index over some of your music. You are ready to move on to step two, where you will use that index via the Sonos controllers.
When you have tested your installation of Sonospy, and have tailored it to your satisfaction, you need to return to this step to index you whole local library. You use the same command, this time without the verbose logging option, and this time running over your whole library not just a few albums. You can use the same Sonospy.db database that you created above, unless you included music into the test, which you don't want to see in your main database. In that case you can delete the test copy of Sonospy.db before proceeding.
Example commands follow, although obviously you need to tailor them for your own music location(s).
For linux:
./scan -d Sonospy.db /mnt/nas/music > SonospyLoad.log
For windows with a NAS:
python scan -d Sonospy.db \\\\MyNAS\\music >SonospyLoad.log
Or windows without a NAS
python scan -d Sonospy.db c:\\music >SonospyLoad.log
If you have more than one music share, you can index them one at a time, or all at once. On the first run, if scan sees that the named database does not already exist, it will automatically create it. On any subsequent runs, when outputting to a pre-existing database, it will just add in the new material. In fact, anytime you add new music to your collection, you will want to re-run your scan to make sure it gets added to the Sonospy database.
The command format to handle multiple music location paths, during a single pass, is to list them one after the other, with a blank separating the paths. Here is a Windows example:
python scan -d Sonospy.db c:\\music c:\\OtherMusic >SonospyLoad.log
And in Linux:
./scan -d Sonospy.db /mnt/music /mnt/OtherMusic >SonospyLoad.log
The Sonos controllers allow you to browse your local library music by either their own restricted index, or via the WMP server from Microsoft. Mark has implemented a WMP clone in Sonospy, and it is through this backdoor he is able to offer his extensions to Sonos users.
This step starts up the Sonospy server function, which will use the Sonospy database created above, and translate this information into something which Sonos is expecting and can understand.
The native Sonos capabilities will remain available, and unaffected, in the Music Library section of the controllers. The new Sonospy indices are also available, alongside, in the Music services section in the Sonos controllers.
Here are example commands to start the Sonospy server:
For Linux:
./sonospy_proxy -wSonospy=Henkelis,Sonospy.db
For Windows:
python pycpoint.py -p -wSonospy=Henkelis,Sonospy.db
You can also load more than one database if you so desire. These will show up as their own (indicies?) in the Music Services section of the sonos controllers. An example:
For Linux:
./sonospy_proxy -wSonospy=Henkelis,Sonospy.db -wSonospy=Last7Days,last7days.db
For Windows:
python pycpoint.py -p -wSonospy=Henkelis,Sonospy.db -wSonospy=Last7Days,last7days.db
This would create a music service called "Henkelis" and another called "Last7Days". This can be useful when you are using extracted databases (more on that later!)
The Sonos controllers should automatically detect and list the Sonospy controller (identified with the title "Henkelis" if you used the example command shown above.
Sonos sees this as a new Music Service, so it will be found at:
- CR100 - as a "button", below the Music Library & Radio buttons, in the Music Menu
- CR100 - ??????
- Desktop Controller: In the Music Services Tab, between the Library and the Sonos Playlists tabs
- iPhone: ???
- iPad: ???
- Android: ????
When you open this Sonospy music service you will see the familiar indices (Artists, Albums, Composers, etc). What you see inside these indices is flexible, and can be easily tailored for your own preferences.
... default start up view just replicates Sonos-native ... removes 65k restrictions, adds support multi-value tags
... Search and speed dial are missing ... why, and who to phone
... turn on sorts ... lots of magic .. brief description of what you are looking at
.... problems ... go and look at the Test.log .. scan -r ... check ports ... check UPnP setting
... what it does ... when and how to run it
- Do we need a basic glossary of what these terms mean to the user? Proxy, Control Point, etc.?
- I think we can/should point out how to make recently added databases. I find this to be one of my go-to features for Sonospy. I could tackle this part.
- We're already running VERY long here on the documentation. We should discuss Wiki layout to make this less overwhelming. Perhaps entirely separate Linux documentation from Windows?
- In step 1 above, there is SO much dedicated to how to create a test database from their entire collection, I think we should reverse it to focus on creating their collection first (as most will just do anyway) and leave a small section on the "if you want to test this on a smaller subset" section. Just seems like an easy place to edit our wordcount down. :)
- On "installation of pycpoint" do we want to refer to it as Sonospy now?