diff --git a/README.md b/README.md index b04a073..8f41e4a 100644 --- 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 -[api]: API-INFO.md +[transcoding]: docs/trancoding.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 -"production" server) or as a WSGI application (on Apache for instance). +_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 ### 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` -* 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 +* _MySQL_: `pip install pymysql` or `pip install mysqlclient` +* _PostgreSQL_: `pip install psycopg2` ### Database initialization -Supysonic does not issue the `CREATE TABLE` commands for the tables it needs. -Thus the database and tables must be created prior to running the application. -Table creation scripts are provided in the `schema` folder for SQLite, MySQL -and PostgreSQL. +_Supysonic_ needs a database to run. It can either be a _SQLite_, +_MySQL_-compatible or _PostgreSQL_ database. + +_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 -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. +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: +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 +### 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. +_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 + $ 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 -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 -`/etc/apache2/envvars` file, comment the line `export LANG=C` and uncomment -the `. /etc/default/locale` line. Then you can restart Apache: +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_: - $ 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 -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`. As with -WSGI, you might need to edit those file to suit your system configuration. +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][]. +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 `). - -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] (-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 -``` - ## 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. +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 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 -run a watcher that will listen to any library change and update the database +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 `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 -background, either use the old `nohup` or `screen` methods, or start it as a -simple systemd unit (unit file not included). +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). ## Upgrading -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. +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. + 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 diff --git a/config.sample b/config.sample index 5066a07..bef5936 100644 --- 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 diff --git a/API-INFO.md b/docs/api.md similarity index 99% rename from API-INFO.md rename to docs/api.md index 3ffc852..a28c87c 100644 --- a/API-INFO.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 | + diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..cfa84d5 --- /dev/null +++ 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 `). + +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 [-a] [-p ] [-e ] + supysonic-cli user delete + supysonic-cli user changepass + supysonic-cli user list + supysonic-cli user setadmin [--off] + +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 +``` + +## Folder management commands + +``` +Usage: + supysonic-cli folder add + supysonic-cli folder delete + supysonic-cli folder list + supysonic-cli folder scan [...] + +Arguments: + add Add a new folder + delete Delete a folder + list List all the folders + scan Scan all or specified folders +``` + diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..913dbb8 --- /dev/null +++ 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 +``` + diff --git a/docs/transcoding.md b/docs/transcoding.md new file mode 100644 index 0000000..889a4ed --- /dev/null +++ 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 - +``` +