bin | ||
cgi-bin | ||
docs | ||
supysonic | ||
tests | ||
.coveragerc | ||
.gitignore | ||
.travis.yml | ||
config.sample | ||
LICENSE | ||
MANIFEST.in | ||
README.md | ||
setup.py | ||
travis-requirements.txt |
Supysonic
Supysonic is a Python implementation of the Subsonic server API.
Current supported features are:
- browsing (by folders or tags)
- streaming of various audio file formats
- transcoding
- user or random playlists
- cover arts (as image files in the same folder as music files)
- starred tracks/albums and ratings
- Last.FM scrobbling
Supysonic currently targets the version 1.8.0 of the Subsonic API. For more details, go check the API implementation status.
Table of contents
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, either run:
$ python setup.py install
or
$ pip install .
but not both. Please note that the pip
method doesn't seem to work with
Python 2.7.
Prerequisites
You'll need these to run Supysonic:
- Python 2.7 or >= 3.5
- Flask
- PonyORM
- Python Imaging Library
- requests
- mutagen
- watchdog (if you want to use the watcher)
All the dependencies (except watchdog) will automatically be installed by the installation command above.
You may also need a database specific package if you don't want to use SQLite (the default):
- MySQL:
pip install pymysql
orpip install mysqlclient
- PostgreSQL:
pip install psycopg2-binary
Database initialization
Supysonic needs a database to run. It can either be a SQLite, MySQL-compatible or PostgreSQL database.
Please refer to the documentation of the DBMS you've chosen on how to create a database. Once it has a database, Supysonic will automatically create the tables it needs.
If you want to use PostgreSQL you'll have to add the citext
extension to the
database once created. This can be done when connected to the database as the
superuser with the folowing SQL command:
supysonic=# CREATE EXTENSION citext;
If you absolutely have no clue about databases, you can go with SQLite as it doesn't need any setup other than specifying a path for the database. Note that using SQLite for large libraries might not be the brightest idea as it tends to struggle with larger datasets.
Configuration
Once you have a database, you'll need to create a configuration file. It must be saved under one of the following paths:
/etc/supysonic
~/.supysonic
~/.config/supysonic/supysonic.conf
A roughly documented sample configuration file is provided as config.sample
.
The minimal configuration using a SQLite database would be:
[base]
database_uri = sqlite:////some/path/to/a/supysonic.db
For a more details on the configuration, please refer to documentation.
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 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
<Directory /path/to/supysonic/cgi-bin>
WSGIApplicationGroup %{GLOBAL}
WSGIPassAuthorization On
Require all granted
</Directory>
You might also need to run Apache using the system default locale, as the one
it uses might cause problems while scanning the library from the web UI. 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:
$ systemctl restart apache2
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
. 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.
Docker
If you want to run Supysonic in a Docker container, here are some images provided by the community.
- https://github.com/ultimate-pms/docker-supysonic
- https://github.com/ogarcia/docker-supysonic
- https://github.com/foosinn/supysonic
- https://github.com/mikafouenski/docker-supysonic
- https://github.com/oakman/supysonic-docker
- https://github.com/glogiotatidis/supysonic-docker
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 MyUserName -a -p MyAwesomePassword
To add a new folder to your music library, you can do something like this:
$ supysonic-cli folder add MyLibrary /home/username/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!
For more details on the command-line usage, take a look at the documentation.
Client authentication
The Subsonic API provides several authentication methods. One of them, known as token authentication was added with API version 1.13.0. As Supysonic currently targets API version 1.8.0, the token based method isn't supported. So if your client offers you the option, you'll have to disable the token based authentication for it to work.
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 supysonic-watcher
, it is a non-exiting process and doesn't
print anything to the console. 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).
It needs some additional dependencies which can be installed with the following command:
$ pip install -e .[watcher]
Upgrading
To upgrade your Supysonic installation, simply re-run the command you used to
install it (either python setup.py install
or pip install .
).
Some commits might introduce changes in the database schema. Starting with
commit e84459d627
(August 29th, 2018) migrations
will be automatically applied.
If your database was created prior to this date, you'll have to manually apply
unapplied migrations up to the latest. Once done you won't have to worry about
future migrations as they'll be automatically applied.
Migration scripts are provided in the supysonic/schema/migration
folder, named
by the date of commit that introduced the schema changes. 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.