# Supysonic Supysonic is a Python implementation of the [Subsonic][] server API. [![Build Status](https://travis-ci.org/spl0k/supysonic.svg?branch=master)](https://travis-ci.org/spl0k/supysonic) [![codecov](https://codecov.io/gh/spl0k/supysonic/branch/master/graph/badge.svg)](https://codecov.io/gh/spl0k/supysonic) ![Python](https://img.shields.io/badge/python-2.7%2C%203.5%2C%203.6-blue.svg) Current supported features are: * browsing (by folders or tags) * streaming of various audio file formats * transcoding * user or random playlists * cover arts (`cover.jpg` files in the same folder as music files) * starred tracks/albums and ratings * [Last.FM][lastfm] scrobbling For more details, go check the [API implementation status][api]. [subsonic]: http://www.subsonic.org/ [lastfm]: https://last.fm [api]: API-INFO.md ## Table of contents * [Installation](#installation) + [Prerequisites](#prerequisites) + [Configuration](#configuration) + [Database initialization](#database-initialization) * [Running the application](#running-the-application) + [As a standalone debug server](#as-a-standalone-debug-server) + [As an Apache WSGI application](#as-an-apache-wsgi-application) + [Other options](#other-options) * [Transcoding](#transcoding) * [Command line interface](#command-line-interface) * [Quickstart](#quickstart) * [Watching library changes](#watching-library-changes) * [Upgrading](#upgrading) ## Installation Supysonic can run as a standalone application (not recommended for a "production" server) or as a WSGI application (on Apache for instance). To install it, run: $ python setup.py install ### Prerequisites You'll need these to run Supysonic: * Python 2.7 or >= 3.5 * [Flask](http://flask.pocoo.org/) >= 0.9 * [PonyORM](https://ponyorm.com/) * [Python Imaging Library](https://github.com/python-pillow/Pillow) * [requests](http://docs.python-requests.org/) * [mutagen](https://mutagen.readthedocs.io/en/latest/) * [watchdog](https://github.com/gorakhargosh/watchdog) You can install all of them using `pip`: $ pip install -r requirements.txt You may also need a database specific package: * MySQL: `pip install pymysql` or `pip install mysqlclient` * PostgreSQL: `pip install psycopg2` ### Configuration Supysonic looks for four files for its configuration: `/etc/supysonic`, `~/.supysonic`, `~/.config/supysonic/supysonic.conf` and `supysonic.conf` in the current folder, merging values from all files. Configuration files must respect a structure similar to Windows INI file, with `[section]` headers and using a `KEY = VALUE` or `KEY: VALUE` syntax. The sample configuration (`config.sample`) looks like this: ```ini [base] ; A database URI. See the 'schema' folder for schema creation scripts ; Default: sqlite:///tmp/supysonic/supysonic.db ;database_uri = sqlite:////var/supysonic/supysonic.db ;database_uri = mysql://supysonic:supysonic@localhost/supysonic ;database_uri = postgres://supysonic:supysonic@localhost/supysonic ; Optional, restrict scanner to these extensions. Default: none ;scanner_extensions = mp3 ogg [webapp] ; Optional cache directory. Default: /tmp/supysonic cache_dir = /var/supysonic/cache ; Optional rotating log file. Default: none log_file = /var/supysonic/supysonic.log ; Log level. Possible values: DEBUG, INFO, WARNING, ERROR, CRITICAL. Default: WARNING log_level = WARNING ; Enable the Subsonic REST API. You'll most likely want to keep this on, here for testing purposes. Default: on ;mount_api = on ; Enable the administrative web interface. Default: on ;mount_webui = on [daemon] ; Delay before triggering scanning operation after a change have been detected ; This prevents running too many scans when multiple changes are detected for a ; single file over a short time span. Default: 5 wait_delay = 5 ; Optional rotating log file for the scanner daemon log_file = /var/supysonic/supysonic-daemon.log log_level = INFO [lastfm] ; API and secret key to enable scrobbling. http://www.last.fm/api/accounts ; Defaults: none ;api_key = ;secret = [transcoding] ; Programs used to convert from one format/bitrate to another. Defaults: none transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath - transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt - decoder_mp3 = mpg123 --quiet -w - %srcpath decoder_ogg = oggdec -o %srcpath decoder_flac = flac -d -c -s %srcpath encoder_mp3 = lame --quiet -b %outrate - - encoder_ogg = oggenc2 -q -M %outrate - [mimetypes] ; Extension to mimetype mappings in case your system has some trouble guessing ; Default: none ;mp3 = audio/mpeg ;ogg = audio/vorbis ``` Note that using SQLite for large libraries might not be the brightest idea as it tends to struggle with larger datasets. For mime types, see the [list of common types][types]. [types]: https://en.wikipedia.org/wiki/Internet_media_type#List_of_common_media_types ### Database initialization Supysonic does not issue the `CREATE TABLE` commands for the tables it needs. Thus the database and tables must be created prior to running the application. Table creation scripts are provided in the `schema` folder for SQLite, MySQL and PostgreSQL. ## Running the application ### As a standalone debug server It is possible to run Supysonic as a standalone server, but it is only recommended to do so if you are hacking on the source. A standalone won't be able to serve more than one request at a time. To start the server, just run the `cgi-bin/server.py` script. $ python cgi-bin/server.py By default, it will listen on the loopback interface (`127.0.0.1`) on port 5000, but you can specify another address on the command line, for instance on all the IPv6 interfaces: $ python cgi-bin/server.py :: ### As an Apache WSGI application Supysonic can run as a WSGI application with the `cgi-bin/supysonic.wsgi` file. To run it within an Apache2 server, first you need to install the WSGI module and enable it. $ apt-get install libapache2-mod-wsgi $ a2enmod wsgi Next, edit the Apache configuration to load the application. Here's a basic example of what it looks like: WSGIScriptAlias /supysonic /path/to/supysonic/cgi-bin/supysonic.wsgi WSGIApplicationGroup %{GLOBAL} WSGIPassAuthorization On Order deny,allow Allow from all You might also need to run Apache using the system default locale, as the one it uses might cause problems while scanning the library. To do so, edit the `/etc/apache2/envvars` file, comment the line `export LANG=C` and uncomment the `. /etc/default/locale` line. Then you can restart Apache: $ service apache2 restart With that kind of configuration, the server address will look like *http://server/supysonic/* ### Other options If you use another HTTP server, such as *nginx* or *lighttpd*, or prefer to use FastCGI or CGI over WSGI, FastCGI and CGI scripts are also provided in the `cgi-bin` folder, respectively as `supysonic.fcgi` and `supysonic.cgi`. As with WSGI, you might need to edit those file to suit your system configuration. Here are some quick docs on how to configure your server for [FastCGI][] or [CGI][]. [fastcgi]: http://flask.pocoo.org/docs/deploying/fastcgi/ [cgi]: http://flask.pocoo.org/docs/deploying/cgi/ ## Transcoding Transcoding is the process of converting from one audio format to another. This allows for streaming of formats that wouldn't be streamable otherwise, or reducing the quality of an audio file to allow a decent streaming for clients with limited bandwidth, such as the ones running on a mobile connection. Supysonic's transcoding is achieved through the use of third-party command-line programs. Supysonic isn't bundled with such programs, and you are left to choose which one you want to use. If you want to use transcoding but your client doesn't allow you to do so, you can force Supysonic to transcode for that client by going on the web interface. ### Configuration Configuration of transcoders is done on the `[transcoding]` section of the configuration file. Transcoding can be done by one single program which is able to convert from one format direclty to another one, or by two programs: a decoder and an encoder. All these are defined by the following variables: * *transcoder_EXT_EXT* * *decoder_EXT* * *encoder_EXT* * *trancoder* * *decoder* * *encoder* where *EXT* is the lowercase file extension of the matching audio format. *transcoder*s variables have two extensions: the first one is the source extension, and the second one is the extension to convert to. The same way, *decoder*s extension is the source extension, and *encoder*s extension is the extension to convert to. Notice that all of them have a version without extension. Those are generic versions. The programs defined with these variables should be able to transcode/decode/encode any format. For that reason, we suggest you don't use these if you want to keep control over the available transcoders. Supysonic will take the first available transcoding configuration in the following order: 1. specific transcoder 2. specific decoder / specific encoder 3. generic decoder / generic encoder (with the possibility to use a generic decoder with a specific encoder, and vice-versa) 4. generic transcoder All the variables should be set to the command-line used to run the converter program. The command-lines can include the following fields: * `%srcpath`: path to the original file to transcode * `%srcfmt`: extension of the original file * `%outfmt`: extension of the resulting file * `%outrate`: bitrate of the resulting file One final note: the original file should be provided as an argument of transcoders and decoders. All transcoders, decoders and encoders should write to standard output, and encoders should read from standard input. ### Suggested configuration Here are some example configuration that you could use. This is provided as-is, and some configurations haven't been tested. transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath - transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt - decoder_mp3 = mpg123 --quiet -w - %srcpath decoder_ogg = oggdec -o %srcpath decoder_flac = flac -d -c -s %srcpath encoder_mp3 = lame --quiet -b %outrate - - encoder_ogg = oggenc2 -q -M %outrate - ## Command line interface The command-line interface (or CLI, *cli.py*) is an interface allowing administration operations without the use of the web interface. It can either be run in interactive mode (`python cli.py`) or to issue a single command (`python cli.py `). If ran without arguments, `supsonic-cli` will open an interactive prompt. You can use the command line tool to do a few things: ``` Usage: supysonic-cli [help] (user) (folder) Display the help message Arguments: user Display the help message for the user command folder Display the help message for the folder command ``` ``` Usage: supysonic-cli user [add] (-a) (-p ) (-e ) supysonic-cli user [delete] supysonic-cli user [changepass] supysonic-cli user [list] supysonic-cli user [setadmin] (--off) User management commands Arguments: add Add a new user delete Delete the user changepass Change the user's password list List all the users setadmin Give admin rights to the user Options: -a --admin Create the user with admin rights -p --password Specify the user's password -e --email Specify the user's email --off Revoke the admin rights if present ``` ``` Usage: supysonic-cli folder [add] supysonic-cli folder [delete] supysonic-cli folder [list] supysonic-cli folder [scan] Folder management commands Arguments: add Add a new folder delete Delete a folder list List all the folders scan Scan a specified folder ``` ## Quickstart To start using Supysonic, you'll first have to specify where your music library is located and create a user to allow calls to the API. Let's start by creating a new admin user this way: $ supysonic-cli user add spl0k -a -p MyAwesomePassword To add a new folder to your music library, you can do something like this: $ supysonic-cli folder add MyLibrary /home/spl0k/Music Once you've added a folder, you will need to scan it: $ supysonic-cli folder scan MyLibrary You should now be able to enjoy your music with the client of your choice! ## Watching library changes Instead of manually running a scan every time your library changes, you can run a watcher that will listen to any library change and update the database accordingly. The watcher is `bin/supysonic-watcher`, it is a non-exiting process and doesn't print anything to stdout nor stderr. If you want to keep it running in background, either use the old `nohup` or `screen` methods, or start it as a simple systemd unit (unit file not included). ## Upgrading Some commits might introduce changes in the database schema. When that's the case migration scripts will be provided in the `schema/migration` folder, prefixed by the date of commit that introduced the changes. Those scripts shouldn't be used when initializing a new database, only when upgrading from a previous schema. There could be both SQL scripts or Python scripts. The Python scripts require arguments that are explained when the script is invoked with the `-h` flag. If a migration script isn't provided for a specific database engine, it simply means that no migration is needed for this engine.