Reworked and split documentation

2024-09-19 10:51:04 +00:00 · 2018-02-14 19:45:39 +01:00 · 2018-02-14 19:45:39 +01:00 · 6160fdc321
commit 6160fdc321
parent 005ae4803b
6 changed files with 443 additions and 269 deletions
--- a/README.md
+++ b/README.md
@ -1,6 +1,6 @@
 # Supysonic
-Supysonic is a Python implementation of the [Subsonic][] server API.
+_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)
@ -9,45 +9,45 @@ 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
+* [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].
+_Supysonic_ currently targets the version 1.8.0 of the _Subsonic_ API. For more
 details, go check the [API implementation status][docs-api].
 [subsonic]: http://www.subsonic.org/
-[lastfm]: https://last.fm
+[transcoding]: docs/trancoding.md
-[api]: API-INFO.md
+[lastfm]: https://last.fm/
 [docs-api]: docs/api.md
 ## Table of contents
 * [Installation](#installation)
  + [Prerequisites](#prerequisites)
  + [Configuration](#configuration)
  + [Database initialization](#database-initialization)
  + [Configuration](#configuration)
 * [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
+_Supysonic_ can run as a standalone application (not recommended for a
-"production" server) or as a WSGI application (on Apache for instance).
+"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:
+You'll need these to run _Supysonic_:
 * Python 2.7 or >= 3.5
 * [Flask](http://flask.pocoo.org/) >= 0.9
@ -63,123 +63,88 @@ You can install all of them using `pip`:
 You may also need a database specific package:
-* MySQL: `pip install pymysql` or `pip install mysqlclient`
+* _MySQL_: `pip install pymysql` or `pip install mysqlclient`
-* PostgreSQL: `pip install psycopg2`
+* _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.
+_Supysonic_ needs a database to run. It can either be a _SQLite_,
-Thus the database and tables must be created prior to running the application.
+_MySQL_-compatible or _PostgreSQL_ database.
-Table creation scripts are provided in the `schema` folder for SQLite, MySQL
+
-and PostgreSQL.
+_Supysonic_ does not automatically create the database and tables it needs to
 work. Thus the database and tables must be created prior to running the
 application. Please refer to the documentation of the DBMS you've chosen on how
 to create a database and how to use a command-line client.
 Table creation scripts are provided in the `schema` folder for _SQLite_,
 _MySQL_ and _PostgreSQL_. Just feed them to any client you're able to use.
 If you absolutely have no clue about databases, you can go with _SQLite_.
 You'll just need the `sqlite3` command-line tool. Install it and create the
 database and tables with the following commands:
    $ apt install sqlite3
    $ sqlite3 /some/path/to/a/supysonic.db < schema/sqlite.sql
 Remember the path you've used for the database file
 (`/some/path/to/a/supysonic.db` in the example above), you'll need it in the
 configuration file.
 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 the _SQLite_ database created on the example
 above whould be:
 ```ini
 [base]
 database_uri = sqlite:////some/path/to/a/supysonic.db
 ```
 For a more details on the configuration, please refer to
 [documentation][docs-config].
 [docs-config]: docs/configuration.md
 ## Running the application
 ### As a standalone debug server
-It is possible to run Supysonic as a standalone server, but it is only
+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
+recommended to do so if you are hacking on the source. A standalone won't be
-be able to serve more than one request at a time.
+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
+5000, but you can specify another address on the command line, for instance on
-on all the IPv6 interfaces:
+all the IPv6 interfaces:
    $ python cgi-bin/server.py ::
-### As an Apache WSGI application
+### As an _Apache_ WSGI application
-Supysonic can run as a WSGI application with the `cgi-bin/supysonic.wsgi` file.
+_Supysonic_ can run as a WSGI application with the `cgi-bin/supysonic.wsgi`
-To run it within an Apache2 server, first you need to install the WSGI module
+file. To run it within an _Apache2_ server, first you need to install the WSGI
-and enable it.
+module and enable it.
-    $ apt-get install libapache2-mod-wsgi
+    $ apt install libapache2-mod-wsgi
    $ a2enmod wsgi
-Next, edit the Apache configuration to load the application. Here's a basic
+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
@ -190,175 +155,41 @@ example of what it looks like:
        Allow from all
    </Directory>
-You might also need to run Apache using the system default locale, as the one
+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
+it uses might cause problems while scanning the library from the web UI. To do
-`/etc/apache2/envvars` file, comment the line `export LANG=C` and uncomment
+so, edit the `/etc/apache2/envvars` file, comment the line `export LANG=C` and
-the `. /etc/default/locale` line. Then you can restart Apache:
+uncomment the `. /etc/default/locale` line. Then you can restart _Apache_:
-    $ service apache2 restart
+    $ systemctl restart apache2
-With that kind of configuration, the server address will look like *http://server/supysonic/*
+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
+If you use another HTTP server, such as _nginx_ or _lighttpd_, or prefer to use
-use FastCGI or CGI over WSGI, FastCGI and CGI scripts are also provided in the
+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
+`cgi-bin` folder, respectively as `supysonic.fcgi` and `supysonic.cgi`. You
-WSGI, you might need to edit those file to suit your system configuration.
+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][].
+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 <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 message for the user command
    folder                      Display the help message 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
 ```
 ## Quickstart
-To start using Supysonic, you'll first have to specify where your music library
+To start using _Supysonic_, you'll first have to specify where your music
-is located and create a user to allow calls to the API.
+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
+    $ 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/spl0k/Music
+    $ supysonic-cli folder add MyLibrary /home/username/Music
 Once you've added a folder, you will need to scan it:
@ -366,23 +197,30 @@ Once you've added a folder, you will need to scan it:
 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][docs-cli].
 [docs-cli]: docs/cli.md
 ## Watching library changes
-Instead of manually running a scan every time your library changes, you can
+Instead of manually running a scan every time your library changes, you can run
-run a watcher that will listen to any library change and update the database
+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
+print anything to the console. If you want to keep it running in background,
-background, either use the old `nohup` or `screen` methods, or start it as a
+either use the old `nohup` or `screen` methods, or start it as a simple
-simple systemd unit (unit file not included).
+_systemd_ unit (unit file not included).
 ## Upgrading
-Some commits might introduce changes in the database schema. When that's
+Some commits might introduce changes in the database schema. When that's the
-the case migration scripts will be provided in the `schema/migration`
+case migration scripts will be provided in the `schema/migration` folder,
-folder, prefixed by the date of commit that introduced the changes. Those
+prefixed by the date of commit that introduced the changes. Those scripts
-scripts shouldn't be used when initializing a new database, only when
+shouldn't be used when initializing a new database, only when upgrading from a
-upgrading from a previous schema.
+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
--- a/config.sample
+++ b/config.sample
@ -1,6 +1,6 @@
 [base]
 ; A database URI. See the 'schema' folder for schema creation scripts
-; Default: sqlite:///tmp/supysonic/supysonic.db
+; 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
--- a/docs/api.md
+++ b/docs/api.md
@ -129,3 +129,4 @@ At the moment, the current target API version is 1.8.0
 | `getBookmarks`           | N/A    | From API v1.9.0                          |
 | `createBookmark`         | N/A    | From API v1.9.0                          |
 | `deleteBookmark`         | N/A    | From API v1.9.0                          |
--- a/docs/cli.md
+++ b/docs/cli.md
@ -0,0 +1,65 @@
 # Command line interface
 The command-line interface (often abbreviated CLI) is an interface allowing
 administration operations without the use of the web interface. It can either
 be run in interactive mode (`supysonic-cli`) or to issue a single command
 (`supysonic-cli <arguments>`).
 If ran without arguments, `supysonic-cli` will open an interactive prompt. You
 can use the command line tool to do a few things:
 ## Help commands
 Whenever you are lost
 ```
 Usage:
    supysonic-cli help
    supysonic-cli help user
    supysonic-cli help folder
 Arguments:
    user                        Display the help message for the user command
    folder                      Display the help message for the folder command
 ```
 ## User management commands
 ```
 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>
 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
 ```
 ## Folder management commands
 ```
 Usage:
    supysonic-cli folder add <name> <path>
    supysonic-cli folder delete <name>
    supysonic-cli folder list
    supysonic-cli folder scan [<name>...]
 Arguments:
    add                         Add a new folder
    delete                      Delete a folder
    list                        List all the folders
    scan                        Scan all or specified folders
 ```
--- a/docs/configuration.md
+++ b/docs/configuration.md
@ -0,0 +1,191 @@
 # 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.
 You'll find a roughly documented configuration sample file at the root of the
 project, file conveniently named `config.sample`. More details below.
 There are six sections in the configuration:
 - [base](#base-section): defines the database and additional scanning config
 - [webapp](#webapp-section): configuration relative to the HTTP server
 - [daemon](#daemon-section): configuration for the scanning file watcher
 - [lastfm](#lastfm-section): keys to enable Last.FM scrobbling
 - [transcoding](#transcoding-section): defines transcoding  programs
 - [mimetypes](#mimetypes-section): some file extension to mimetype mappings
 ## `[base]` section
 `database_uri`: the most important configuration, defines the type and
 parameters of the database _Supysonic_ should connect to. It usually includes
 username, password, hostname and database name. The typical form of a database
 URI is:
    driver://username:password@host:port/database
 Supported drivers are `sqlite`, `mysql` and `postgres` (or `postgresql`)
 As SQLite connects to local files, the format is slightly different. The "file"
 portion of the URI is the filename of the database. For a relative path, it
 requires three slashes, for absolute paths it's also three slashes followed by
 the absolute path, meaning actually four slashes on Unix systems.
 ```ini
 ; Relative path
 database_uri = sqlite:///relative-file.db
 ; Absolute path on Unix-based systems
 database_uri = sqlite:////home/user/supysonic.db
 ; Absolute path on Windows
 database_uri = sqlite:///C:\Users\user\supysonic.db
 ```
 A MySQL-compatible database require either `MySQLdb` or `pymysql` to be
 installed. PostgreSQL needs `psycopg2`.
 If `database_uri` isn't provided, it defaults to a SQLite database stored in
 `/tmp/supysonic/supysonic.db`.
 `scanner_extensions`: A space separated list of file extensions the scanner is
 restricted to. Useful if you have multiple audio formats in your library but
 only want to serve some. If left empty, the scanner will try to read every file
 it finds.
 ```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]` section
 `cache_dir`: directory used to store generated files, such as resized cover
 arts. Defaults to `/tmp/supysonic`.
 `log_file`: rotating file where some events generated by the web server are
 logged. Leave empty to disable logging.
 `log_level`: defines the minimum severity threshold of messages to be added to
 `log_file`. Possible values are: `DEBUG`, `INFO`, `WARNING`, `ERROR` and
 `CRITICAL`. Defaults to `WARNING`.
 `mount_api`: [`on`/`off`] enable or disable the Subsonic REST API. Should be
 kept on or _Supysonic_ would be quite useless. Exists mostly for testing
 purposes. Defaults to `on`.
 `mount_webui`: [`on`/`off`] enable or disable the administrative web interface.
 Note that setting this off will prevent users from defining a preferred
 transcoding format. Defaults to `on`.
 ```ini
 [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]` section
 `wait_delay`: delay before triggering the 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 seconds.
 `log_file`: rotating file where events generated by the file watcher are logged.
 Leave empty to disable logging.
 `log_level`: defines the minimum severity threshold of messages to be added to
 `log_file`. Possible values are: `DEBUG`, `INFO`, `WARNING`, `ERROR` and
 `CRITICAL`. Defaults to `WARNING`.
 ```ini
 [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]` section
 This section allow defining API keys to enable Last.FM integration in
 _Supysonic_. Currently it is only used to _scrobble_ played tracks and update
 the _now playing_ information.
 See https://www.last.fm/api to obtain such keys.
 Once keys are set, users have to link their account by visiting their profile
 page on _Supysonic_'s administrative UI.
 `api_key`: Last.FM API key
 `secret`: secret key associated to the API key
 ```ini
 [lastfm]
 ; API and secret key to enable scrobbling. http://www.last.fm/api/accounts
 ; Defaults: none
 ;api_key =
 ;secret =
 ```
 ## `[transcoding]` section
 This section defines command-line programs to be used to convert an audio file
 to another format or change its bitrate. All configurations in the sample below
 have **not** been thoroughly tested.
 For more details, please refer to the
 [transcoding configuration](transcoding.md).
 ```ini
 [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]` section
 Use this section if the system _Supysonic_ is installed on has trouble guessing
 the mimetype of some files. This might only be useful in some rare cases.
 See the following links for a list of examples:
 * https://en.wikipedia.org/wiki/Media_type#Common_examples
 * https://www.iana.org/assignments/media-types/media-types.xhtml
 ```ini
 [mimetypes]
 ; Extension to mimetype mappings in case your system has some trouble guessing
 ; Default: none
 ;mp3 = audio/mpeg
 ;ogg = audio/vorbis
 ```
--- a/docs/transcoding.md
+++ b/docs/transcoding.md
@ -0,0 +1,79 @@
 # 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.
 Transcoding in _Supysonic_ 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 to your profile page
 on the web interface.
 ## Configuration
 Configuration of transcoders is done on the `[transcoding]` section of the
 [configuration file](configuration.md).
 Transcoding can be done by one single program which is able to convert from one
 format directly 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.
 ```ini
 [transcoding]
 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 -
 ```