mirror of
https://github.com/spl0k/supysonic.git
synced 2024-12-23 01:16:18 +00:00
merge the wiki with the README
This commit is contained in:
Louis-Philippe Véronneau
parent
78b795dc4c
commit
34fa03f719
243
README.md
243
README.md
@ -23,16 +23,20 @@ For more details, go check the [API implementation status wiki page](https://git
|
||||
+ [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 parameters](#command-line-parameters)
|
||||
+ [Examples](#examples)
|
||||
* [Quickstart](#quickstart)
|
||||
* [Scanner daemon](#scanner-daemon)
|
||||
* [Upgrading](#upgrading)
|
||||
* [Current target API version](#current-target-api-version)
|
||||
|
||||
## 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
|
||||
$ python setup.py install
|
||||
|
||||
### Prerequisites
|
||||
|
||||
@ -50,7 +54,7 @@ You'll need these to run Supysonic:
|
||||
On a Debian-like OS (Debian, Ubuntu, Linux Mint, etc.), you can install them
|
||||
this way:
|
||||
|
||||
apt-get install python-flask python-storm python-imaging python-simplesjon python-requests python-mutagen python-watchdog
|
||||
$ apt-get install python-flask python-storm python-imaging python-simplesjon python-requests python-mutagen python-watchdog
|
||||
|
||||
You may also need a database specific package. For example, if you choose to
|
||||
use MySQL, you will need to install `python-mysqldb`.
|
||||
@ -96,20 +100,20 @@ hacking on the source. A standalone won't be able to serve more than one request
|
||||
|
||||
To start the server, just run the `cgi-bin/server.py` script.
|
||||
|
||||
python cgi-bin/server.py
|
||||
$ 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 ::
|
||||
$ 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
|
||||
$ 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:
|
||||
|
||||
@ -125,7 +129,7 @@ You might also need to run Apache using the system default locale, as the one it
|
||||
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
|
||||
$ service apache2 restart
|
||||
|
||||
With that kind of configuration, the server address will look like *http://server/supysonic/*
|
||||
|
||||
@ -138,6 +142,151 @@ As with WSGI, you might need to edit those file to suit your system configuratio
|
||||
Here are some quick docs on how to configure your server for [FastCGI](http://flask.pocoo.org/docs/deploying/fastcgi/)
|
||||
or [CGI](http://flask.pocoo.org/docs/deploying/cgi/).
|
||||
|
||||
## Trancoding
|
||||
|
||||
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.
|
||||
|
||||
### 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 parameters
|
||||
|
||||
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 <arguments>`).
|
||||
|
||||
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 mesage for the user command
|
||||
folder Display the help mesage for the folder command
|
||||
```
|
||||
|
||||
```
|
||||
Usage:
|
||||
supysonic-cli user [add] <user> (-a) (-p <password>) (-e <email>)
|
||||
supysonic-cli user [delete] <user>
|
||||
supysonic-cli user [changepass] <user> <password>
|
||||
supysonic-cli user [list]
|
||||
supysonic-cli user [setadmin] (--off) <user>
|
||||
|
||||
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 <password> Specify the user's password
|
||||
-e --email <email> Specify the user's email
|
||||
--off Revoke the admin rights if present
|
||||
```
|
||||
|
||||
```
|
||||
Usage:
|
||||
supysonic-cli folder [add] <name> <path>
|
||||
supysonic-cli folder [delete] <name>
|
||||
supysonic-cli folder [list]
|
||||
supysonic-cli folder [scan] <name>
|
||||
|
||||
Folder management commands
|
||||
|
||||
Arguments:
|
||||
add Add a new folder
|
||||
delete Delete a folder
|
||||
list List all the folders
|
||||
scan Scan a specified folder
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
You can add a new admin user this way:
|
||||
|
||||
$ supysonic-cli user add spl0k -a -p MyAwesomePassword
|
||||
|
||||
To add a new folder, you can use something like this:
|
||||
|
||||
$ supysonic-cli folder add MyLibrary /home/spl0k/Music
|
||||
|
||||
Once you've added it, you will need to scan it:
|
||||
|
||||
$ supysonic-cli folder scan MyLibrary
|
||||
|
||||
## Quickstart
|
||||
|
||||
To start using Supysonic, you'll first have to specify where your music library is located and create a user
|
||||
@ -161,3 +310,83 @@ and can be run as an *init.d* script.
|
||||
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.
|
||||
|
||||
## Current target API version
|
||||
|
||||
At the moment, the current target API version is 1.8.0
|
||||
|
||||
<table>
|
||||
<tr><th>Module</th><th>API call</th><th>Status</th><th>Comments</th></tr>
|
||||
|
||||
<tr><th rowspan="2">System</th> <td>ping</td> <td style="background-color: green">Done</td> <td></td></tr>
|
||||
<tr> <td>getLicense</td> <td>Done</td> <td></td></tr>
|
||||
|
||||
<tr><th rowspan="9">Browsing</th> <td>getMusicFolders</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>getIndexes</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>getMusicDirectory</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>getGenres</td> <td>N/A</td> <td>From API v1.9.0</td></tr>
|
||||
<tr> <td>getArtists</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>getArtist</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>getAlbum</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>getSong</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>getVideos</td> <td>Done</td> <td>Actually returns an error as video support is not planned</td></tr>
|
||||
|
||||
<tr><th rowspan="7">Album/song lists</th> <td>getAlbumList</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>getAlbumList2</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>getRandomSongs</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>getSongsByGenre</td> <td>N/A</td> <td>From API v1.9.0</td></tr>
|
||||
<tr> <td>getNowPlaying</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>getStarred</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>getStarred2</td> <td>Done</td> <td></td></tr>
|
||||
|
||||
<tr><th rowspan="3">Searching</th> <td>search</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>search2</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>search3</td> <td>Done</td> <td></td></tr>
|
||||
|
||||
<tr><th rowspan="5">Playlists</th> <td>getPlaylists</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>getPlaylist</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>createPlaylist</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>updatePlaylist</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>deletePlaylist</td> <td>Done</td> <td></td></tr>
|
||||
|
||||
<tr><th rowspan="6">Media retrieval</th> <td>stream</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>download</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>hls</td> <td>N/A</td> <td>Video related stuff, not planned</td></tr>
|
||||
<tr> <td>getCoverArt</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>getLyrics</td> <td>Done</td> <td>Use either text files or ChartLyrics API</td></tr>
|
||||
<tr> <td>getAvatar</td> <td><strong>TODO</strong></td> <td>Not that useful for a streaming server, but whatever</td></tr>
|
||||
|
||||
<tr><th rowspan="4">Media annotation</th> <td>star</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>unstar</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>setRating</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>scrobble</td> <td>Done</td> <td></td></tr>
|
||||
|
||||
<tr><th rowspan="4">Sharing</th> <td>getShares</td> <td><strong>TODO</strong></td> <td rowspan="4">Need to look how this works on the official Subsonic server</td></tr>
|
||||
<tr> <td>createShare</td> <td><strong>TODO</strong></td></tr>
|
||||
<tr> <td>updateShare</td> <td><strong>TODO</strong></td></tr>
|
||||
<tr> <td>deleteShare</td> <td><strong>TODO</strong></td></tr>
|
||||
|
||||
<tr><th rowspan="6">Podcast</th> <td>getPodcasts</td> <td>N/A</td> <td>Not planning to support podcasts at the moment</td></tr>
|
||||
<tr> <td>refreshPodcasts</td> <td>N/A</td> <td>From API v1.9.0</td></tr>
|
||||
<tr> <td>createPodcastChannel</td> <td>N/A</td> <td>From API v1.9.0</td></tr>
|
||||
<tr> <td>deletePodcastChannel</td> <td>N/A</td> <td>From API v1.9.0</td></tr>
|
||||
<tr> <td>deletePodcastEpisode</td> <td>N/A</td> <td>From API v1.9.0</td></tr>
|
||||
<tr> <td>downloadPodcastEpisode</td> <td>N/A</td> <td>From API v1.9.0</td></tr>
|
||||
|
||||
<tr><th>Jukebox</th> <td>jukeboxControl</td> <td>N/A</td> <td>Not planning to support the Jukebox feature</td></tr>
|
||||
|
||||
<tr><th>Internet radio</th> <td>getInternetRadioStations </td> <td>N/A</td> <td>From API v1.9.0</td></tr>
|
||||
|
||||
<tr><th rowspan="2">Chat</th> <td>getChatMessages</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>addChatMessage </td> <td>Done</td> <td></td></tr>
|
||||
|
||||
<tr><th rowspan="5">User management</th> <td>getUser</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>getUsers</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>createUser</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>deleteUser</td> <td>Done</td> <td></td></tr>
|
||||
<tr> <td>changePassword </td> <td>Done</td> <td></td></tr>
|
||||
|
||||
<tr><th rowspan="3">Bookmarks</th> <td>getBookmarks</td> <td>N/A</td> <td>From API v1.9.0</td></tr>
|
||||
<tr> <td>createBookmark</td> <td>N/A</td> <td>From API v1.9.0</td></tr>
|
||||
<tr> <td>deleteBookmark</td> <td>N/A</td> <td>From API v1.9.0</td></tr>
|
||||
</table>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user