From 34fa03f719c718f144d23ddd2ea88481f45b8df9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Louis-Philippe=20V=C3=A9ronneau?= Date: Sat, 24 Jun 2017 15:23:50 -0400 Subject: [PATCH] merge the wiki with the README --- README.md | 243 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 236 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index cf65c27..3a799bb 100644 --- a/README.md +++ b/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 `). + +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] (-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 +``` + +### 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ModuleAPI callStatusComments
System ping Done
getLicense Done
Browsing getMusicFolders Done
getIndexes Done
getMusicDirectory Done
getGenres N/A From API v1.9.0
getArtists Done
getArtist Done
getAlbum Done
getSong Done
getVideos Done Actually returns an error as video support is not planned
Album/song lists getAlbumList Done
getAlbumList2 Done
getRandomSongs Done
getSongsByGenre N/A From API v1.9.0
getNowPlaying Done
getStarred Done
getStarred2 Done
Searching search Done
search2 Done
search3 Done
Playlists getPlaylists Done
getPlaylist Done
createPlaylist Done
updatePlaylist Done
deletePlaylist Done
Media retrieval stream Done
download Done
hls N/A Video related stuff, not planned
getCoverArt Done
getLyrics Done Use either text files or ChartLyrics API
getAvatar TODO Not that useful for a streaming server, but whatever
Media annotation star Done
unstar Done
setRating Done
scrobble Done
Sharing getShares TODO Need to look how this works on the official Subsonic server
createShare TODO
updateShare TODO
deleteShare TODO
Podcast getPodcasts N/A Not planning to support podcasts at the moment
refreshPodcasts N/A From API v1.9.0
createPodcastChannel N/A From API v1.9.0
deletePodcastChannel N/A From API v1.9.0
deletePodcastEpisode N/A From API v1.9.0
downloadPodcastEpisode N/A From API v1.9.0
Jukebox jukeboxControl N/A Not planning to support the Jukebox feature
Internet radio getInternetRadioStations N/A From API v1.9.0
Chat getChatMessages Done
addChatMessage Done
User management getUser Done
getUsers Done
createUser Done
deleteUser Done
changePassword Done
Bookmarks getBookmarks N/A From API v1.9.0
createBookmark N/A From API v1.9.0
deleteBookmark N/A From API v1.9.0