From a56facce91f935b6f27635262a6ca23763622aef Mon Sep 17 00:00:00 2001
From: Alban <alban.feron@gmail.com>
Date: Wed, 15 May 2013 18:07:47 +0200
Subject: [PATCH] Added README

---
 README.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100755 README.md

diff --git a/README.md b/README.md
new file mode 100755
index 0000000..6fb444b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,86 @@
+Supysonic
+=========
+
+Supysonic is a Python implementation of the [Subsonic](http://www.subsonic.org/) server API.
+
+At this time, it only supports what I need and lacks most features a real Subsonic server
+would provide. Current supported features are:
+* basic browsing (by folders or tags)
+* streaming (obviously, the collection scanner only looks for MP3s though)
+* random playlists
+* cover arts (`cover.jpg` files in the same folder as music files)
+* [Last.FM](http://last.fm/) scrobbling
+
+Installation
+------------
+
+Supysonic can run as a standalone application (not recommended for a "production" server)
+or as a WSGI application (on Apache for instance). But first:
+
+### Prerequisites
+
+* Python 2.7
+* [Flask](http://flask.pocoo.org/) (`pip install flask`)
+* [SQLAlchemy](http://www.sqlalchemy.org/) (`apt-get install sqlalchemy`)
+* Python Imaging Library (`apt-get install python-imaging`)
+* simplejson (`apt-get install python-simplejson`)
+* [eyeD3](http://eyed3.nicfit.net/) (`apt-get install python-eyed3`)
+
+### Configuration
+
+Supysonic looks for two files for its configuration: `~/.supysonic` or `/etc/supysonic` (in this order).
+Options are set using the `KEY = VALUE` syntax. String values must be quote-enclosed.
+
+Available settings are:
+* **DATABASE_URI**: a SQLAlchemy [database URI](http://docs.sqlalchemy.org/en/rel_0_8/core/engines.html#database-urls)
+  I personnaly use SQLite (`sqlite:////var/supysonic/supysonic.db`), but it might not be the brightest
+  idea for large libraries.
+* **CACHE_DIR**: path to a cache folder. Mostly used for resized cover art images.
+* **LOG_FILE**: path and base name of a rolling log file.
+* **LASTFM_KEY**: Last.FM [API key](http://www.last.fm/api/accounts) to enable scrobbling
+* **LASTFM_SECRET**: Last.FM API secret matching the key.
+
+### Running as a standalone 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 `main.py` script.
+
+	python main.py
+
+The server will then be available at *http://server:5000/*
+
+### Running as a WSGI application
+
+Supysonic can run as a WSGI application with the `main.wsgi` file. But first you need to edit this
+file at line 4 to set the path to the Supysonic app folder.
+
+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
+	service apache2 reload
+
+Next, edit the Apache configuration to load the application. Here's a basic example of what it looks like:
+
+	WSGIScriptAlias /supysonic /path/to/supysonic/main.wsgi
+	<Directory /path/to/supysonic>
+		WSGIApplicationGroup %{GLOBAL}
+		Order deny,allow
+		Allow from all
+	</Directory>
+
+With that kind of configuration, the server address will look like *http://server/supysonic/*
+
+Quickstart
+----------
+
+The first time you run the server, open its URL to set the initial configuration. You'll be asked to create
+a first user. This user will be an admin of the server.
+
+Once the first user created, log in to the app. Then you can add other users or manage folders. Folders are
+where your music is located. Add one, then hit the scan button. The scanning process might take some time on
+large libraries, so be patient. Your browser might even timeout even if the process is still running. Once
+scanning is done, you can enjoy your music with the client of your choice.
+