From cfc324e346402a63e4e3bfa9f55a9950eabbc711 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Tue, 29 Dec 2020 11:39:34 +0100 Subject: [PATCH 01/14] Rewriting docs as reStructuredText Starting with the configuration page The goal being to publish it outside of GitHub --- docs/configuration.md | 250 --------------------------------- docs/configuration.rst | 307 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 307 insertions(+), 250 deletions(-) delete mode 100644 docs/configuration.md create mode 100644 docs/configuration.rst diff --git a/docs/configuration.md b/docs/configuration.md deleted file mode 100644 index ecdbe60..0000000 --- a/docs/configuration.md +++ /dev/null @@ -1,250 +0,0 @@ -# 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 - -If the connection needs some additional parameters, they can be provided as a -query string, such as: - - driver://username:password@host:port/database?param1=value1¶m2=value2 - -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 requires either `MySQLdb` or `pymysql` to be -installed. PostgreSQL needs `psycopg2`. -Note that for MySQL if no character set is defined on the URI it defaults to -`utf8mb4` regardless of what's set on your MySQL installation. - -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. - -`follow_symlinks`: if set to `yes`, allows the scanner to follow symbolic links. -Disabled by default, enable it only if you trust your file system as nothing is -done to handle broken links or loops. - -```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 - -; Should the scanner follow symbolic links? Default: no -follow_symlinks = no -``` - -## `[webapp]` section - -`cache_dir`: directory used to store generated files, such as resized cover -art or transcoded files. Defaults to `/tmp/supysonic`. - -`cache_size`: maximum size (in megabytes) of the cache (except for trancodes). -Defaults to 512 MB - -`transcode_cache_size`: maximum size (in megabytes) of the transcode cache. -Defaults to 1024 MB (1 GB) - -`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`. - -`index_ignored_prefixes`: space separated list of prefixes that should be -ignored from artist names when returning their index. Example: if the word _The_ -is in this list, artist _The Rolling Stones_ will be listed under the letter _R_. -The match is case insensitive. -Defaults to `El La Le Las Les Los The`. - -```ini -[webapp] -; Optional cache directory. Default: /tmp/supysonic -cache_dir = /var/supysonic/cache - -; Main cache max size in MB. Default: 512 -cache_size = 512 - -; Transcode cache max size in MB. Default: 1024 (1GB) -transcode_cache_size = 1024 - -; 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 - -; Space separated list of prefixes that should be ignored on index endpoints -; Default: El La Le Las Les Los The -index_ignored_prefixes = El La Le Las Les Los The -``` - -## `[daemon]` section - -`socket`: Unix domain socket file (or named pipe on Windows) used to communicate -between the daemon and clients that rely on it (eg. CLI, folder admin web page, -etc.). Note that using an IP address here isn't supported. -Default: /tmp/supysonic/supysonic.sock - -`run_watcher`: whether or not to start the watcher that will listen for library -changes. Default: yes - -`wait_delay`: delay (in seconds) 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. - -`jukebox_command` : command used by the jukebox mode to play a single file. -See the [jukebox documentation](jukebox.md) for more details. - -`log_file`: rotating file where events generated by the file watcher are logged. -If left empty, any logging will be sent to stderr. - -`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] -; Socket file the daemon will listen on for incoming management commands -; Default: /tmp/supysonic/supysonic.sock -socket = /var/run/supysonic.sock - -; Defines if the file watcher should be started. Default: yes -run_watcher = yes - -; Delay in seconds 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 - -; Command used by the jukebox -jukebox_command = mplayer -ss %offset %path - -; Optional rotating log file for the scanner daemon. Logs to stderr if empty -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/configuration.rst b/docs/configuration.rst new file mode 100644 index 0000000..01e1230 --- /dev/null +++ b/docs/configuration.rst @@ -0,0 +1,307 @@ +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. + +``[base]`` section +------------------ + +This sections defines the database and additional scanning config. + +``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 + + If the connection needs some additional parameters, they can be provided as a + query string, such as:: + + driver://username:password@host:port/database?param1=value1¶m2=value2 + + 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. + + .. code-block:: 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 requires either ``MySQLdb`` or ``pymysql`` to be + installed. PostgreSQL needs ``psycopg2``. + + .. note:: + + For MySQL if no character set is defined on the URI it defaults to + ``utf8mb4`` regardless of what's set on your MySQL installation. + + 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. + +``follow_symlinks`` + If set to ``yes``, allows the scanner to follow symbolic links. + + Disabled by default, enable it only if you trust your file system as nothing + is done to handle broken links or loops. + +Sample configuration: + +.. code-block:: 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 + + ; Should the scanner follow symbolic links? Default: no + follow_symlinks = no + +``[webapp]`` section +-------------------- + +Configuration relative to the HTTP server. + +``cache_dir``: + Directory used to store generated files, such as resized cover art or + transcoded files. Defaults to ``/tmp/supysonic``. + +``cache_size`` + Maximum size (in megabytes) of the cache (except for trancodes). + Defaults to 512 MB. + +``transcode_cache_size`` + Maximum size (in megabytes) of the transcode cache. + Defaults to 1024 MB (1 GB). + +``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`` + * ``CRITICAL`` + + Defaults to ``WARNING``. + +``mount_api`` (``on`` or ``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`` or ``off``) + Enable or disable the administrative web interface. + + .. note:: + Setting this off will prevent users from defining a preferred transcoding + format. + + Defaults to ``on``. + +``index_ignored_prefixes`` + Space-separated list of prefixes that should be ignored from artist names + when returning their index. Example: if the word *The* is in this list, + artist *The Rolling Stones* will be listed under the letter *R*. The match is + case insensitive. + Defaults to ``El La Le Las Les Los The``. + +Sample configuration: + +.. code-block:: ini + + [webapp] + ; Optional cache directory. Default: /tmp/supysonic + cache_dir = /var/supysonic/cache + + ; Main cache max size in MB. Default: 512 + cache_size = 512 + + ; Transcode cache max size in MB. Default: 1024 (1GB) + transcode_cache_size = 1024 + + ; 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 + + ; Space separated list of prefixes that should be ignored on index endpoints + ; Default: El La Le Las Les Los The + index_ignored_prefixes = El La Le Las Les Los The + +``[daemon]`` section +-------------------- + +Configuration for the daemon process that is used to watch for changes in the +library folders and providing the jukebox feature. + +``socket`` + Unix domain socket file (or named pipe on Windows) used to communicate + between the daemon and clients that rely on it (eg. CLI, folder admin web + page, etc.). Note that using an IP address here isn't supported. + Default: /tmp/supysonic/supysonic.sock + +``run_watcher`` + Whether or not to start the watcher that will listen for library changes. + Default: yes + +``wait_delay`` + Delay (in seconds) 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. + +``jukebox_command`` + Command used by the jukebox mode to play a single file. + See the :doc:`jukebox documentation ` for more details. + +``log_file`` + Rotating file where events generated by the file watcher are logged. + If left empty, any logging will be sent to stderr. + +``log_level`` + Defines the minimum severity threshold of messages to be added to + ``log_file``. Possible values are: + + * ``DEBUG`` + * ``INFO`` + * ``WARNING`` + * ``ERROR`` + * ``CRITICAL`` + + Defaults to ``WARNING``. + +Sample configuration: + +.. code-block:: ini + + [daemon] + ; Socket file the daemon will listen on for incoming management commands + ; Default: /tmp/supysonic/supysonic.sock + socket = /var/run/supysonic.sock + + ; Defines if the file watcher should be started. Default: yes + run_watcher = yes + + ; Delay in seconds 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 + + ; Command used by the jukebox + jukebox_command = mplayer -ss %offset %path + + ; Optional rotating log file for the scanner daemon. Logs to stderr if empty + 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 + +Sample configuration: + +.. code-block:: 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 +:doc:`transcoding configuration `. + +.. code-block:: 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 + +.. code-block:: ini + + [mimetypes] + ; Extension to mimetype mappings in case your system has some trouble guessing + ; Default: none + ;mp3 = audio/mpeg + ;ogg = audio/vorbis From ff75ff1230d72c6c5f53055a334698921ec7a3c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Tue, 29 Dec 2020 12:50:15 +0100 Subject: [PATCH 02/14] Docs as reST: transcoding --- docs/configuration.rst | 4 +- docs/transcoding.md | 105 ------------------------------- docs/transcoding.rst | 139 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 142 insertions(+), 106 deletions(-) delete mode 100644 docs/transcoding.md create mode 100644 docs/transcoding.rst diff --git a/docs/configuration.rst b/docs/configuration.rst index 01e1230..d83b1b4 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -90,7 +90,7 @@ Sample configuration: Configuration relative to the HTTP server. -``cache_dir``: +``cache_dir`` Directory used to store generated files, such as resized cover art or transcoded files. Defaults to ``/tmp/supysonic``. @@ -266,6 +266,8 @@ Sample configuration: ;api_key = ;secret = +.. _conf-transcoding: + ``[transcoding]`` section ------------------------- diff --git a/docs/transcoding.md b/docs/transcoding.md deleted file mode 100644 index 9b9fa28..0000000 --- a/docs/transcoding.md +++ /dev/null @@ -1,105 +0,0 @@ -# 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` -* `default_transcode_target` - -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 -* `%title`: title of the file to transcode -* `%album`: album name of the file to transcode -* `%artist`: artist name of the file to transcode -* `%tracknumber`: track number of the file to transcode -* `%totaltracks`: number of tracks in the album of the file to transcode -* `%discnumber`: disc number of the file to transcode -* `%genre`: genre of the file to transcode (not always available, defaults to "") -* `%year`: year of the file to transcode (not always available, defaults to "") - -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. - -The value of `default_transcode_target` will be used as output format when a -client requests a bitrate lower than the original file and no specific format. - -## Suggested configuration - -Here is an example configuration that you could use. This is provided as-is, -and some configurations haven't been tested. - -Basic configuration: -```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 - -default_transcode_target = mp3 -``` - -To include track metadata in the transcoded stream: -```ini -[transcoding] -transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate --tt %title --tl %album --ta %artist --tn %tracknumber/%totaltracks --tv TPOS=%discnumber --tg %genre --ty %year --add-id3v2 %srcpath - -transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -metadata title=%title -metadata album=%album -metadata author=%artist -metadata track=%tracknumber/%totaltracks -metadata disc=%discnumber -metadata genre=%genre -metadata date=%year -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 --tt %title --tl %album --ta %artist --tn %tracknumber/%totaltracks --tv TPOS=%discnumber --tg %genre --ty %year --add-id3v2 - - -encoder_ogg = oggenc2 -Q -M %outrate -t %title -l %album -a %artist -N %tracknumber -c TOTALTRACKS=%totaltracks -c DISCNUMBER=%discnumber -G %genre -d %year - -default_transcode_target = mp3 -``` diff --git a/docs/transcoding.rst b/docs/transcoding.rst new file mode 100644 index 0000000..ba45744 --- /dev/null +++ b/docs/transcoding.rst @@ -0,0 +1,139 @@ +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 :ref:`conf-transcoding` of the +configuration file. + +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`` +* ``default_transcode_target`` + +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. +The value of ``default_transcode_target`` will be used as output format when a +client requests a bitrate lower than the original file and no specific format. + +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: + +#. specific transcoder +#. specific decoder / specific encoder +#. generic decoder / generic encoder (with the possibility to use a generic + decoder with a specific encoder, and vice-versa) +#. 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 +``%title`` + title of the file to transcode +``%album`` + album name of the file to transcode +``%artist`` + artist name of the file to transcode +``%tracknumber`` + track number of the file to transcode +``%totaltracks`` + number of tracks in the album of the file to transcode +``%discnumber`` + disc number of the file to transcode +``%genre`` + genre of the file to transcode (not always available, defaults to "") +``%year`` + year of the file to transcode (not always available, defaults to "") + +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 (decoders +output being piped into encoders) + +Suggested configuration +^^^^^^^^^^^^^^^^^^^^^^^ + +Here is an example configuration that you could use. This is provided as-is, +and some configurations haven't been tested. + +Basic configuration: + +.. code-block:: 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 - + default_transcode_target = mp3 + +To include track metadata in the transcoded stream: + +.. code-block:: ini + + [transcoding] + transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate --tt %title --tl %album --ta %artist --tn %tracknumber/%totaltracks --tv TPOS=%discnumber --tg %genre --ty %year --add-id3v2 %srcpath - + transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -metadata title=%title -metadata album=%album -metadata author=%artist -metadata track=%tracknumber/%totaltracks -metadata disc=%discnumber -metadata genre=%genre -metadata date=%year -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 --tt %title --tl %album --ta %artist --tn %tracknumber/%totaltracks --tv TPOS=%discnumber --tg %genre --ty %year --add-id3v2 - - + encoder_ogg = oggenc2 -Q -M %outrate -t %title -l %album -a %artist -N %tracknumber -c TOTALTRACKS=%totaltracks -c DISCNUMBER=%discnumber -G %genre -d %year - + default_transcode_target = mp3 + +Enabling transcoding +-------------------- + +Once the transcoding configuration has been set, most clients will require the +user to specify that they want to transcode files. This might be done on the +client itself, but most importantly it should be done on *Supysonic* web +interface. Not doing so might prevent some clients to properly request +transcoding. + +To enable transcoding with the web interface, you should first start using the +client you want to set transcoding for. Only browsing the library should +suffice. Then open your browser of choice and navigate to the URL of your +*Supysonic* instance. Log in with your credentials and the click on your +username in the top bar. There you should be presented with a list of clients +you used to connect to *Supysonic* and be able to set you preferred streaming +format and bitrate. From 2ff1080fd43a8723341360c2f968754404b7dead Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Tue, 29 Dec 2020 13:03:28 +0100 Subject: [PATCH 03/14] Docs as reST: jukebox --- docs/configuration.rst | 2 ++ docs/jukebox.md | 43 ----------------------------------------- docs/jukebox.rst | 44 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 46 insertions(+), 43 deletions(-) delete mode 100644 docs/jukebox.md create mode 100644 docs/jukebox.rst diff --git a/docs/configuration.rst b/docs/configuration.rst index d83b1b4..11d91db 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -171,6 +171,8 @@ Sample configuration: ; Default: El La Le Las Les Los The index_ignored_prefixes = El La Le Las Les Los The +.. _conf-daemon: + ``[daemon]`` section -------------------- diff --git a/docs/jukebox.md b/docs/jukebox.md deleted file mode 100644 index 5d3a0b8..0000000 --- a/docs/jukebox.md +++ /dev/null @@ -1,43 +0,0 @@ -# Jukebox - -The jukebox mode allow playing audio files on the hardware of the machine -running Supysonic, using regular clients that support it as a remote control. - -The daemon must be running in order to be able to use the jukebox mode. So be -sure to start the `supysonic-daemon` command and keep it running. A basic -_systemd_ service file can be found at the root of the project folder. - -## Setting the player program - -Jukebox mode in _Supysonic_ works 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. The chosen program should be able to play a -single audio file from a path specified on its command-line. - -The configuration is done in the `[daemon]` section of the -[configuration file](configuration.md), with the `jukebox_command` variable. -This variable should include the following fields: - -- `%path`: absolute path of the file to be played -- `%offset`: time in seconds where to start playing (used for seeking) - -Here's an example using `mplayer`: -``` -jukebox_command = mplayer -ss %offset %path -``` - -Or using `mpv`: -``` -jukebox_command = mpv --start=%offset %path -``` - -Setting the output volume isn't currently supported. - -## Allowing users to act on the jukebox - -The jukebox mode is only accessible to chosen users. Granting (or revoking) -jukebox usage rights to a specific user is done with the [CLI](cli.md): - -``` -$ supysonic-cli user setroles --jukebox -``` diff --git a/docs/jukebox.rst b/docs/jukebox.rst new file mode 100644 index 0000000..80dda29 --- /dev/null +++ b/docs/jukebox.rst @@ -0,0 +1,44 @@ +Jukebox mode +============ + +The jukebox mode allow playing audio files on the hardware of the machine +running *Supysonic*, using regular clients that support it as a remote control. + +The daemon must be running in order to be able to use the jukebox mode. So be +sure to start the ``supysonic-daemon`` command and keep it running. A basic +*systemd* service file can be found at the root of the project folder. + +Setting the player program +-------------------------- + +Jukebox mode in *Supysonic* works 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. The chosen program should be able to play a +single audio file from a path specified on its command-line. + +The configuration is done in the :ref:`conf-daemon` of the configuration file, +with the ``jukebox_command`` variable. This variable should include the +following fields: + +``%path`` + absolute path of the file to be played +``%offset`` + time in seconds where to start playing (used for seeking) + +Here's an example using ``mplayer``:: + + jukebox_command = mplayer -ss %offset %path + +Or using ``mpv``:: + + jukebox_command = mpv --start=%offset %path + +Setting the output volume isn't currently supported. + +Allowing users to act on the jukebox +------------------------------------ + +The jukebox mode is only accessible to chosen users. Granting (or revoking) +jukebox usage rights to a specific user is done with the :doc:`cli`:: + + $ supysonic-cli user setroles --jukebox From 1c65fdede673c9d5688c1a011e116bee39f0028e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Tue, 29 Dec 2020 18:29:20 +0100 Subject: [PATCH 04/14] Docs to reST: api --- docs/api.md | 917 ----------------------------------- docs/api.rst | 1286 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1286 insertions(+), 917 deletions(-) delete mode 100644 docs/api.md create mode 100644 docs/api.rst diff --git a/docs/api.md b/docs/api.md deleted file mode 100644 index 6412730..0000000 --- a/docs/api.md +++ /dev/null @@ -1,917 +0,0 @@ -# API breakdown - -This page lists all the API methods and their parameters up to the version -1.16.0 (Subsonic 6.1.2). Here you'll find details about which API features -_Supysonic_ support, plan on supporting, or won't. - -At the moment, the current target API version is 1.10.2. - -The following information was gathered by _diff_-ing various snapshots of the -[Subsonic API page](http://www.subsonic.org/pages/api.jsp). - -- [Methods and parameters listing](#methods-and-parameters-listing) -- [Changes by version](#changes-by-version) - -## Methods and parameters listing - -Statuses explanation: -- πŸ“…: planned -- βœ”οΈ: done -- ❌: done as not supported -- πŸ”΄: won't be implemented -- ❔: not decided yet - -The version column specifies the API version which added the related method or -parameter. When no version is given, it means the item was introduced prior to -or with version 1.8.0. - -### All methods / pseudo-TOC - -| Method | Vers. | | -|-------------------------------------------------------------|--------|---| -| [`ping`](#ping) | | βœ”οΈ | -| [`getLicense`](#getlicense) | | βœ”οΈ | -| [`getMusicFolders`](#getmusicfolders) | | βœ”οΈ | -| [`getIndexes`](#getindexes) | | βœ”οΈ | -| [`getMusicDirectory`](#getmusicdirectory) | | βœ”οΈ | -| [`getGenres`](#getgenres) | 1.9.0 | βœ”οΈ | -| [`getArtists`](#getartists) | | βœ”οΈ | -| [`getArtist`](#getartist) | | βœ”οΈ | -| [`getAlbum`](#getalbum) | | βœ”οΈ | -| [`getSong`](#getsong) | | βœ”οΈ | -| [`getVideos`](#getvideos) | | ❌ | -| [`getVideoInfo`](#getvideoinfo) | 1.15.0 | πŸ”΄ | -| [`getArtistInfo`](#getartistinfo) | 1.11.0 | πŸ“… | -| [`getArtistInfo2`](#getartistinfo2) | 1.11.0 | πŸ“… | -| [`getAlbumInfo`](#getalbuminfo) | 1.14.0 | πŸ“… | -| [`getAlbumInfo2`](#getalbuminfo2) | 1.14.0 | πŸ“… | -| [`getSimilarSongs`](#getsimilarsongs) | 1.11.0 | ❔ | -| [`getSimilarSongs2`](#getsimilarsongs2) | 1.11.0 | ❔ | -| [`getTopSongs`](#gettopsongs) | 1.13.0 | ❔ | -| [`getAlbumList`](#getalbumlist) | | βœ”οΈ | -| [`getAlbumList2`](#getalbumlist2) | | βœ”οΈ | -| [`getRandomSongs`](#getrandomsongs) | | βœ”οΈ | -| [`getSongsByGenre`](#getsongsbygenre) | 1.9.0 | βœ”οΈ | -| [`getNowPlaying`](#getnowplaying) | | βœ”οΈ | -| [`getStarred`](#getstarred) | | βœ”οΈ | -| [`getStarred2`](#getstarred2) | | βœ”οΈ | -| [`search`](#search) | | βœ”οΈ | -| [`search2`](#search2) | | βœ”οΈ | -| [`search3`](#search3) | | βœ”οΈ | -| [`getPlaylists`](#getplaylists) | | βœ”οΈ | -| [`getPlaylist`](#getplaylist) | | βœ”οΈ | -| [`createPlaylist`](#createplaylist) | | βœ”οΈ | -| [`updatePlaylist`](#updateplaylist) | | βœ”οΈ | -| [`deletePlaylist`](#deleteplaylist) | | βœ”οΈ | -| [`stream`](#stream) | | βœ”οΈ | -| [`download`](#download) | | βœ”οΈ | -| [`hls`](#hls) | 1.9.0 | πŸ”΄ | -| [`getCaptions`](#getcaptions) | 1.15.0 | πŸ”΄ | -| [`getCoverArt`](#getcoverart) | | βœ”οΈ | -| [`getLyrics`](#getlyrics) | | βœ”οΈ | -| [`getAvatar`](#getavatar) | | ❌ | -| [`star`](#star) | | βœ”οΈ | -| [`unstar`](#unstar) | | βœ”οΈ | -| [`setRating`](#setrating) | | βœ”οΈ | -| [`scrobble`](#scrobble) | | βœ”οΈ | -| [`getShares`](#getshares) | | ❌ | -| [`createShare`](#createshare) | | ❌ | -| [`updateShare`](#updateshare) | | ❌ | -| [`deleteShare`](#deleteshare) | | ❌ | -| [`getPodcasts`](#getpodcasts) | | ❔ | -| [`getNewestPodcasts`](#getnewestpodcasts) | 1.14.0 | ❔ | -| [`refreshPodcasts`](#refreshpodcasts) | 1.9.0 | ❔ | -| [`createPodcastChannel`](#createpodcastchannel) | 1.9.0 | ❔ | -| [`deletePodcastChannel`](#deletepodcastchannel) | 1.9.0 | ❔ | -| [`deletePodcastEpisode`](#deletepodcastepisode) | 1.9.0 | ❔ | -| [`downloadPodcastEpisode`](#downloadpodcastepisode) | 1.9.0 | ❔ | -| [`jukeboxControl`](#jukeboxcontrol) | | βœ”οΈ | -| [`getInternetRadioStations`](#getinternetradiostations) | 1.9.0 | βœ”οΈ | -| [`createInternetRadioStation`](#createinternetradiostation) | 1.16.0 | βœ”οΈ | -| [`updateInternetRadioStation`](#updateinternetradiostation) | 1.16.0 | βœ”οΈ | -| [`deleteInternetRadioStation`](#deleteinternetradiostation) | 1.16.0 | βœ”οΈ | -| [`getChatMessages`](#getchatmessages) | | βœ”οΈ | -| [`addChatMessage`](#addchatmessage) | | βœ”οΈ | -| [`getUser`](#getuser) | | βœ”οΈ | -| [`getUsers`](#getusers) | 1.9.0 | βœ”οΈ | -| [`createUser`](#createuser) | | βœ”οΈ | -| [`updateUser`](#updateuser) | 1.10.2 | βœ”οΈ | -| [`deleteUser`](#deleteuser) | | βœ”οΈ | -| [`changePassword`](#changepassword) | | βœ”οΈ | -| [`getBookmarks`](#getbookmarks) | 1.9.0 | ❔ | -| [`createBookmark`](#createbookmark) | 1.9.0 | ❔ | -| [`deleteBookmark`](#deletebookmark) | 1.9.0 | ❔ | -| [`getPlayQueue`](#getplayqueue) | 1.12.0 | ❔ | -| [`savePlayQueue`](#saveplayqueue) | 1.12.0 | ❔ | -| [`getScanStatus`](#getscanstatus) | 1.15.0 | βœ”οΈ | -| [`startScan`](#startscan) | 1.15.0 | βœ”οΈ | - -### Global - -Parameters used for any request - -| P. | Vers. | | -|-----|--------|---| -| `u` | | βœ”οΈ | -| `p` | | βœ”οΈ | -| `t` | 1.13.0 | πŸ”΄ | -| `s` | 1.13.0 | πŸ”΄ | -| `v` | | βœ”οΈ | -| `c` | | βœ”οΈ | -| `f` | | βœ”οΈ | - -Error codes - -| # | Vers. | | -|----|--------|---| -| 0 | | βœ”οΈ | -| 10 | | βœ”οΈ | -| 20 | | βœ”οΈ | -| 30 | | βœ”οΈ | -| 40 | | βœ”οΈ | -| 41 | 1.15.0 | πŸ“… | -| 50 | | βœ”οΈ | -| 60 | | βœ”οΈ | -| 70 | | βœ”οΈ | - -### System - -#### `ping` -βœ”οΈ -No parameter - -#### `getLicense` -βœ”οΈ -No parameter - -### Browsing - -#### `getMusicFolders` -βœ”οΈ -No parameter - -#### `getIndexes` -βœ”οΈ - -| Parameter | Vers. | | -|-------------------|-------|---| -| `musicFolderId` | | βœ”οΈ | -| `ifModifiedSince` | | βœ”οΈ | - -#### `getMusicDirectory` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | - -#### `getGenres` -βœ”οΈ 1.9.0 -No parameter - -#### `getArtists` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------|--------|---| -| `musicFolderId` | 1.14.0 | πŸ“… | - -#### `getArtist` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | - -#### `getAlbum` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | - -#### `getSong` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | - -#### `getVideos` -❌ -No parameter - -#### `getVideoInfo` -πŸ”΄ 1.15.0 - -| Parameter | Vers. | | -|-----------|--------|---| -| `id` | 1.15.0 | πŸ”΄ | - -#### `getArtistInfo` -πŸ“… 1.11.0 - -| Parameter | Vers. | | -|---------------------|--------|---| -| `id` | 1.11.0 | πŸ“… | -| `count` | 1.11.0 | πŸ“… | -| `includeNotPresent` | 1.11.0 | πŸ“… | - -#### `getArtistInfo2` -πŸ“… 1.11.0 - -| Parameter | Vers. | | -|---------------------|--------|---| -| `id` | 1.11.0 | πŸ“… | -| `count` | 1.11.0 | πŸ“… | -| `includeNotPresent` | 1.11.0 | πŸ“… | - -#### `getAlbumInfo` -πŸ“… 1.14.0 - -| Parameter | Vers. | | -|-----------|--------|---| -| `id` | 1.14.0 | πŸ“… | - -#### `getAlbumInfo2` -πŸ“… 1.14.0 - -| Parameter | Vers. | | -|-----------|--------|---| -| `id` | 1.14.0 | πŸ“… | - -#### `getSimilarSongs` -❔ 1.11.0 - -| Parameter | Vers. | | -|-----------|--------|---| -| `id` | 1.11.0 | ❔ | -| `count` | 1.11.0 | ❔ | - -#### `getSimilarSongs2` -❔ 1.11.0 - -| Parameter | Vers. | | -|-----------|--------|---| -| `id` | 1.11.0 | ❔ | -| `count` | 1.11.0 | ❔ | - -#### `getTopSongs` -❔ 1.13.0 - -| Parameter | Vers. | | -|-----------|--------|---| -| `artist` | 1.13.0 | ❔ | -| `count` | 1.13.0 | ❔ | - -### Album/song lists - -#### `getAlbumList` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------|--------|---| -| `type` | | βœ”οΈ | -| `size` | | βœ”οΈ | -| `offset` | | βœ”οΈ | -| `fromYear` | | βœ”οΈ | -| `toYear` | | βœ”οΈ | -| `genre` | | βœ”οΈ | -| `musicFolderId` | 1.12.0 | πŸ“… | - -On 1.10.1, `byYear` and `byGenre` were added to `type` - -#### `getAlbumList2` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------|--------|---| -| `type` | | βœ”οΈ | -| `size` | | βœ”οΈ | -| `offset` | | βœ”οΈ | -| `fromYear` | | βœ”οΈ | -| `toYear` | | βœ”οΈ | -| `genre` | | βœ”οΈ | -| `musicFolderId` | 1.12.0 | πŸ“… | - -On 1.10.1, `byYear` and `byGenre` were added to `type` - -#### `getRandomSongs` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------|-------|---| -| `size` | | βœ”οΈ | -| `genre` | | βœ”οΈ | -| `fromYear` | | βœ”οΈ | -| `toYear` | | βœ”οΈ | -| `musicFolderId` | | βœ”οΈ | - -#### `getSongsByGenre` -βœ”οΈ 1.9.0 - -| Parameter | Vers. | | -|-----------------|--------|---| -| `genre` | 1.9.0 | βœ”οΈ | -| `count` | 1.9.0 | βœ”οΈ | -| `offset` | 1.9.0 | βœ”οΈ | -| `musicFolderId` | 1.12.0 | πŸ“… | - -#### `getNowPlaying` -βœ”οΈ -No parameter - -#### `getStarred` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------|--------|---| -| `musicFolderId` | 1.12.0 | πŸ“… | - -#### `getStarred2` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------|--------|---| -| `musicFolderId` | 1.12.0 | πŸ“… | - -### Searching - -#### `search` -βœ”οΈ - -| Parameter | Vers. | | -|-------------|-------|---| -| `artist` | | βœ”οΈ | -| `album` | | βœ”οΈ | -| `title` | | βœ”οΈ | -| `any` | | βœ”οΈ | -| `count` | | βœ”οΈ | -| `offset` | | βœ”οΈ | -| `newerThan` | | βœ”οΈ | - -#### `search2` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------|--------|---| -| `query` | | βœ”οΈ | -| `artistCount` | | βœ”οΈ | -| `artistOffset` | | βœ”οΈ | -| `albumCount` | | βœ”οΈ | -| `albumOffset` | | βœ”οΈ | -| `songCount` | | βœ”οΈ | -| `songOffset` | | βœ”οΈ | -| `musicFolderId` | 1.12.0 | πŸ“… | - -#### `search3` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------|--------|---| -| `query` | | βœ”οΈ | -| `artistCount` | | βœ”οΈ | -| `artistOffset` | | βœ”οΈ | -| `albumCount` | | βœ”οΈ | -| `albumOffset` | | βœ”οΈ | -| `songCount` | | βœ”οΈ | -| `songOffset` | | βœ”οΈ | -| `musicFolderId` | 1.12.0 | πŸ“… | - -### Playlists - -#### `getPlaylists` -βœ”οΈ - -| Parameter | Vers. | | -|------------|-------|---| -| `username` | | βœ”οΈ | - -#### `getPlaylist` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | - -#### `createPlaylist` -βœ”οΈ - -| Parameter | Vers. | | -|--------------|-------|---| -| `playlistId` | | βœ”οΈ | -| `name` | | βœ”οΈ | -| `songId` | | βœ”οΈ | - -#### `updatePlaylist` -βœ”οΈ - -| Parameter | Vers. | | -|---------------------|-------|---| -| `playlistId` | | βœ”οΈ | -| `name` | | βœ”οΈ | -| `comment` | | βœ”οΈ | -| `public` | 1.9.0 | βœ”οΈ | -| `songIdToAdd` | | βœ”οΈ | -| `songIndexToRemove` | | βœ”οΈ | - -#### `deletePlaylist` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | - -### Media retrieval - -#### `stream` -βœ”οΈ - -| Parameter | Vers. | | -|-------------------------|--------|---| -| `id` | | βœ”οΈ | -| `maxBitRate` | | βœ”οΈ | -| `format` | | βœ”οΈ | -| `timeOffset` | | ❌ | -| `size` | | ❌ | -| `estimateContentLength` | | βœ”οΈ | -| `converted` | 1.15.0 | πŸ”΄ | - -#### `download` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | - -#### `hls` -πŸ”΄ 1.9.0 - -| Parameter | Vers. | | -|--------------|--------|---| -| `id` | 1.9.0 | πŸ”΄ | -| `bitRate` | 1.9.0 | πŸ”΄ | -| `audioTrack` | 1.15.0 | πŸ”΄ | - -#### `getCaptions` -πŸ”΄ 1.15.0 - -| Parameter | Vers. | | -|-------------|--------|---| -| `id` | 1.15.0 | πŸ”΄ | -| `format` | 1.15.0 | πŸ”΄ | - -#### `getCoverArt` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | -| `size` | | βœ”οΈ | - -#### `getLyrics` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `artist` | | βœ”οΈ | -| `title` | | βœ”οΈ | - -#### `getAvatar` -❌ - -| Parameter | Vers. | | -|------------|-------|---| -| `username` | | ❌ | - -### Media annotation - -#### `star` -βœ”οΈ - -| Parameter | Vers. | | -|------------|-------|---| -| `id` | | βœ”οΈ | -| `albumId` | | βœ”οΈ | -| `artistId` | | βœ”οΈ | - -#### `unstar` -βœ”οΈ - -| Parameter | Vers. | | -|------------|-------|---| -| `id` | | βœ”οΈ | -| `albumId` | | βœ”οΈ | -| `artistId` | | βœ”οΈ | - -#### `setRating` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | βœ”οΈ | -| `rating` | | βœ”οΈ | - -#### `scrobble` -βœ”οΈ - -| Parameter | Vers. | | -|--------------|-------|---| -| `id` | | βœ”οΈ | -| `time` | 1.9.0 | βœ”οΈ | -| `submission` | | βœ”οΈ | - -### Sharing - -#### `getShares` -❌ -No parameter - -#### `createShare` -❌ - -| Parameter | Vers. | | -|---------------|-------|---| -| `id` | | ❌ | -| `description` | | ❌ | -| `expires` | | ❌ | - -#### `updateShare` -❌ - -| Parameter | Vers. | | -|---------------|-------|---| -| `id` | | ❌ | -| `description` | | ❌ | -| `expires` | | ❌ | - -#### `deleteShare` -❌ - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | | ❌ | - -### Podcast - -#### `getPodcasts` -❔ - -| Parameter | Vers. | | -|-------------------|-------|---| -| `includeEpisodes` | 1.9.0 | ❔ | -| `id` | 1.9.0 | ❔ | - -#### `getNewestPodcasts` -❔ 1.14.0 - -| Parameter | Vers. | | -|-----------|--------|---| -| `count` | 1.14.0 | ❔ | - -#### `refreshPodcasts` -❔ 1.9.0 - -No parameter - -#### `createPodcastChannel` -❔ 1.9.0 - -| Parameter | Vers. | | -|-----------|-------|---| -| `url` | 1.9.0 | ❔ | - -#### `deletePodcastChannel` -❔ 1.9.0 - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | 1.9.0 | ❔ | - -#### `deletePodcastEpisode` -❔ 1.9.0 - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | 1.9.0 | ❔ | - - -#### `downloadPodcastEpisode` -❔ 1.9.0 - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | 1.9.0 | ❔ | - -### Jukebox - -#### `jukeboxControl` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `action` | | βœ”οΈ | -| `index` | | βœ”οΈ | -| `offset` | | βœ”οΈ | -| `id` | | βœ”οΈ | -| `gain` | | ❌ | - -### Internet radio - -#### `getInternetRadioStations` -❔ 1.9.0 - -No parameter - -#### `createInternetRadioStation` -❔ 1.16.0 - -| Parameter | Vers. | | -|---------------|--------|---| -| `streamUrl` | 1.16.0 | ❔ | -| `name` | 1.16.0 | ❔ | -| `homepageUrl` | 1.16.0 | ❔ | - -#### `updateInternetRadioStation` -❔ 1.16.0 - -| Parameter | Vers. | | -|---------------|--------|---| -| `id` | 1.16.0 | ❔ | -| `streamUrl` | 1.16.0 | ❔ | -| `name` | 1.16.0 | ❔ | -| `homepageUrl` | 1.16.0 | ❔ | - -#### `deleteInternetRadioStation` -❔ 1.16.0 - -| Parameter | Vers. | | -|-----------|--------|---| -| `id` | 1.16.0 | ❔ | - -### Chat - -#### `getChatMessages` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `since` | | βœ”οΈ | - -#### `addChatMessage` -βœ”οΈ - -| Parameter | Vers. | | -|-----------|-------|---| -| `message` | | βœ”οΈ | - -### User management - -#### `getUser` -βœ”οΈ - -| Parameter | Vers. | | -|------------|-------|---| -| `username` | | βœ”οΈ | - -#### `getUsers` -βœ”οΈ 1.9.0 - -No parameter - -#### `createUser` -βœ”οΈ - -| Parameter | Vers. | | -|-----------------------|--------|---| -| `username` | | βœ”οΈ | -| `password` | | βœ”οΈ | -| `email` | | βœ”οΈ | -| `ldapAuthenticated` | | | -| `adminRole` | | βœ”οΈ | -| `settingsRole` | | | -| `streamRole` | | | -| `jukeboxRole` | | βœ”οΈ | -| `downloadRole` | | | -| `uploadRole` | | | -| `playlistRole` | | | -| `coverArtRole` | | | -| `commentRole` | | | -| `podcastRole` | | | -| `shareRole` | | | -| `videoConversionRole` | 1.14.0 | | -| `musicFolderId` | 1.12.0 | πŸ“… | - -#### `updateUser` -βœ”οΈ 1.10.2 - -| Parameter | Vers. | | -|-----------------------|--------|---| -| `username` | 1.10.2 | βœ”οΈ | -| `password` | 1.10.2 | βœ”οΈ | -| `email` | 1.10.2 | βœ”οΈ | -| `ldapAuthenticated` | 1.10.2 | | -| `adminRole` | 1.10.2 | βœ”οΈ | -| `settingsRole` | 1.10.2 | | -| `streamRole` | 1.10.2 | | -| `jukeboxRole` | 1.10.2 | βœ”οΈ | -| `downloadRole` | 1.10.2 | | -| `uploadRole` | 1.10.2 | | -| `coverArtRole` | 1.10.2 | | -| `commentRole` | 1.10.2 | | -| `podcastRole` | 1.10.2 | | -| `shareRole` | 1.10.2 | | -| `videoConversionRole` | 1.14.0 | | -| `musicFolderId` | 1.12.0 | πŸ“… | -| `maxBitRate` | 1.13.0 | πŸ“… | - -#### `deleteUser` -βœ”οΈ - -| Parameter | Vers. | | -|------------|--------|---| -| `username` | | βœ”οΈ | - -#### `changePassword` -βœ”οΈ - -| Parameter | Vers. | | -|------------|--------|---| -| `username` | | βœ”οΈ | -| `password` | | βœ”οΈ | - -### Bookmarks - -#### `getBookmarks` -❔ 1.9.0 -No parameter - -#### `createBookmark` -❔ 1.9.0 - -| Parameter | Vers. | | -|------------|-------|---| -| `id` | 1.9.0 | ❔ | -| `position` | 1.9.0 | ❔ | -| `comment` | 1.9.0 | ❔ | - -#### `deleteBookmark` -❔ 1.9.0 - -| Parameter | Vers. | | -|-----------|-------|---| -| `id` | 1.9.0 | ❔ | - -#### `getPlayQueue` -❔ 1.12.0 -No parameter - -#### `savePlayQueue` -❔ 1.12.0 - -| Parameter | Vers. | | -|------------|--------|---| -| `id` | 1.12.0 | ❔ | -| `current` | 1.12.0 | ❔ | -| `position` | 1.12.0 | ❔ | - -### Library scanning - -#### `getScanStatus` -βœ”οΈ 1.15.0 -No parameter - -#### `startScan` -βœ”οΈ 1.15.0 -No parameter - -## Changes by version - -### Version 1.9.0 - -Added methods: -- `getGenres` -- `getSongsByGenre` -- `hls` -- `refreshPodcasts` -- `createPodcastChannel` -- `deletePodcastChannel` -- `deletePodcastEpisode` -- `downloadPodcastEpisode` -- `getInternetRadioStations` -- `getUsers` -- `getBookmarks` -- `createBookmark` -- `deleteBookmark` - -Added method parameters: -- `updatePlaylist` - - `public` -- `scrobble` - - `time` -- `getPodcasts` - - `includeEpisodes` - - `id` - -### Version 1.10.1 - -Added method parameters: -- `getAlbumList` - - `fromYear` - - `toYear` - - `genre` -- `getAlbumList2` - - `fromYear` - - `toYear` - - `genre` - -### Version 1.10.2 - -Added methods: -- `updateUser` - -### Version 1.11.0 - -Added methods: -- `getArtistInfo` -- `getArtistInfo2` -- `getSimilarSongs` -- `getSimilarSongs2` - -### Version 1.12.0 - -Added methods: -- `getPlayQueue` -- `savePlayQueue` - -Added method parameters: -- `getAlbumList` - - `musicFolderId` -- `getAlbumList2` - - `musicFolderId` -- `getSongsByGenre` - - `musicFolderId` -- `getStarred` - - `musicFolderId` -- `getStarred2` - - `musicFolderId` -- `search2` - - `musicFolderId` -- `search3` - - `musicFolderId` -- `createUser` - - `musicFolderId` -- `updateUser` - - `musicFolderId` - -### Version 1.13.0 - -Added global parameters: -- `t` -- `s` - -Added methods: -- `getTopSongs` - -Added method parameters: -- `updateUser` - - `maxBitRate` - -### Version 1.14.0 - -Added methods: -- `getAlbumInfo` -- `getAlbumInfo2` -- `getNewestPodcasts` - -Added method parameters: -- `getArtists` - - `musicFolderId` -- `createUser` - - `videoConversionRole` -- `updateUser` - - `videoConversionRole` - -### Version 1.15.0 - -Added error code `41` - -Added methods: -- `getVideoInfo` -- `getCaptions` -- `getScanStatus` -- `startScan` - -Added method parameters: -- `stream` - - `converted` -- `hls` - - `audioTrack` - -### Version 1.16.0 - -Added methods: -- `createInternetRadioStation` -- `updateInternetRadioStation` -- `deleteInternetRadioStation` - diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..d3612a2 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,1286 @@ +Subsonic API breakdown +====================== + +This page lists all the API methods and their parameters up to the version +1.16.0 (Subsonic 6.1.2). Here you'll find details about which API features +*Supysonic* support, plan on supporting, or won't. + +At the moment, the current target API version is 1.10.2. + +The following information was gathered by *diff*-ing various snapshots of the +`Subsonic API page `_. + +Methods and parameters listing +------------------------------ + +Statuses explanation: + +* πŸ“…: planned +* βœ”οΈ: done +* ❌: done as not supported +* πŸ”΄: won't be implemented +* ❔: not decided yet + +The version column specifies the API version which added the related method or +parameter. When no version is given, it means the item was introduced prior to +or with version 1.8.0. + +All methods / pseudo-TOC +^^^^^^^^^^^^^^^^^^^^^^^^ + +============================================================== ====== = +Method Vers. +============================================================== ====== = +:ref:`ping ` βœ”οΈ +:ref:`getLicense ` βœ”οΈ +:ref:`getMusicFolders ` βœ”οΈ +:ref:`getIndexes ` βœ”οΈ +:ref:`getMusicDirectory ` βœ”οΈ +:ref:`getGenres ` 1.9.0 βœ”οΈ +:ref:`getArtists ` βœ”οΈ +:ref:`getArtist ` βœ”οΈ +:ref:`getAlbum ` βœ”οΈ +:ref:`getSong ` βœ”οΈ +:ref:`getVideos ` ❌ +:ref:`getVideoInfo ` 1.15.0 πŸ”΄ +:ref:`getArtistInfo ` 1.11.0 πŸ“… +:ref:`getArtistInfo2 ` 1.11.0 πŸ“… +:ref:`getAlbumInfo ` 1.14.0 πŸ“… +:ref:`getAlbumInfo2 ` 1.14.0 πŸ“… +:ref:`getSimilarSongs ` 1.11.0 ❔ +:ref:`getSimilarSongs2 ` 1.11.0 ❔ +:ref:`getTopSongs ` 1.13.0 ❔ +:ref:`getAlbumList ` βœ”οΈ +:ref:`getAlbumList2 ` βœ”οΈ +:ref:`getRandomSongs ` βœ”οΈ +:ref:`getSongsByGenre ` 1.9.0 βœ”οΈ +:ref:`getNowPlaying ` βœ”οΈ +:ref:`getStarred ` βœ”οΈ +:ref:`getStarred2 ` βœ”οΈ +:ref:`search ` βœ”οΈ +:ref:`search2 ` βœ”οΈ +:ref:`search3 ` βœ”οΈ +:ref:`getPlaylists ` βœ”οΈ +:ref:`getPlaylist ` βœ”οΈ +:ref:`createPlaylist ` βœ”οΈ +:ref:`updatePlaylist ` βœ”οΈ +:ref:`deletePlaylist ` βœ”οΈ +:ref:`stream ` βœ”οΈ +:ref:`download ` βœ”οΈ +:ref:`hls ` 1.9.0 πŸ”΄ +:ref:`getCaptions ` 1.15.0 πŸ”΄ +:ref:`getCoverArt ` βœ”οΈ +:ref:`getLyrics ` βœ”οΈ +:ref:`getAvatar ` ❌ +:ref:`star ` βœ”οΈ +:ref:`unstar ` βœ”οΈ +:ref:`setRating ` βœ”οΈ +:ref:`scrobble ` βœ”οΈ +:ref:`getShares ` ❌ +:ref:`createShare ` ❌ +:ref:`updateShare ` ❌ +:ref:`deleteShare ` ❌ +:ref:`getPodcasts ` ❔ +:ref:`getNewestPodcasts ` 1.14.0 ❔ +:ref:`refreshPodcasts ` 1.9.0 ❔ +:ref:`createPodcastChannel ` 1.9.0 ❔ +:ref:`deletePodcastChannel ` 1.9.0 ❔ +:ref:`deletePodcastEpisode ` 1.9.0 ❔ +:ref:`downloadPodcastEpisode ` 1.9.0 ❔ +:ref:`jukeboxControl ` βœ”οΈ +:ref:`getInternetRadioStations ` 1.9.0 βœ”οΈ +:ref:`createInternetRadioStation ` 1.16.0 βœ”οΈ +:ref:`updateInternetRadioStation ` 1.16.0 βœ”οΈ +:ref:`deleteInternetRadioStation ` 1.16.0 βœ”οΈ +:ref:`getChatMessages ` βœ”οΈ +:ref:`addChatMessage ` βœ”οΈ +:ref:`getUser ` βœ”οΈ +:ref:`getUsers ` 1.9.0 βœ”οΈ +:ref:`createUser ` βœ”οΈ +:ref:`updateUser ` 1.10.2 βœ”οΈ +:ref:`deleteUser ` βœ”οΈ +:ref:`changePassword ` βœ”οΈ +:ref:`getBookmarks ` 1.9.0 ❔ +:ref:`createBookmark ` 1.9.0 ❔ +:ref:`deleteBookmark ` 1.9.0 ❔ +:ref:`getPlayQueue ` 1.12.0 ❔ +:ref:`savePlayQueue ` 1.12.0 ❔ +:ref:`getScanStatus ` 1.15.0 βœ”οΈ +:ref:`startScan ` 1.15.0 βœ”οΈ +============================================================== ====== = + +Global +^^^^^^ + +Parameters used for any request + +===== ====== = +P. Vers. +===== ====== = +``u`` βœ”οΈ +``p`` βœ”οΈ +``t`` 1.13.0 πŸ”΄ +``s`` 1.13.0 πŸ”΄ +``v`` βœ”οΈ +``c`` βœ”οΈ +``f`` βœ”οΈ +===== ====== = + +Error codes + +== ====== = +# Vers. +== ====== = +0 βœ”οΈ +10 βœ”οΈ +20 βœ”οΈ +30 βœ”οΈ +40 βœ”οΈ +41 1.15.0 πŸ“… +50 βœ”οΈ +60 βœ”οΈ +70 βœ”οΈ +== ====== = + +System +^^^^^^ + +.. _ping: + +``ping`` + βœ”οΈ + + No parameter + +.. _getLicense: + +``getLicense`` + βœ”οΈ + + No parameter + +Browsing +^^^^^^^^ + +.. _getMusicFolders: + +``getMusicFolders`` + βœ”οΈ + + No parameter + +.. _getIndexes: + +``getIndexes`` + βœ”οΈ + + =================== ===== = + Parameter Vers. + =================== ===== = + ``musicFolderId`` βœ”οΈ + ``ifModifiedSince`` βœ”οΈ + =================== ===== = + +.. _getMusicDirectory: + +``getMusicDirectory`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _getGenres: + +``getGenres`` + βœ”οΈ 1.9.0 + + No parameter + +.. _getArtists: + +``getArtists`` + βœ”οΈ + + ================= ====== = + Parameter Vers. + ================= ====== = + ``musicFolderId`` 1.14.0 πŸ“… + ================= ====== = + +.. _getArtist: + +``getArtist`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _getAlbum: + +``getAlbum`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _getSong: + +``getSong`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _getVideos: + +``getVideos`` + ❌ + + No parameter + +.. _getVideoInfo: + +``getVideoInfo`` + πŸ”΄ 1.15.0 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``id`` 1.15.0 πŸ”΄ + ========= ====== = + +.. _getArtistInfo: + +``getArtistInfo`` + πŸ“… 1.11.0 + + ===================== ====== = + Parameter Vers. + ===================== ====== = + ``id`` 1.11.0 πŸ“… + ``count`` 1.11.0 πŸ“… + ``includeNotPresent`` 1.11.0 πŸ“… + ===================== ====== = + +.. _getArtistInfo2: + +``getArtistInfo2`` + πŸ“… 1.11.0 + + ===================== ====== = + Parameter Vers. + ===================== ====== = + ``id`` 1.11.0 πŸ“… + ``count`` 1.11.0 πŸ“… + ``includeNotPresent`` 1.11.0 πŸ“… + ===================== ====== = + +.. _getAlbumInfo: + +``getAlbumInfo`` + πŸ“… 1.14.0 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``id`` 1.14.0 πŸ“… + ========= ====== = + +.. _getAlbumInfo2: + +``getAlbumInfo2`` + πŸ“… 1.14.0 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``id`` 1.14.0 πŸ“… + ========= ====== = + +.. _getSimilarSongs: + +``getSimilarSongs`` + ❔ 1.11.0 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``id`` 1.11.0 ❔ + ``count`` 1.11.0 ❔ + ========= ====== = + +.. _getSimilarSongs2: + +``getSimilarSongs2`` + ❔ 1.11.0 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``id`` 1.11.0 ❔ + ``count`` 1.11.0 ❔ + ========= ====== = + +.. _getTopSongs: + +``getTopSongs`` + ❔ 1.13.0 + + ========== ====== = + Parameter Vers. + ========== ====== = + ``artist`` 1.13.0 ❔ + ``count`` 1.13.0 ❔ + ========== ====== = + +Album/song lists +^^^^^^^^^^^^^^^^ + +.. _getAlbumList: + +``getAlbumList`` + βœ”οΈ + + ================= ====== = + Parameter Vers. + ================= ====== = + ``type`` βœ”οΈ + ``size`` βœ”οΈ + ``offset`` βœ”οΈ + ``fromYear`` βœ”οΈ + ``toYear`` βœ”οΈ + ``genre`` βœ”οΈ + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + + .. versionadded:: 1.10.1 + ``byYear`` and ``byGenre`` were added to ``type`` + +.. _getAlbumList2: + +``getAlbumList2`` + βœ”οΈ + + ================= ====== = + Parameter Vers. + ================= ====== = + ``type`` βœ”οΈ + ``size`` βœ”οΈ + ``offset`` βœ”οΈ + ``fromYear`` βœ”οΈ + ``toYear`` βœ”οΈ + ``genre`` βœ”οΈ + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + + .. versionadded:: 1.10.1 + ``byYear`` and ``byGenre`` were added to ``type`` + +.. _getRandomSongs: + +``getRandomSongs`` + βœ”οΈ + + ================= ===== = + Parameter Vers. + ================= ===== = + ``size`` βœ”οΈ + ``genre`` βœ”οΈ + ``fromYear`` βœ”οΈ + ``toYear`` βœ”οΈ + ``musicFolderId`` βœ”οΈ + ================= ===== = + +.. _getSongsByGenre: + +``getSongsByGenre`` + βœ”οΈ 1.9.0 + + ================= ====== = + Parameter Vers. + ================= ====== = + ``genre`` 1.9.0 βœ”οΈ + ``count`` 1.9.0 βœ”οΈ + ``offset`` 1.9.0 βœ”οΈ + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + +.. _getNowPlaying: + +``getNowPlaying`` + βœ”οΈ + + No parameter + +.. _getStarred: + +``getStarred`` + βœ”οΈ + + ================= ====== = + Parameter Vers. + ================= ====== = + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + +.. _getStarred2: + +``getStarred2`` + βœ”οΈ + + ================= ====== = + Parameter Vers. + ================= ====== = + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + +Searching +^^^^^^^^^ + +.. _search-: + +``search`` + βœ”οΈ + + ============= ===== = + Parameter Vers. + ============= ===== = + ``artist`` βœ”οΈ + ``album`` βœ”οΈ + ``title`` βœ”οΈ + ``any`` βœ”οΈ + ``count`` βœ”οΈ + ``offset`` βœ”οΈ + ``newerThan`` βœ”οΈ + ============= ===== = + +.. _search2: + +``search2`` + βœ”οΈ + + ================= ====== = + Parameter Vers. + ================= ====== = + ``query`` βœ”οΈ + ``artistCount`` βœ”οΈ + ``artistOffset`` βœ”οΈ + ``albumCount`` βœ”οΈ + ``albumOffset`` βœ”οΈ + ``songCount`` βœ”οΈ + ``songOffset`` βœ”οΈ + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + +.. _search3: + +``search3`` + βœ”οΈ + + ================= ====== = + Parameter Vers. + ================= ====== = + ``query`` βœ”οΈ + ``artistCount`` βœ”οΈ + ``artistOffset`` βœ”οΈ + ``albumCount`` βœ”οΈ + ``albumOffset`` βœ”οΈ + ``songCount`` βœ”οΈ + ``songOffset`` βœ”οΈ + ``musicFolderId`` 1.12.0 πŸ“… + ================= ====== = + +Playlists +^^^^^^^^^ + +.. _getPlaylists: + +``getPlaylists`` + βœ”οΈ + + ============ ===== = + Parameter Vers. + ============ ===== = + ``username`` βœ”οΈ + ============ ===== = + +.. _getPlaylist: + +``getPlaylist`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _createPlaylist: + +``createPlaylist`` + βœ”οΈ + + ============== ===== = + Parameter Vers. + ============== ===== = + ``playlistId`` βœ”οΈ + ``name`` βœ”οΈ + ``songId`` βœ”οΈ + ============== ===== = + +.. _updatePlaylist: + +``updatePlaylist`` + βœ”οΈ + + ===================== ===== = + Parameter Vers. + ===================== ===== = + ``playlistId`` βœ”οΈ + ``name`` βœ”οΈ + ``comment`` βœ”οΈ + ``public`` 1.9.0 βœ”οΈ + ``songIdToAdd`` βœ”οΈ + ``songIndexToRemove`` βœ”οΈ + ===================== ===== = + +.. _deletePlaylist: + +``deletePlaylist`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +Media retrieval +^^^^^^^^^^^^^^^ + +.. _stream: + +``stream`` + βœ”οΈ + + ========================= ====== = + Parameter Vers. + ========================= ====== = + ``id`` βœ”οΈ + ``maxBitRate`` βœ”οΈ + ``format`` βœ”οΈ + ``timeOffset`` ❌ + ``size`` ❌ + ``estimateContentLength`` βœ”οΈ + ``converted`` 1.15.0 πŸ”΄ + ========================= ====== = + +.. _download: + +``download`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ========= ===== = + +.. _hls: + +``hls`` + πŸ”΄ 1.9.0 + + ============== ====== = + Parameter Vers. + ============== ====== = + ``id`` 1.9.0 πŸ”΄ + ``bitRate`` 1.9.0 πŸ”΄ + ``audioTrack`` 1.15.0 πŸ”΄ + ============== ====== = + +.. _getCaptions: + +``getCaptions`` + πŸ”΄ 1.15.0 + + ========== ====== = + Parameter Vers. + ========== ====== = + ``id`` 1.15.0 πŸ”΄ + ``format`` 1.15.0 πŸ”΄ + ========== ====== = + +.. _getCoverArt: + +``getCoverArt`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` βœ”οΈ + ``size`` βœ”οΈ + ========= ===== = + +.. _getLyrics: + +``getLyrics`` + βœ”οΈ + + ========== ===== = + Parameter Vers. + ========== ===== = + ``artist`` βœ”οΈ + ``title`` βœ”οΈ + ========== ===== = + +.. _getAvatar: + +``getAvatar`` + ❌ + + ============ ===== = + Parameter Vers. + ============ ===== = + ``username`` ❌ + ============ ===== = + +Media annotation +^^^^^^^^^^^^^^^^ + +.. _star: + +``star`` + βœ”οΈ + + ============ ===== = + Parameter Vers. + ============ ===== = + ``id`` βœ”οΈ + ``albumId`` βœ”οΈ + ``artistId`` βœ”οΈ + ============ ===== = + +.. _unstar: + +``unstar`` + βœ”οΈ + + ============ ===== = + Parameter Vers. + ============ ===== = + ``id`` βœ”οΈ + ``albumId`` βœ”οΈ + ``artistId`` βœ”οΈ + ============ ===== = + +.. _setRating: + +``setRating`` + βœ”οΈ + + ========== ===== = + Parameter Vers. + ========== ===== = + ``id`` βœ”οΈ + ``rating`` βœ”οΈ + ========== ===== = + +.. _scrobble: + +``scrobble`` + βœ”οΈ + + ============== ===== = + Parameter Vers. + ============== ===== = + ``id`` βœ”οΈ + ``time`` 1.9.0 βœ”οΈ + ``submission`` βœ”οΈ + ============== ===== = + +Sharing +^^^^^^^ + +.. _getShares: + +``getShares`` + ❌ + + No parameter + +.. _createShare: + +``createShare`` + ❌ + + =============== ===== = + Parameter Vers. + =============== ===== = + ``id`` ❌ + ``description`` ❌ + ``expires`` ❌ + =============== ===== = + +.. _updateShare: + +``updateShare`` + ❌ + + =============== ===== = + Parameter Vers. + =============== ===== = + ``id`` ❌ + ``description`` ❌ + ``expires`` ❌ + =============== ===== = + +.. _deleteShare: + +``deleteShare`` + ❌ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` ❌ + ========= ===== = + +Podcast +^^^^^^^ + +.. _getPodcasts: + +``getPodcasts`` + ❔ + + =================== ===== = + Parameter Vers. + =================== ===== = + ``includeEpisodes`` 1.9.0 ❔ + ``id`` 1.9.0 ❔ + =================== ===== = + +.. _getNewestPodcasts: + +``getNewestPodcasts`` + ❔ 1.14.0 + + ========= ====== = + Parameter Vers. + ========= ====== = + ``count`` 1.14.0 ❔ + ========= ====== = + +.. _refreshPodcasts: + +``refreshPodcasts`` + ❔ 1.9.0 + + No parameter + +.. _createPodcastChannel: + +``createPodcastChannel`` + ❔ 1.9.0 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``url`` 1.9.0 ❔ + ========= ===== = + +.. _deletePodcastChannel: + +``deletePodcastChannel`` + ❔ 1.9.0 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` 1.9.0 ❔ + ========= ===== = + +.. _deletePodcastEpisode: + +``deletePodcastEpisode`` + ❔ 1.9.0 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` 1.9.0 ❔ + ========= ===== = + +.. _downloadPodcastEpisode: + +``downloadPodcastEpisode`` + ❔ 1.9.0 + + ========= ===== = + Parameter Vers. + ========= ===== = + ``id`` 1.9.0 ❔ + ========= ===== = + +Jukebox +^^^^^^^ + +.. _jukeboxControl: + +``jukeboxControl`` + βœ”οΈ + + ========== ===== = + Parameter Vers. + ========== ===== = + ``action`` βœ”οΈ + ``index`` βœ”οΈ + ``offset`` βœ”οΈ + ``id`` βœ”οΈ + ``gain`` ❌ + ========== ===== = + +Internet radio +^^^^^^^^^^^^^^ + +.. _getInternetRadioStations: + +``getInternetRadioStations`` + ❔ 1.9.0 + + No parameter + +.. _createInternetRadioStation: + +``createInternetRadioStation`` + ❔ 1.16.0 + + =============== ====== = + Parameter Vers. + =============== ====== = + ``streamUrl`` 1.16.0 ❔ + ``name`` 1.16.0 ❔ + ``homepageUrl`` 1.16.0 ❔ + =============== ====== = + +.. _updateInternetRadioStation: + +``updateInternetRadioStation`` + ❔ 1.16.0 + + =============== ====== = + Parameter Vers. + =============== ====== = + ``id`` 1.16.0 ❔ + ``streamUrl`` 1.16.0 ❔ + ``name`` 1.16.0 ❔ + ``homepageUrl`` 1.16.0 ❔ + =============== ====== = + +.. _deleteInternetRadioStation: + +``deleteInternetRadioStation`` + ❔ 1.16.0 + + =============== ====== = + Parameter Vers. + =============== ====== = + ``id`` 1.16.0 ❔ + =============== ====== = + +Chat +^^^^ + +.. _getChatMessages: + +``getChatMessages`` + βœ”οΈ + + ========= ===== = + Parameter Vers. + ========= ===== = + ``since`` βœ”οΈ + ========= ===== = + +.. _addChatMessage: + +``addChatMessage`` + βœ”οΈ + + =========== ===== = + Parameter Vers. + =========== ===== = + ``message`` βœ”οΈ + =========== ===== = + +User management +^^^^^^^^^^^^^^^ + +.. _getUser: + +``getUser`` + βœ”οΈ + + ============ ===== = + Parameter Vers. + ============ ===== = + ``username`` βœ”οΈ + ============ ===== = + +.. _getUsers: + +``getUsers`` + βœ”οΈ 1.9.0 + + No parameter + +.. _createUser: + +``createUser`` + βœ”οΈ + + ======================= ====== = + Parameter Vers. + ======================= ====== = + ``username`` βœ”οΈ + ``password`` βœ”οΈ + ``email`` βœ”οΈ + ``ldapAuthenticated`` + ``adminRole`` βœ”οΈ + ``settingsRole`` + ``streamRole`` + ``jukeboxRole`` βœ”οΈ + ``downloadRole`` + ``uploadRole`` + ``playlistRole`` + ``coverArtRole`` + ``commentRole`` + ``podcastRole`` + ``shareRole`` + ``videoConversionRole`` 1.14.0 + ``musicFolderId`` 1.12.0 πŸ“… + ======================= ====== = + +.. _updateUser: + +``updateUser`` + βœ”οΈ 1.10.2 + + ======================= ====== = + Parameter Vers. + ======================= ====== = + ``username`` 1.10.2 βœ”οΈ + ``password`` 1.10.2 βœ”οΈ + ``email`` 1.10.2 βœ”οΈ + ``ldapAuthenticated`` 1.10.2 + ``adminRole`` 1.10.2 βœ”οΈ + ``settingsRole`` 1.10.2 + ``streamRole`` 1.10.2 + ``jukeboxRole`` 1.10.2 βœ”οΈ + ``downloadRole`` 1.10.2 + ``uploadRole`` 1.10.2 + ``coverArtRole`` 1.10.2 + ``commentRole`` 1.10.2 + ``podcastRole`` 1.10.2 + ``shareRole`` 1.10.2 + ``videoConversionRole`` 1.14.0 + ``musicFolderId`` 1.12.0 πŸ“… + ``maxBitRate`` 1.13.0 πŸ“… + ======================= ====== = + +.. _deleteUser: + +``deleteUser`` + βœ”οΈ + + ============ ===== = + Parameter Vers. + ============ ===== = + ``username`` βœ”οΈ + ============ ===== = + +.. _changePassword: + +``changePassword`` + βœ”οΈ + + ============ ===== = + Parameter Vers. + ============ ===== = + ``username`` βœ”οΈ + ``password`` βœ”οΈ + ============ ===== = + +Bookmarks +^^^^^^^^^ + +.. _getBookmarks: + +``getBookmarks`` + ❔ 1.9.0 + + No parameter + +.. _createBookmark: + +``createBookmark`` + ❔ 1.9.0 + + ============ ===== = + Parameter Vers. + ============ ===== = + ``id`` 1.9.0 ❔ + ``position`` 1.9.0 ❔ + ``comment`` 1.9.0 ❔ + ============ ===== = + +.. _deleteBookmark: + +``deleteBookmark`` + ❔ 1.9.0 + + =============== ===== = + Parameter Vers. + =============== ===== = + ``id`` 1.9.0 ❔ + =============== ===== = + +.. _getPlayQueue: + +``getPlayQueue`` + ❔ 1.12.0 + + No parameter + +.. _savePlayQueue: + +``savePlayQueue`` + ❔ 1.12.0 + + ============ ====== = + Parameter Vers. + ============ ====== = + ``id`` 1.12.0 ❔ + ``current`` 1.12.0 ❔ + ``position`` 1.12.0 ❔ + ============ ====== = + +Library scanning +^^^^^^^^^^^^^^^^ + +.. _getScanStatus: + +``getScanStatus`` + βœ”οΈ 1.15.0 + + No parameter + +.. _startScan: + +``startScan`` + βœ”οΈ 1.15.0 + + No parameter + +Changes by version +------------------ + +Version 1.9.0 +^^^^^^^^^^^^^ + +Added methods: + +* :ref:`getGenres ` +* :ref:`getSongsByGenre ` +* :ref:`hls ` +* :ref:`refreshPodcasts ` +* :ref:`createPodcastChannel ` +* :ref:`deletePodcastChannel ` +* :ref:`deletePodcastEpisode ` +* :ref:`downloadPodcastEpisode ` +* :ref:`getInternetRadioStations ` +* :ref:`getUsers ` +* :ref:`getBookmarks ` +* :ref:`createBookmark ` +* :ref:`deleteBookmark ` + +Added method parameters: + +* :ref:`updatePlaylist ` + + * ``public`` + +* :ref:`scrobble ` + + * ``time`` + +* :ref:`getPodcasts ` + + * ``includeEpisodes`` + * ``id`` + +Version 1.10.1 +^^^^^^^^^^^^^^ + +Added method parameters: + +* :ref:`getAlbumList ` + + * ``fromYear`` + * ``toYear`` + * ``genre`` + +* :ref:`getAlbumList2 ` + + * ``fromYear`` + * ``toYear`` + * ``genre`` + +Version 1.10.2 +^^^^^^^^^^^^^^ + +Added methods: + +* :ref:`updateUser ` + +Version 1.11.0 +^^^^^^^^^^^^^^ + +Added methods: + +* :ref:`getArtistInfo ` +* :ref:`getArtistInfo2 ` +* :ref:`getSimilarSongs ` +* :ref:`getSimilarSongs2 ` + +Version 1.12.0 +^^^^^^^^^^^^^^ + +Added methods: + +* :ref:`getPlayQueue ` +* :ref:`savePlayQueue ` + +Added method parameters: + +* :ref:`getAlbumList ` + + * ``musicFolderId`` + +* :ref:`getAlbumList2 ` + + * ``musicFolderId`` + +* :ref:`getSongsByGenre ` + + * ``musicFolderId`` + +* :ref:`getStarred ` + + * ``musicFolderId`` + +* :ref:`getStarred2 ` + + * ``musicFolderId`` + +* :ref:`search2 ` + + * ``musicFolderId`` + +* :ref:`search3 ` + + * ``musicFolderId`` + +* :ref:`createUser ` + + * ``musicFolderId`` + +* :ref:`updateUser ` + + * ``musicFolderId`` + +Version 1.13.0 +^^^^^^^^^^^^^^ + +Added global parameters: + +* ``t`` +* ``s`` + +Added methods: + +* :ref:`getTopSongs ` + +Added method parameters: + +* :ref:`updateUser ` + + * ``maxBitRate`` + +Version 1.14.0 +^^^^^^^^^^^^^^ + +Added methods: + +* :ref:`getAlbumInfo ` +* :ref:`getAlbumInfo2 ` +* :ref:`getNewestPodcasts ` + +Added method parameters: + +* :ref:`getArtists ` + + * ``musicFolderId`` + +* :ref:`createUser ` + + * ``videoConversionRole`` + +* :ref:`updateUser ` + + * ``videoConversionRole`` + +Version 1.15.0 +^^^^^^^^^^^^^^ + +Added error code ``41`` + +Added methods: + +* :ref:`getVideoInfo ` +* :ref:`getCaptions ` +* :ref:`getScanStatus ` +* :ref:`startScan ` + +Added method parameters: + +* :ref:`stream ` + + * ``converted`` + +* :ref:`hls ` + + * ``audioTrack`` + +Version 1.16.0 +^^^^^^^^^^^^^^ + +Added methods: + +* :ref:`createInternetRadioStation ` +* :ref:`updateInternetRadioStation ` +* :ref:`deleteInternetRadioStation ` From c8db5b81ab26a9896ebb8fbeb3974efabe38ed72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Sat, 2 Jan 2021 17:24:30 +0100 Subject: [PATCH 05/14] Simplify API cross references --- docs/api.rst | 264 +++++++++++++++++++++++++-------------------------- 1 file changed, 132 insertions(+), 132 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index d3612a2..73b075b 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -28,86 +28,86 @@ or with version 1.8.0. All methods / pseudo-TOC ^^^^^^^^^^^^^^^^^^^^^^^^ -============================================================== ====== = -Method Vers. -============================================================== ====== = -:ref:`ping ` βœ”οΈ -:ref:`getLicense ` βœ”οΈ -:ref:`getMusicFolders ` βœ”οΈ -:ref:`getIndexes ` βœ”οΈ -:ref:`getMusicDirectory ` βœ”οΈ -:ref:`getGenres ` 1.9.0 βœ”οΈ -:ref:`getArtists ` βœ”οΈ -:ref:`getArtist ` βœ”οΈ -:ref:`getAlbum ` βœ”οΈ -:ref:`getSong ` βœ”οΈ -:ref:`getVideos ` ❌ -:ref:`getVideoInfo ` 1.15.0 πŸ”΄ -:ref:`getArtistInfo ` 1.11.0 πŸ“… -:ref:`getArtistInfo2 ` 1.11.0 πŸ“… -:ref:`getAlbumInfo ` 1.14.0 πŸ“… -:ref:`getAlbumInfo2 ` 1.14.0 πŸ“… -:ref:`getSimilarSongs ` 1.11.0 ❔ -:ref:`getSimilarSongs2 ` 1.11.0 ❔ -:ref:`getTopSongs ` 1.13.0 ❔ -:ref:`getAlbumList ` βœ”οΈ -:ref:`getAlbumList2 ` βœ”οΈ -:ref:`getRandomSongs ` βœ”οΈ -:ref:`getSongsByGenre ` 1.9.0 βœ”οΈ -:ref:`getNowPlaying ` βœ”οΈ -:ref:`getStarred ` βœ”οΈ -:ref:`getStarred2 ` βœ”οΈ -:ref:`search ` βœ”οΈ -:ref:`search2 ` βœ”οΈ -:ref:`search3 ` βœ”οΈ -:ref:`getPlaylists ` βœ”οΈ -:ref:`getPlaylist ` βœ”οΈ -:ref:`createPlaylist ` βœ”οΈ -:ref:`updatePlaylist ` βœ”οΈ -:ref:`deletePlaylist ` βœ”οΈ -:ref:`stream ` βœ”οΈ -:ref:`download ` βœ”οΈ -:ref:`hls ` 1.9.0 πŸ”΄ -:ref:`getCaptions ` 1.15.0 πŸ”΄ -:ref:`getCoverArt ` βœ”οΈ -:ref:`getLyrics ` βœ”οΈ -:ref:`getAvatar ` ❌ -:ref:`star ` βœ”οΈ -:ref:`unstar ` βœ”οΈ -:ref:`setRating ` βœ”οΈ -:ref:`scrobble ` βœ”οΈ -:ref:`getShares ` ❌ -:ref:`createShare ` ❌ -:ref:`updateShare ` ❌ -:ref:`deleteShare ` ❌ -:ref:`getPodcasts ` ❔ -:ref:`getNewestPodcasts ` 1.14.0 ❔ -:ref:`refreshPodcasts ` 1.9.0 ❔ -:ref:`createPodcastChannel ` 1.9.0 ❔ -:ref:`deletePodcastChannel ` 1.9.0 ❔ -:ref:`deletePodcastEpisode ` 1.9.0 ❔ -:ref:`downloadPodcastEpisode ` 1.9.0 ❔ -:ref:`jukeboxControl ` βœ”οΈ -:ref:`getInternetRadioStations ` 1.9.0 βœ”οΈ -:ref:`createInternetRadioStation ` 1.16.0 βœ”οΈ -:ref:`updateInternetRadioStation ` 1.16.0 βœ”οΈ -:ref:`deleteInternetRadioStation ` 1.16.0 βœ”οΈ -:ref:`getChatMessages ` βœ”οΈ -:ref:`addChatMessage ` βœ”οΈ -:ref:`getUser ` βœ”οΈ -:ref:`getUsers ` 1.9.0 βœ”οΈ -:ref:`createUser ` βœ”οΈ -:ref:`updateUser ` 1.10.2 βœ”οΈ -:ref:`deleteUser ` βœ”οΈ -:ref:`changePassword ` βœ”οΈ -:ref:`getBookmarks ` 1.9.0 ❔ -:ref:`createBookmark ` 1.9.0 ❔ -:ref:`deleteBookmark ` 1.9.0 ❔ -:ref:`getPlayQueue ` 1.12.0 ❔ -:ref:`savePlayQueue ` 1.12.0 ❔ -:ref:`getScanStatus ` 1.15.0 βœ”οΈ -:ref:`startScan ` 1.15.0 βœ”οΈ -============================================================== ====== = +=========================== ====== = +Method Vers. +=========================== ====== = +ping_ βœ”οΈ +getLicense_ βœ”οΈ +getMusicFolders_ βœ”οΈ +getIndexes_ βœ”οΈ +getMusicDirectory_ βœ”οΈ +getGenres_ 1.9.0 βœ”οΈ +getArtists_ βœ”οΈ +getArtist_ βœ”οΈ +getAlbum_ βœ”οΈ +getSong_ βœ”οΈ +getVideos_ ❌ +getVideoInfo_ 1.15.0 πŸ”΄ +getArtistInfo_ 1.11.0 πŸ“… +getArtistInfo2_ 1.11.0 πŸ“… +getAlbumInfo_ 1.14.0 πŸ“… +getAlbumInfo2_ 1.14.0 πŸ“… +getSimilarSongs_ 1.11.0 ❔ +getSimilarSongs2_ 1.11.0 ❔ +getTopSongs_ 1.13.0 ❔ +getAlbumList_ βœ”οΈ +getAlbumList2_ βœ”οΈ +getRandomSongs_ βœ”οΈ +getSongsByGenre_ 1.9.0 βœ”οΈ +getNowPlaying_ βœ”οΈ +getStarred_ βœ”οΈ +getStarred2_ βœ”οΈ +search_ βœ”οΈ +search2_ βœ”οΈ +search3_ βœ”οΈ +getPlaylists_ βœ”οΈ +getPlaylist_ βœ”οΈ +createPlaylist_ βœ”οΈ +updatePlaylist_ βœ”οΈ +deletePlaylist_ βœ”οΈ +stream_ βœ”οΈ +download_ βœ”οΈ +hls_ 1.9.0 πŸ”΄ +getCaptions_ 1.15.0 πŸ”΄ +getCoverArt_ βœ”οΈ +getLyrics_ βœ”οΈ +getAvatar_ ❌ +star_ βœ”οΈ +unstar_ βœ”οΈ +setRating_ βœ”οΈ +scrobble_ βœ”οΈ +getShares_ ❌ +createShare_ ❌ +updateShare_ ❌ +deleteShare_ ❌ +getPodcasts_ ❔ +getNewestPodcasts_ 1.14.0 ❔ +refreshPodcasts_ 1.9.0 ❔ +createPodcastChannel_ 1.9.0 ❔ +deletePodcastChannel_ 1.9.0 ❔ +deletePodcastEpisode_ 1.9.0 ❔ +downloadPodcastEpisode_ 1.9.0 ❔ +jukeboxControl_ βœ”οΈ +getInternetRadioStations_ 1.9.0 βœ”οΈ +createInternetRadioStation_ 1.16.0 βœ”οΈ +updateInternetRadioStation_ 1.16.0 βœ”οΈ +deleteInternetRadioStation_ 1.16.0 βœ”οΈ +getChatMessages_ βœ”οΈ +addChatMessage_ βœ”οΈ +getUser_ βœ”οΈ +getUsers_ 1.9.0 βœ”οΈ +createUser_ βœ”οΈ +updateUser_ 1.10.2 βœ”οΈ +deleteUser_ βœ”οΈ +changePassword_ βœ”οΈ +getBookmarks_ 1.9.0 ❔ +createBookmark_ 1.9.0 ❔ +deleteBookmark_ 1.9.0 ❔ +getPlayQueue_ 1.12.0 ❔ +savePlayQueue_ 1.12.0 ❔ +getScanStatus_ 1.15.0 βœ”οΈ +startScan_ 1.15.0 βœ”οΈ +=========================== ====== = Global ^^^^^^ @@ -449,7 +449,7 @@ Album/song lists Searching ^^^^^^^^^ -.. _search-: +.. _search: ``search`` βœ”οΈ @@ -1104,31 +1104,31 @@ Version 1.9.0 Added methods: -* :ref:`getGenres ` -* :ref:`getSongsByGenre ` -* :ref:`hls ` -* :ref:`refreshPodcasts ` -* :ref:`createPodcastChannel ` -* :ref:`deletePodcastChannel ` -* :ref:`deletePodcastEpisode ` -* :ref:`downloadPodcastEpisode ` -* :ref:`getInternetRadioStations ` -* :ref:`getUsers ` -* :ref:`getBookmarks ` -* :ref:`createBookmark ` -* :ref:`deleteBookmark ` +* getGenres_ +* getSongsByGenre_ +* hls_ +* refreshPodcasts_ +* createPodcastChannel_ +* deletePodcastChannel_ +* deletePodcastEpisode_ +* downloadPodcastEpisode_ +* getInternetRadioStations_ +* getUsers_ +* getBookmarks_ +* createBookmark_ +* deleteBookmark_ Added method parameters: -* :ref:`updatePlaylist ` +* updatePlaylist_ * ``public`` -* :ref:`scrobble ` +* scrobble_ * ``time`` -* :ref:`getPodcasts ` +* getPodcasts_ * ``includeEpisodes`` * ``id`` @@ -1138,13 +1138,13 @@ Version 1.10.1 Added method parameters: -* :ref:`getAlbumList ` +* getAlbumList_ * ``fromYear`` * ``toYear`` * ``genre`` -* :ref:`getAlbumList2 ` +* getAlbumList2_ * ``fromYear`` * ``toYear`` @@ -1155,61 +1155,61 @@ Version 1.10.2 Added methods: -* :ref:`updateUser ` +* updateUser_ Version 1.11.0 ^^^^^^^^^^^^^^ Added methods: -* :ref:`getArtistInfo ` -* :ref:`getArtistInfo2 ` -* :ref:`getSimilarSongs ` -* :ref:`getSimilarSongs2 ` +* getArtistInfo_ +* getArtistInfo2_ +* getSimilarSongs_ +* getSimilarSongs2_ Version 1.12.0 ^^^^^^^^^^^^^^ Added methods: -* :ref:`getPlayQueue ` -* :ref:`savePlayQueue ` +* getPlayQueue_ +* savePlayQueue_ Added method parameters: -* :ref:`getAlbumList ` +* getAlbumList_ * ``musicFolderId`` -* :ref:`getAlbumList2 ` +* getAlbumList2_ * ``musicFolderId`` -* :ref:`getSongsByGenre ` +* getSongsByGenre_ * ``musicFolderId`` -* :ref:`getStarred ` +* getStarred_ * ``musicFolderId`` -* :ref:`getStarred2 ` +* getStarred2_ * ``musicFolderId`` -* :ref:`search2 ` +* search2_ * ``musicFolderId`` -* :ref:`search3 ` +* search3_ * ``musicFolderId`` -* :ref:`createUser ` +* createUser_ * ``musicFolderId`` -* :ref:`updateUser ` +* updateUser_ * ``musicFolderId`` @@ -1223,11 +1223,11 @@ Added global parameters: Added methods: -* :ref:`getTopSongs ` +* getTopSongs_ Added method parameters: -* :ref:`updateUser ` +* updateUser_ * ``maxBitRate`` @@ -1236,21 +1236,21 @@ Version 1.14.0 Added methods: -* :ref:`getAlbumInfo ` -* :ref:`getAlbumInfo2 ` -* :ref:`getNewestPodcasts ` +* getAlbumInfo_ +* getAlbumInfo2_ +* getNewestPodcasts_ Added method parameters: -* :ref:`getArtists ` +* getArtists_ * ``musicFolderId`` -* :ref:`createUser ` +* createUser_ * ``videoConversionRole`` -* :ref:`updateUser ` +* updateUser_ * ``videoConversionRole`` @@ -1261,18 +1261,18 @@ Added error code ``41`` Added methods: -* :ref:`getVideoInfo ` -* :ref:`getCaptions ` -* :ref:`getScanStatus ` -* :ref:`startScan ` +* getVideoInfo_ +* getCaptions_ +* getScanStatus_ +* startScan_ Added method parameters: -* :ref:`stream ` +* stream_ * ``converted`` -* :ref:`hls ` +* hls_ * ``audioTrack`` @@ -1281,6 +1281,6 @@ Version 1.16.0 Added methods: -* :ref:`createInternetRadioStation ` -* :ref:`updateInternetRadioStation ` -* :ref:`deleteInternetRadioStation ` +* createInternetRadioStation_ +* updateInternetRadioStation_ +* deleteInternetRadioStation_ From fb41bf28148e29d1f2366b04ce8780c870a4dc9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Sun, 3 Jan 2021 16:34:29 +0100 Subject: [PATCH 06/14] Improve manpages --- docs/cli.md | 74 ---------------------------- docs/jukebox.rst | 3 +- docs/man/supysonic-cli-folder.rst | 64 +++++++++++++++++-------- docs/man/supysonic-cli-user.rst | 80 ++++++++++++++++++++----------- docs/man/supysonic-cli.rst | 51 ++++++++++---------- docs/man/supysonic-daemon.rst | 34 +++++++------ 6 files changed, 142 insertions(+), 164 deletions(-) delete mode 100644 docs/cli.md diff --git a/docs/cli.md b/docs/cli.md deleted file mode 100644 index 7e5ee36..0000000 --- a/docs/cli.md +++ /dev/null @@ -1,74 +0,0 @@ -# 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 [-p ] [-e ] - supysonic-cli user delete - supysonic-cli user changepass - supysonic-cli user list - supysonic-cli user setroles [-a|-A] [-j|-J] - -Arguments: - add Add a new user - delete Delete the user - changepass Change the user's password - list List all the users - setroles Give or remove rights to the user - -Options: - -p --password Specify the user's password - -e --email Specify the user's email - -a --noadmin Revoke admin rights - -A --admin Grant admin rights - -j --nojukebox Revoke jukebox rights - -J --jukebox Grant jukebox rights -``` - -## Folder management commands - -``` -Usage: - supysonic-cli folder add - supysonic-cli folder delete - supysonic-cli folder list - supysonic-cli folder scan [-f] [--background | --foreground] [...] - -Arguments: - add Add a new folder - delete Delete a folder - list List all the folders - scan Scan all or specified folders - -Options: - -f --force Force scan of already known files even if they - haven't changed - --background Scan in the background. Requires the daemon to - be running. - --foreground Scan in the foreground, blocking the process - while the scan is running -``` diff --git a/docs/jukebox.rst b/docs/jukebox.rst index 80dda29..3066b4b 100644 --- a/docs/jukebox.rst +++ b/docs/jukebox.rst @@ -39,6 +39,7 @@ Allowing users to act on the jukebox ------------------------------------ The jukebox mode is only accessible to chosen users. Granting (or revoking) -jukebox usage rights to a specific user is done with the :doc:`cli`:: +jukebox usage rights to a specific user is done with the +:doc:`command line interface `:: $ supysonic-cli user setroles --jukebox diff --git a/docs/man/supysonic-cli-folder.rst b/docs/man/supysonic-cli-folder.rst index 9d0dee5..869fbd5 100644 --- a/docs/man/supysonic-cli-folder.rst +++ b/docs/man/supysonic-cli-folder.rst @@ -6,50 +6,72 @@ supysonic-cli-folder Supysonic folder management commands ------------------------------------ -:Author: Louis-Philippe VΓ©ronneau -:Date: 2019 +:Author: Louis-Philippe VΓ©ronneau, Alban FΓ©ron +:Date: 2019, 2021 :Manual section: 1 Synopsis ======== -| supysonic-cli folder **add** -| supysonic-cli folder **delete** -| supysonic-cli folder **list** -| supysonic-cli folder **scan** [-f] [--background | --foreground] [...] +| ``supysonic-cli folder list`` +| ``supysonic-cli folder add`` `name` `path` +| ``supysonic-cli folder delete`` `name` +| ``supysonic-cli folder scan`` [``--force``] [``--background``\|\ ``--foreground``] [`name`]... -Arguments -========= +Description +=========== -| **add** Add a new folder -| **delete** Delete a folder -| **list** List all the folders -| **scan** Scan all or specified folders +The ``supysonic-cli folder`` subcommand manages your library folders, where the +audio files are located. This allows to list, add, delete and scan the folders. + +``supysonic-cli folder list`` + List all the folders. + +``supysonic-cli folder add`` `name` `path` + Add a new library folder called `name` and located at `path`. `name` must be + unique and `path` pointing to an existing directory. If ``supysonic-daemon`` + is running it will start to listen for changes in this folder but will not + scan files already present in the folder. + +``supysonic-cli folder delete`` `name` + Delete the folder called `name`. + +``supysonic-cli folder scan`` [``--force``] [``--background``\|\ ``--foreground``] [`name`]... + Scan the specified folders. If none is given, all the registered folders are + scanned. Options ======= -| **-f** | **--force** -|     Force scan of already known files even if they haven't changed +-f, --force + Force scan of already known files even if they haven't changed. Might be + useful if an update to *Supysonic* adds new metadata to audio files. -| **--background** -|     Scan in the background. Requires the daemon to be running +--background + Scan in the background. Requires the ``supysonic-daemon`` to be running -| **--foreground** -|     Scan in the foreground, blocking the process while the scan is running +--foreground + Scan in the foreground, blocking the process while the scan is running + +If neither ``--background`` nor ``--foreground`` is provided, ``supysonic-cli`` +will try to connect to the daemon to initiate a background scan, falling back to +a foreground scan if it isn't available. Examples ======== To add a new folder to your music library, you can do something like this:: - $ supysonic-cli folder add MyLibrary /home/username/Music + $ supysonic-cli folder add MyLibrary /home/username/Music Once you've added a folder, you will need to scan it:: - $ supysonic-cli folder scan MyLibrary + $ supysonic-cli folder scan MyLibrary + +The audio files residing in `/home/username/Music` will now appear under the +`MyLibrary` folder on the clients. See Also ======== -supysonic-cli(1), supysonic-cli-user(1) +``supysonic-cli``\ (1), ``supysonic-cli-user``\ (1) diff --git a/docs/man/supysonic-cli-user.rst b/docs/man/supysonic-cli-user.rst index 33096cc..c25df9e 100644 --- a/docs/man/supysonic-cli-user.rst +++ b/docs/man/supysonic-cli-user.rst @@ -6,56 +6,78 @@ supysonic-cli-user Supysonic user management commands ---------------------------------- -:Author: Louis-Philippe VΓ©ronneau -:Date: 2019 +:Author: Louis-Philippe VΓ©ronneau, Alban FΓ©ron +:Date: 2019, 2021 :Manual section: 1 Synopsis ======== -| supysonic-cli user **add** [-p ] [-e ] -| supysonic-cli user **delete** -| supysonic-cli user **changepass** -| supysonic-cli user **list** -| supysonic-cli user **setroles** [-a|-A] [-j|-J] +| ``supysonic-cli user list`` +| ``supysonic-cli user add`` `user` [``--password`` `password`] [``--email`` `email`] +| ``supysonic-cli user delete`` `user` +| ``supysonic-cli user changepass`` `user` `password` +| ``supysonic-cli user setroles`` [``--admin``\|\ ``--noadmin``] [``--jukebox``\|\ ``--nojukebox``] `user` -Arguments -========= +Description +=========== -| **add** Add a new user -| **delete** Delete the user -| **changepass** Change the user's password -| **list** List all the users -| **setroles** Give or remove rights to the user +The ``supysonic-cli user`` subcommand manages users, allowing to list them, add +a new user, delete an existing user, and change their password or roles. + +``supysonic-cli user list`` + List all the users. + +``supysonic-cli user add`` `user` [``--password`` `password`] [``--email`` `email`] + Add a new user named `user`. Will prompt for a password if it isn't given + with the ``--password`` option. + +``supysonic-cli user delete`` `user` + Delete the user `user`. + +``supysonic-cli user changepass`` `user` [`password`] + Change the password of user `user`. Will prompt for the new password if not + provided. + +``supysonic-cli user setroles`` [``--admin``\|\ ``--noadmin``] [``--jukebox``\|\ ``--nojukebox``] `user` + Give or remove rights to user `user`. Options ======= -| **-p** | **--password** ** -|     Specify the user's password +-p password, --password password + Specify the user's password upon creation. -| **-e** | **--email** ** -|     Specify the user's email +-e email, --email email + Specify the user's email. -| **-a** | **--noadmin** -|     Revoke admin rights +The next options relate to user roles. They work in pairs, one option granting +a right while the other revokes it; obviously options of the same pair are +mutually exclusive. The long options are named with the matching right, prefix +it with a ``no`` to revoke the right. For short options, the upper case letter +grants the right while the lower case letter revokes it. Short options might be +combined into a single one such as ``-aJ`` to both revoke the admin right and +grant the jukebox one. -| **-A** | **--admin** -|     Grant admin rights +-A, --admin + Grant admin rights. -| **-j** | **--nojukebox** -|     Revoke jukebox rights +-a, --noadmin + Revoke admin rights. -| **-J** | **--jukebox** -|     Grant jukebox rights +-J, --jukebox + Grant jukebox rights. + +-j, --nojukebox + Revoke jukebox rights. Examples ======== -To add a new admin user:: +To add a new admin user named `MyUserName` having password `MyAwesomePassword`:: - $ supysonic-cli user add MyUserName -p MyAwesomePassword - $ supysonic-cli user setroles -A MyUserName + $ supysonic-cli user add MyUserName -p MyAwesomePassword + $ supysonic-cli user setroles -A MyUserName See Also ======== diff --git a/docs/man/supysonic-cli.rst b/docs/man/supysonic-cli.rst index d9d71b3..a19de78 100644 --- a/docs/man/supysonic-cli.rst +++ b/docs/man/supysonic-cli.rst @@ -6,25 +6,21 @@ supysonic-cli Python implementation of the Subsonic server API ------------------------------------------------ -:Author: Louis-Philippe VΓ©ronneau -:Date: 2019 +:Author: Louis-Philippe VΓ©ronneau, Alban FΓ©ron +:Date: 2019, 2021 :Manual section: 1 Synopsis ======== -| supysonic-cli [**subcommand**] -| supysonic-cli **help** -| supysonic-cli **help** *user* -| supysonic-cli **help** *folder* +| ``supysonic-cli`` [`subcommand`] +| ``supysonic-cli help`` [`subcommand`] Description =========== -| supysonic is a Python implementation of the Subsonic server API. -| Current supported features are: - -| +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 @@ -33,34 +29,41 @@ Description | * cover arts (as image files in the same folder as music files) | * starred tracks/albums and ratings | * Last.FM scrobbling +| * Jukebox mode -| The "Subsonic API" is a set of adhoc standards to browse, stream or -| download a music collection over HTTP. +The "Subsonic API" is a set of adhoc standards to browse, stream or download a +music collection over HTTP. + +The command-line interface is an interface allowing administration operations +without the use of the web interface. If ran without arguments, +``supysonic-cli`` will open an interactive prompt, with arguments it will run +a single command and exit. Subcommands =========== -| If ran without arguments, **supysonic-cli** will open an interactive -| prompt. +``supysonic-cli`` has three different subcommands: -**supysonic-cli** has three different subcommands: +``help`` [`subcommand`] + When used without argument, displays the list of available subcommands. With + an argument, shows the help and arguments for the given subcommand. -| +``user`` `args` ... + User management commands -| * help -| * user -| * folder +``folder`` `args` ... + Folder managemnt commands -| For more details on the **user** and **folder** subcommands, see the -| subsonic-cli-user(1), subsonic-cli-folder(1) manual pages. +For more details on the ``user`` and ``folder`` subcommands, see the +``subsonic-cli-user``\ (1), ``subsonic-cli-folder``\ (1) manual pages. Bugs ==== -| Bugs can be reported to your distribution's bug tracker or upstream -| at https://github.com/spl0k/supysonic/issues. +Bugs can be reported to your distribution's bug tracker or upstream +at https://github.com/spl0k/supysonic/issues. See Also ======== -supysonic-cli-user(1), supysonic-cli-folder(1) +``supysonic-cli-user``\ (1), ``supysonic-cli-folder``\ (1) diff --git a/docs/man/supysonic-daemon.rst b/docs/man/supysonic-daemon.rst index d343e29..39acd79 100644 --- a/docs/man/supysonic-daemon.rst +++ b/docs/man/supysonic-daemon.rst @@ -2,37 +2,41 @@ supysonic-daemon ================ ------------------------- -Supysonic scanner daemon ------------------------- +--------------------------- +Supysonic background daemon +--------------------------- -:Author: Louis-Philippe VΓ©ronneau -:Date: 2019 +:Author: Louis-Philippe VΓ©ronneau, Alban FΓ©ron +:Date: 2019, 2021 :Manual section: 1 Synopsis ======== -| supysonic-daemon +``supysonic-daemon`` Description =========== -| **supysonic-daemon** is an optional non-exiting process made to be ran in the -| background to manage background scans and library changes detection. +``supysonic-daemon`` is an optional non-exiting process made to be ran in the +background to manage background scans, library changes detection and the jukebox +mode (audio played on the server hardware). -| If **supysonic-daemon** is running when you start a manual scan using -| **supysonic-cli(1)**, the scan will be run by the daemon process in the -| background instead of running in the foreground. This daemon also enables the -| web UI scan feature. +If ``supysonic-daemon`` is running when you start a manual scan using +``supysonic-cli``\ (1), the scan will be run by the daemon process in the +background instead of running in the foreground. This daemon also enables the +web UI scan feature. + +With proper configuration, ``supysonic-daemon`` also allows authorized users to +play audio on the machine's hardware, using their client as a remote control. Bugs ==== -| Bugs can be reported to your distribution's bug tracker or upstream -| at https://github.com/spl0k/supysonic/issues. +Bugs can be reported to your distribution's bug tracker or upstream +at https://github.com/spl0k/supysonic/issues. See Also ======== -supysonic-cli(1) +``supysonic-cli``\ (1) From f92c7110aeba4cc9cb8dd47c967bfe5603c3696e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Sat, 9 Jan 2021 16:05:49 +0100 Subject: [PATCH 07/14] Installation doc --- docs/setup/index.rst | 10 ++++ docs/setup/install.rst | 110 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 120 insertions(+) create mode 100644 docs/setup/index.rst create mode 100644 docs/setup/install.rst diff --git a/docs/setup/index.rst b/docs/setup/index.rst new file mode 100644 index 0000000..58231fc --- /dev/null +++ b/docs/setup/index.rst @@ -0,0 +1,10 @@ +Supysonic setup +=============== + +This guide details the required steps to get a *Supysonic* instance ready to +start serving your music. + +.. toctree:: + :maxdepth: 2 + + install diff --git a/docs/setup/install.rst b/docs/setup/install.rst new file mode 100644 index 0000000..58b2705 --- /dev/null +++ b/docs/setup/install.rst @@ -0,0 +1,110 @@ +Installing Supysonic +==================== + +Supysonic is written in Python and supports Python 3.5+. + +Linux +----- + +Currently, only Debian-based distributions might provide Supysonic in their +package repositories. Install the package ``supysonic`` using either +:command:`apt` or :command:`apt-get`:: + + $ apt-get install supysonic + +This will install Supysonic along with the minimal dependencies it needs to +run. + +.. note:: + + As of January 2021, Supysonic only reached Debian's *testing* release. If + you're using the *stable* release it might not be available in the packages + yet. + +If you plan on using it with a MySQL or PostgreSQL you also need the +corresponding Python package, ``python-pymysql`` for MySQL or +``python-psycopg2`` for PostgreSQL. + +:: + + $ apt-get install python-pymysql + +:: + + $ apt-get install python-psycopg2 + +For other distributions, you might consider installing from `docker`_ images or +from `source`_. + +Windows +------- + +.. note:: + While Supysonic hasn't been thoroughly tested on Windows, it *should* work. + If something is broken, we're really sorry. Don't hesitate to `open an + issue`__ on GitHub. + + __ https://github.com/spl0k/supysonic/issues + +Most Windows users do not have Python installed by default, so we begin with +the installation of Python itself. To check if you already have Python +installed, open the *Command Prompt* (:kbd:`Win-R` and type :command:`cmd`). +Once the command prompt is open, type :command:`python --version` and press +Enter. If Python is installed, you will see the version of Python printed to +the screen. If you do not have Python installed, refer to the `Hitchhikers +Guide to Python's`__ Python on Windows installation guides. You must install +`Python 3`__. + +Once Python is installed, you can install Supysonic using :command:`pip`. Refer +to the `source installation instructions `_ below for more information. + +__ https://docs.python-guide.org/ +__ https://docs.python-guide.org/starting/install3/win/ + +.. _docker: + +Docker +------ + +While we don't provide Docker images for Supysonic, that didn't keep the +community from creating some. Take a look on the `Docker Hub`__ and pick one you +like. For more details on their usage, please refer to the readme of said +images. + +__ https://hub.docker.com/search?q=supysonic&type=image + +.. _source: + +Source +------ + +You can install Supysonic directly from a clone of the `Git repository`__. This +can be done either by cloning the repo and installing from the local clone, or +simply installing directly via :command:`pip`. + +:: + + $ git clone https://github.com/spl0k/supysonic.git + $ cd supysonic + $ pip install . + +:: + + $ pip install git+https://github.com/spl0k/supysonic.git + +This will install Supysonic along with the minimal dependencies it needs to +run. + +If you plan on using it with a MySQL or PostgreSQL you also need the +corresponding package, ``pymysql`` for MySQL or ``psycopg2-binary`` for +PostgreSQL. + +:: + + $ pip install pymysql + +:: + + $ pip install psycopg2-binary + +__ https://github.com/spl0k/supysonic From 15e5114cd916c135768a3a0b36d8741d54580cf7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Sat, 9 Jan 2021 16:58:00 +0100 Subject: [PATCH 08/14] Database setup doc --- docs/setup/database.rst | 39 +++++++++++++++++++++++++++++++++++++++ docs/setup/index.rst | 1 + docs/setup/install.rst | 4 ++-- 3 files changed, 42 insertions(+), 2 deletions(-) create mode 100644 docs/setup/database.rst diff --git a/docs/setup/database.rst b/docs/setup/database.rst new file mode 100644 index 0000000..cd089fa --- /dev/null +++ b/docs/setup/database.rst @@ -0,0 +1,39 @@ +Database setup +============== + +Supysonic needs a database to run. It can either be a SQLite, MySQL-compatible +or PostgreSQL database. + +If you absolutely have no clue about databases, you can go with SQLite as it +doesn't need any setup other than specifying a path for the database in the +:doc:`configuration <../configuration>`. + +.. note:: + + SQLite, while being a viable option, isn't recommended for large + installations. First of all its performance *might* start to decrease as the + size of your library grows. But most importantly if you have a lot of users + reaching the instance at the same time you will start to see the performance + drop, or even errors. + +Please refer to the documentation of the DBMS you've chosen on how to create a +database. Once it has a database, Supysonic will automatically create the +tables it needs and keep the schema up-to-date. + +The PostgreSQL case +------------------- + +If you want to use PostgreSQL you'll have to add the ``citext`` extension to the +database once created. This can be done when connected to the database as the +superuser. How to connect as a superuser might change depending on your +PostgreSQL installation (this is **not** the same thing as the OS superuser +known as *root* on Linux systems). + +On a Debian-based system you can connect as a superuser by invoking +:command:`psql` while being logged in as the *postgres* user. The following +commands will install the ``citext`` extension on the database named *supysonic* +assuming you are currently logged as *root*. :: + + # su - postgres + $ psql supysonic + supysonic=# CREATE EXTENSION citext; diff --git a/docs/setup/index.rst b/docs/setup/index.rst index 58231fc..f347305 100644 --- a/docs/setup/index.rst +++ b/docs/setup/index.rst @@ -8,3 +8,4 @@ start serving your music. :maxdepth: 2 install + database diff --git a/docs/setup/install.rst b/docs/setup/install.rst index 58b2705..b297f1d 100644 --- a/docs/setup/install.rst +++ b/docs/setup/install.rst @@ -21,7 +21,7 @@ run. you're using the *stable* release it might not be available in the packages yet. -If you plan on using it with a MySQL or PostgreSQL you also need the +If you plan on using it with a MySQL or PostgreSQL database you also need the corresponding Python package, ``python-pymysql`` for MySQL or ``python-psycopg2`` for PostgreSQL. @@ -95,7 +95,7 @@ simply installing directly via :command:`pip`. This will install Supysonic along with the minimal dependencies it needs to run. -If you plan on using it with a MySQL or PostgreSQL you also need the +If you plan on using it with a MySQL or PostgreSQL database you also need the corresponding package, ``pymysql`` for MySQL or ``psycopg2-binary`` for PostgreSQL. From 33d0739c4e663883661f8c41db00dfdadd0d195a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Sat, 9 Jan 2021 17:10:56 +0100 Subject: [PATCH 09/14] Moving the configuration doc --- docs/{ => setup}/configuration.rst | 18 +++++++++++------- docs/setup/database.rst | 2 +- docs/setup/index.rst | 1 + 3 files changed, 13 insertions(+), 8 deletions(-) rename docs/{ => setup}/configuration.rst (90%) diff --git a/docs/configuration.rst b/docs/setup/configuration.rst similarity index 90% rename from docs/configuration.rst rename to docs/setup/configuration.rst index 11d91db..5670ae5 100644 --- a/docs/configuration.rst +++ b/docs/setup/configuration.rst @@ -1,15 +1,19 @@ 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. +Supysonic looks for four files for its configuration: :file:`/etc/supysonic`, +:file:`~/.supysonic`, :file:`~/.config/supysonic/supysonic.conf` and +:file:`supysonic.conf` in the current working directory, in this order, 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. +If you cloned Supysonic from its `GitHub repository`__ you'll find a roughly +documented configuration sample file at the root of the project, file +conveniently named :file:`config.sample`. More details below. + +__ http://github.com/spl0k/supysonic ``[base]`` section ------------------ @@ -197,7 +201,7 @@ library folders and providing the jukebox feature. ``jukebox_command`` Command used by the jukebox mode to play a single file. - See the :doc:`jukebox documentation ` for more details. + See the :doc:`jukebox documentation <../jukebox>` for more details. ``log_file`` Rotating file where events generated by the file watcher are logged. @@ -277,7 +281,7 @@ 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 -:doc:`transcoding configuration `. +:doc:`transcoding configuration <../transcoding>`. .. code-block:: ini diff --git a/docs/setup/database.rst b/docs/setup/database.rst index cd089fa..71dc9e9 100644 --- a/docs/setup/database.rst +++ b/docs/setup/database.rst @@ -6,7 +6,7 @@ or PostgreSQL database. If you absolutely have no clue about databases, you can go with SQLite as it doesn't need any setup other than specifying a path for the database in the -:doc:`configuration <../configuration>`. +:doc:`configuration `. .. note:: diff --git a/docs/setup/index.rst b/docs/setup/index.rst index f347305..3abbb73 100644 --- a/docs/setup/index.rst +++ b/docs/setup/index.rst @@ -9,3 +9,4 @@ start serving your music. install database + configuration From 2469698261717d7ca1fc08238a735388db9bef22 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Sun, 10 Jan 2021 18:01:21 +0100 Subject: [PATCH 10/14] Some deployment docs --- docs/setup/deploying/apache.rst | 54 +++++++++++++++++++++ docs/setup/deploying/index.rst | 19 ++++++++ docs/setup/deploying/wsgi-standalone.rst | 61 ++++++++++++++++++++++++ 3 files changed, 134 insertions(+) create mode 100644 docs/setup/deploying/apache.rst create mode 100644 docs/setup/deploying/index.rst create mode 100644 docs/setup/deploying/wsgi-standalone.rst diff --git a/docs/setup/deploying/apache.rst b/docs/setup/deploying/apache.rst new file mode 100644 index 0000000..eba8af7 --- /dev/null +++ b/docs/setup/deploying/apache.rst @@ -0,0 +1,54 @@ +Apache and mod_wsgi +=================== + +If you are using the `Apache`__ webserver, you can use it to run Supysonic with +the help of `mod_wsgi`__. + +__ https://httpd.apache.org/ +__ https://github.com/GrahamDumpleton/mod_wsgi + +Installing `mod_wsgi` +--------------------- + +If you don't have `mod_wsgi` installed yet you have to install it and enable it +first as follows:: + + # apt install libapache2-mod-wsgi-py3 + # a2enmod wsgi + +Creating a `.wsgi` file +----------------------- + +To run Supysonic within Apache you need a :file:`supysonic.wsgi` file. Create +one somewhere and fill it with the following content:: + + from supysonic.web import create_application + application = create_application() + +Store that file somewhere that you will find it again (e.g.: +:file:`/var/www/supysonic/supysonic.wsgi`). + +Configuring Apache +------------------ + +The last thing you have to do is to edit the Apache configuration to tell it to +load the application. Here's a basic example of what it looks like: + +.. code-block:: apache + + WSGIScriptAlias /supysonic /var/www/supysonic/supysonic.wsgi + + WSGIApplicationGroup %{GLOBAL} + WSGIPassAuthorization On + Require all granted + + +With that kind of configuration, the server address will look like +`http://server/supysonic/`. + +For more information consult the `mod_wsgi documentation`__. Note that the +``WSGIPassAuthorization`` directive is required for some clients as they provide +their credentials using the *basic access authentification* mechanism rather +than as URL query parameters. + +__ https://modwsgi.readthedocs.io/en/latest/ diff --git a/docs/setup/deploying/index.rst b/docs/setup/deploying/index.rst new file mode 100644 index 0000000..9ae7ddc --- /dev/null +++ b/docs/setup/deploying/index.rst @@ -0,0 +1,19 @@ +Running the web server +====================== + +Once Supysonic is installed and configured, you'll have to start its web server +for the clients to be able to access the music. Here you have several options, +whether you want to run it as independant process(es), then possibly putting it +behind a reverse proxy, or running it as a WSGI application within Apache. + +As Supysonic is a WSGI application, you have numerous deployment options +available to you. If you want to deploy it to a WSGI server not listed here, +look up the server documentation about how to use a WSGI app with it. When +setting one of those, you'll want to call the :func:`create_application` factory +function from module :mod:`supysonic.web`. + +.. toctree:: + :maxdepth: 2 + + wsgi-standalone + apache diff --git a/docs/setup/deploying/wsgi-standalone.rst b/docs/setup/deploying/wsgi-standalone.rst new file mode 100644 index 0000000..d7fab3d --- /dev/null +++ b/docs/setup/deploying/wsgi-standalone.rst @@ -0,0 +1,61 @@ +Standalone WSGI Containers +========================== + +There are popular servers written in Python that contain WSGI applications and +serve HTTP. These servers stand alone when they run; you can let your clients +access them directly or proxy to them from your web server such as Apache +or nginx. + +Gunicorn +-------- + +`Gunicorn`__ "Green Unicorn" is a WSGI HTTP Server for UNIX. It's a pre-fork +worker model. Running Supysonic on this server is quite simple. First install +Gunicorn with either :command:`pip install gunicorn` or +:command:`apt install gunicorn3` (the ``gunicorn`` package in this case is +for Python 2 which isn't supported anymore). Then:: + + $ gunicorn "supysonic.web:create_application()" + +But this will only listen on the loopback interface, which isn't really useful. + +Gunicorn provides many command-line options -- see :command:`gunicorn -h`. +For example, to run Supysonic with 4 worker processes (``-w 4``) binding to all +IPv4 interfaces on port 5000 (``-b 0.0.0.0:5000``):: + + $ gunicorn -w 4 -b 0.0.0.0:5000 "supysonic.web:create_application()" + +__ https://gunicorn.org/ + +uWSGI +----- + +`uWSGI`__ is a fast application server written in C. It is very configurable +which makes it more complicated to setup than gunicorn. + +To use it, install the package ``uwsgi`` with either :command:`pip` or +:command:`apt`. Using the later, wou might also need the additional package +``uwsgi-plugin-python3``. + +Then to run Supysonic in uWSGI:: + + $ uwsgi --http-socket 0.0.0.0:5000 --module "supysonic.web:create_application()" + +If it complains about an unknown ``--module`` option, try adding +``--plugin python3``:: + + $ uwsgi --http-socket 0.0.0.0:5000 --plugin python3 --module "supysonic.web:create_application()" + +As uWSGI is highly configurable there are several options you could use to tweak +it to your liking. Detailing all it can do is way beyond the scope of this +documentation, if you're interested please refer to its documentation. + +If you plan on using uWSGI behind a nginx reverse proxy, note that nginx +provides options to integrate directly with uWSGI. You'll find an example +configuration in `Flask's documentation`__ (the framework Supysonic is built +upon). Replace the ``myapp:app`` in their example by +``supysonic.web:create_application()`` (you might need to enclose it in +double-quotes). + +__ https://uwsgi-docs.readthedocs.io/en/latest/ +__ https://flask.palletsprojects.com/en/1.1.x/deploying/uwsgi/ From 6bb551a32a30e74bada0e2b295ff1cf581c5ca9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Sat, 16 Jan 2021 16:09:53 +0100 Subject: [PATCH 11/14] FastCGI/CGI deployment docs --- docs/setup/deploying/index.rst | 13 +++-- docs/setup/deploying/other.rst | 96 ++++++++++++++++++++++++++++++++++ docs/setup/index.rst | 1 + docs/setup/install.rst | 9 ++-- 4 files changed, 109 insertions(+), 10 deletions(-) create mode 100644 docs/setup/deploying/other.rst diff --git a/docs/setup/deploying/index.rst b/docs/setup/deploying/index.rst index 9ae7ddc..3d65ffd 100644 --- a/docs/setup/deploying/index.rst +++ b/docs/setup/deploying/index.rst @@ -6,14 +6,17 @@ for the clients to be able to access the music. Here you have several options, whether you want to run it as independant process(es), then possibly putting it behind a reverse proxy, or running it as a WSGI application within Apache. -As Supysonic is a WSGI application, you have numerous deployment options -available to you. If you want to deploy it to a WSGI server not listed here, -look up the server documentation about how to use a WSGI app with it. When -setting one of those, you'll want to call the :func:`create_application` factory -function from module :mod:`supysonic.web`. +You'll find some common (and less common) deployment option below: .. toctree:: :maxdepth: 2 wsgi-standalone apache + other + +As Supysonic is a WSGI application, you have numerous deployment options +available to you. If you want to deploy it to a WSGI server not listed here, +look up the server documentation about how to use a WSGI app with it. When +setting one of those, you'll want to call the :func:`create_application` factory +function from module :mod:`supysonic.web`. diff --git a/docs/setup/deploying/other.rst b/docs/setup/deploying/other.rst new file mode 100644 index 0000000..28a9e03 --- /dev/null +++ b/docs/setup/deploying/other.rst @@ -0,0 +1,96 @@ +Other options +============= + +FastCGI +------- + +FastCGI is a deployment option on servers like `nginx`__ or `lighttpd`__; see +:doc:`wsgi-standalone` for other options. +To use Supysonic with any of them you will need a FastCGI server first. The most +popular one is `flup`__ which we will use for this guide. Make sure to have it +installed (with eith :command:`pip` or :command:`apt`) to follow along. + +__ https://nginx.org/ +__ https://www.lighttpd.net/ +__ https://pypi.org/project/flup/ + +Creating a `.fcgi` file +^^^^^^^^^^^^^^^^^^^^^^^ + +First you need to create the FastCGI server file. Let's call it +:file:`supysonic.fcgi`:: + + #!/usr/bin/python3 + + from flup.server.fcgi import WSGIServer + from supysonic.web import create_application + + if __name__ == '__main__': + app = create_application() + WSGIServer(app).run() + +This should be enough for Apache to work, however nginx and older versions of +lighttpd need a socket to be explicitly passed to communicate with the +FastCGI server. For that to work you need to pass the path to the socket +to the :class:`~flup.server.fcgi.WSGIServer`:: + + WSGIServer(app, bindAddress='/path/to/fcgi.sock').run() + +The path has to be the exact same path you define in the server +config. + +Save the :file:`supysonic.fcgi` file somewhere you will find it again. +It makes sense to have that in :file:`/var/www/supysonic` or something +similar. + +Make sure to set the executable bit on that file so that the servers +can execute it:: + + $ chmod +x /var/www/supysonic/supysonic.fcgi + +Configuring the web server +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The example above is good enough for a basic Apache deployment but your +`.fcgi` file will appear in your application URL e.g. +``example.com/supysonic.fcgi/``. If that bothers you or you wish to load it in +another web server, Flask's documentation details how to do it for `Apache`__, +`lighttpd`__ or `nginx`__. + +__ https://flask.palletsprojects.com/en/1.1.x/deploying/fastcgi/#configuring-apache +__ https://flask.palletsprojects.com/en/1.1.x/deploying/fastcgi/#configuring-lighttpd +__ https://flask.palletsprojects.com/en/1.1.x/deploying/fastcgi/#configuring-nginx + +CGI +--- + +If all other deployment methods do not work, CGI will work for sure. +CGI is supported by all major servers but usually has a sub-optimal +performance. + +Creating a `.cgi` file +^^^^^^^^^^^^^^^^^^^^^^ + +First you need to create the CGI application file. Let's call it +:file:`supysonic.cgi`:: + + #!/usr/bin/python3 + + from wsgiref.handlers import CGIHandler + from supysonic.web import create_application + + app = create_application() + CGIHandler().run(app) + +Server Setup +^^^^^^^^^^^^ + +Usually there are two ways to configure the server. Either just copy the +``.cgi`` into a :file:`cgi-bin` (and use `mod_rewrite` or something similar to +rewrite the URL) or let the server point to the file directly. + +In Apache for example you can put something like this into the config: + +.. sourcecode:: apache + + ScriptAlias /supysonic /path/to/the/supysonic.cgi diff --git a/docs/setup/index.rst b/docs/setup/index.rst index 3abbb73..4cb79c9 100644 --- a/docs/setup/index.rst +++ b/docs/setup/index.rst @@ -10,3 +10,4 @@ start serving your music. install database configuration + deploying/index diff --git a/docs/setup/install.rst b/docs/setup/install.rst index b297f1d..2762595 100644 --- a/docs/setup/install.rst +++ b/docs/setup/install.rst @@ -7,10 +7,9 @@ Linux ----- Currently, only Debian-based distributions might provide Supysonic in their -package repositories. Install the package ``supysonic`` using either -:command:`apt` or :command:`apt-get`:: +package repositories. Install the package ``supysonic`` using :command:`apt`:: - $ apt-get install supysonic + $ apt install supysonic This will install Supysonic along with the minimal dependencies it needs to run. @@ -27,11 +26,11 @@ corresponding Python package, ``python-pymysql`` for MySQL or :: - $ apt-get install python-pymysql + $ apt install python-pymysql :: - $ apt-get install python-psycopg2 + $ apt install python-psycopg2 For other distributions, you might consider installing from `docker`_ images or from `source`_. From 2599f1ae37d2e9e37f13979b0ac9a995f3680bb7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Sat, 16 Jan 2021 17:03:42 +0100 Subject: [PATCH 12/14] Daemon doc --- docs/jukebox.rst | 11 ++++---- docs/setup/daemon.rst | 59 +++++++++++++++++++++++++++++++++++++++++++ docs/setup/index.rst | 13 +++++----- 3 files changed, 71 insertions(+), 12 deletions(-) create mode 100644 docs/setup/daemon.rst diff --git a/docs/jukebox.rst b/docs/jukebox.rst index 3066b4b..f241730 100644 --- a/docs/jukebox.rst +++ b/docs/jukebox.rst @@ -2,17 +2,16 @@ Jukebox mode ============ The jukebox mode allow playing audio files on the hardware of the machine -running *Supysonic*, using regular clients that support it as a remote control. +running Supysonic, using regular clients that support it as a remote control. -The daemon must be running in order to be able to use the jukebox mode. So be -sure to start the ``supysonic-daemon`` command and keep it running. A basic -*systemd* service file can be found at the root of the project folder. +:doc:`setup/daemon` must be running in order to be able to use the jukebox mode. +So be sure to start the :doc:`man/supysonic-daemon` command and keep it running. Setting the player program -------------------------- -Jukebox mode in *Supysonic* works through the use of third-party command-line -programs. *Supysonic* isn't bundled with such programs, and you are left to +Jukebox mode in Supysonic works 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. The chosen program should be able to play a single audio file from a path specified on its command-line. diff --git a/docs/setup/daemon.rst b/docs/setup/daemon.rst new file mode 100644 index 0000000..30d6003 --- /dev/null +++ b/docs/setup/daemon.rst @@ -0,0 +1,59 @@ +The daemon +========== + +Supysonic comes with an optional daemon service that currently provides the +following features: + +- background scans +- library changes detection +- jukebox mode + +Background scans +---------------- + +First of all, the daemon allows running backgrounds scans, meaning you can start +scans from the :doc:`command-line interface <../man/supysonic-cli>` and do +something else while it's scanning (otherwise the scan will block the CLI until +it's done). Background scans also enable the web UI to run scans, while you have +to use the CLI to do so if you don't run the daemon. + +Library watching +---------------- + +Instead of manually running a scan every time your library changes, the daemon +can listen to any library change and update the database accordingly. This +watcher is started along with the daemon but can be disabled to only keep +background scans. Please refer to :ref:`conf-daemon` of the configuration to +enable or disable it. + +Jukebox +------- + +Finally, the daemon acts as a backend for the jukebox mode, allowing to play +audio on the machine running Supysonic. More details on the :doc:`../jukebox` +page. + +Running it +---------- + +The daemon is :doc:`../man/supysonic-daemon`, it is a non-exiting process. +If you want to keep it running in background, either use the old +:command:`nohup` or :command:`screen` methods, or start it as a systemd unit. + +Below is a basic service file to load it through systemd. Modify it to match +your installation and save it as +:file:`/etc/systemd/system/supysonic-daemon.service`. + +.. code-block:: ini + + [Unit] + Description=Supysonic Daemon + + [Service] + User=someuser + Group=somegroup + WorkingDirectory=/home/supysonic + ExecStart=/usr/bin/python3 -m supysonic.daemon + + [Install] + WantedBy=multi-user.target diff --git a/docs/setup/index.rst b/docs/setup/index.rst index 4cb79c9..a2a75bc 100644 --- a/docs/setup/index.rst +++ b/docs/setup/index.rst @@ -1,13 +1,14 @@ Supysonic setup =============== -This guide details the required steps to get a *Supysonic* instance ready to +This guide details the required steps to get a Supysonic instance ready to start serving your music. .. toctree:: - :maxdepth: 2 + :maxdepth: 2 - install - database - configuration - deploying/index + install + database + configuration + deploying/index + daemon From 6d56b56dd5d3ebd4302ba0920c0cefbb5c6479f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Sun, 17 Jan 2021 12:29:37 +0100 Subject: [PATCH 13/14] Some doc touches --- docs/api.rst | 10 ++++++---- docs/index.rst | 30 +++++++++++++++++++++++++++++ docs/jukebox.rst | 1 + docs/man/index.rst | 20 +++++++++++++++++++ docs/man/supysonic-cli-folder.rst | 2 +- docs/man/supysonic-cli-user.rst | 2 +- docs/setup/configuration.rst | 23 +++++++++++----------- docs/setup/index.rst | 32 +++++++++++++++++++++++++++++++ docs/setup/install.rst | 23 ++++------------------ docs/transcoding.rst | 31 ++++++++++++++++++++---------- 10 files changed, 127 insertions(+), 47 deletions(-) create mode 100644 docs/index.rst create mode 100644 docs/man/index.rst diff --git a/docs/api.rst b/docs/api.rst index 73b075b..0ac0598 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,12 +3,14 @@ Subsonic API breakdown This page lists all the API methods and their parameters up to the version 1.16.0 (Subsonic 6.1.2). Here you'll find details about which API features -*Supysonic* support, plan on supporting, or won't. +Supysonic support, plan on supporting, or won't. At the moment, the current target API version is 1.10.2. The following information was gathered by *diff*-ing various snapshots of the -`Subsonic API page `_. +`Subsonic API page`__. + +__ http://www.subsonic.org/pages/api.jsp Methods and parameters listing ------------------------------ @@ -57,7 +59,7 @@ getSongsByGenre_ 1.9.0 βœ”οΈ getNowPlaying_ βœ”οΈ getStarred_ βœ”οΈ getStarred2_ βœ”οΈ -search_ βœ”οΈ +:ref:`search ` βœ”οΈ search2_ βœ”οΈ search3_ βœ”οΈ getPlaylists_ βœ”οΈ @@ -449,7 +451,7 @@ Album/song lists Searching ^^^^^^^^^ -.. _search: +.. _search-: ``search`` βœ”οΈ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..571fa55 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,30 @@ +Welcome to Supysonic's documentation! +===================================== + +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 +* user or random playlists +* cover arts (as image files in the same folder as music files) +* starred tracks/albums and ratings +* `Last.FM`__ scrobbling +* Jukebox mode + +__ http://www.subsonic.org/ +__ https://www.last.fm/ + +User's guide +------------ + +.. toctree:: + :maxdepth: 2 + + setup/index + transcoding + jukebox + man/index + api diff --git a/docs/jukebox.rst b/docs/jukebox.rst index f241730..30f9bf7 100644 --- a/docs/jukebox.rst +++ b/docs/jukebox.rst @@ -21,6 +21,7 @@ following fields: ``%path`` absolute path of the file to be played + ``%offset`` time in seconds where to start playing (used for seeking) diff --git a/docs/man/index.rst b/docs/man/index.rst new file mode 100644 index 0000000..b4b5229 --- /dev/null +++ b/docs/man/index.rst @@ -0,0 +1,20 @@ +Man pages +========= + +Command-line interface +---------------------- + +.. toctree:: + :maxdepth: 2 + + supysonic-cli + supysonic-cli-user + supysonic-cli-folder + +Daemon +------ + +.. toctree:: + :maxdepth: 2 + + supysonic-daemon diff --git a/docs/man/supysonic-cli-folder.rst b/docs/man/supysonic-cli-folder.rst index 869fbd5..d41dca0 100644 --- a/docs/man/supysonic-cli-folder.rst +++ b/docs/man/supysonic-cli-folder.rst @@ -45,7 +45,7 @@ Options -f, --force Force scan of already known files even if they haven't changed. Might be - useful if an update to *Supysonic* adds new metadata to audio files. + useful if an update to Supysonic adds new metadata to audio files. --background Scan in the background. Requires the ``supysonic-daemon`` to be running diff --git a/docs/man/supysonic-cli-user.rst b/docs/man/supysonic-cli-user.rst index c25df9e..b4f51d5 100644 --- a/docs/man/supysonic-cli-user.rst +++ b/docs/man/supysonic-cli-user.rst @@ -82,4 +82,4 @@ To add a new admin user named `MyUserName` having password `MyAwesomePassword`:: See Also ======== -supysonic-cli(1), supysonic-cli-folder(1) +``supysonic-cli``\ (1), ``supysonic-cli-folder``\ (1) diff --git a/docs/setup/configuration.rst b/docs/setup/configuration.rst index 5670ae5..02c091c 100644 --- a/docs/setup/configuration.rst +++ b/docs/setup/configuration.rst @@ -13,7 +13,7 @@ If you cloned Supysonic from its `GitHub repository`__ you'll find a roughly documented configuration sample file at the root of the project, file conveniently named :file:`config.sample`. More details below. -__ http://github.com/spl0k/supysonic +__ https://github.com/spl0k/supysonic ``[base]`` section ------------------ @@ -22,7 +22,7 @@ This sections defines the database and additional scanning config. ``database_uri`` The most important configuration, defines the type and - parameters of the database *Supysonic* should connect to. It usually includes + 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:: @@ -59,7 +59,7 @@ This sections defines the database and additional scanning config. ``utf8mb4`` regardless of what's set on your MySQL installation. If ``database_uri`` isn't provided, it defaults to a SQLite database stored - in ``/tmp/supysonic/supysonic.db``. + in :file:`/tmp/supysonic/supysonic.db`. ``scanner_extensions`` A space separated list of file extensions the scanner is restricted to. @@ -77,8 +77,7 @@ Sample configuration: .. code-block:: ini [base] - ; A database URI. See the 'schema' folder for schema creation scripts - ; Default: sqlite:////tmp/supysonic/supysonic.db + ; A database URI. 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 @@ -96,7 +95,7 @@ Configuration relative to the HTTP server. ``cache_dir`` Directory used to store generated files, such as resized cover art or - transcoded files. Defaults to ``/tmp/supysonic``. + transcoded files. Defaults to :file:`/tmp/supysonic`. ``cache_size`` Maximum size (in megabytes) of the cache (except for trancodes). @@ -123,8 +122,8 @@ Configuration relative to the HTTP server. Defaults to ``WARNING``. ``mount_api`` (``on`` or ``off``) - Enable or disable the Subsonic REST API. Should be kept on or *Supysonic* - would be quite useless. Exists mostly for testing purposes. + 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`` or ``off``) @@ -187,7 +186,7 @@ library folders and providing the jukebox feature. Unix domain socket file (or named pipe on Windows) used to communicate between the daemon and clients that rely on it (eg. CLI, folder admin web page, etc.). Note that using an IP address here isn't supported. - Default: /tmp/supysonic/supysonic.sock + Default: :file:`/tmp/supysonic/supysonic.sock` ``run_watcher`` Whether or not to start the watcher that will listen for library changes. @@ -248,13 +247,13 @@ Sample configuration: -------------------- This section allow defining API keys to enable Last.FM integration in -*Supysonic*. Currently it is only used to *scrobble* played tracks and update +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. +page on Supysonic's administrative UI. ``api_key`` Last.FM API key @@ -298,7 +297,7 @@ For more details, please refer to the ``[mimetypes]`` section ----------------------- -Use this section if the system *Supysonic* is installed on has trouble guessing +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: diff --git a/docs/setup/index.rst b/docs/setup/index.rst index a2a75bc..cc7e4cb 100644 --- a/docs/setup/index.rst +++ b/docs/setup/index.rst @@ -4,6 +4,25 @@ Supysonic setup This guide details the required steps to get a Supysonic instance ready to start serving your music. +TL;DR +----- + +For the impatient, here's a quick summary to get Supysonic installed and ready +to start serving (but this doesn't create any user nor specifies where your +music is located 😏). This uses `gunicorn`__, but there are +:doc:`other options `. + +:: + + pip install git+https://github.com/spl0k/supysonic.git + pip install gunicorn + gunicorn -b 0.0.0.0:5000 "supysonic.web:create_application()" + +__ https://gunicorn.org/ + +Table of contents +----------------- + .. toctree:: :maxdepth: 2 @@ -12,3 +31,16 @@ start serving your music. configuration deploying/index daemon + +.. _docker: + +Docker +------ + +Another solution rather than going through the whole setup process yourself is +to use a ready-to-use Docker image. While we don't provide images for Supysonic, +that didn't keep the community from creating some. Take a look on the +`Docker Hub`__ and pick one you like. For more details on their usage, please +refer to the readme of said images. + +__ https://hub.docker.com/search?q=supysonic&type=image diff --git a/docs/setup/install.rst b/docs/setup/install.rst index 2762595..9482c9e 100644 --- a/docs/setup/install.rst +++ b/docs/setup/install.rst @@ -32,8 +32,8 @@ corresponding Python package, ``python-pymysql`` for MySQL or $ apt install python-psycopg2 -For other distributions, you might consider installing from `docker`_ images or -from `source`_. +For other distributions, you might consider installing from :ref:`docker` images +or from `source`_. Windows ------- @@ -60,34 +60,19 @@ to the `source installation instructions `_ below for more information. __ https://docs.python-guide.org/ __ https://docs.python-guide.org/starting/install3/win/ -.. _docker: - -Docker ------- - -While we don't provide Docker images for Supysonic, that didn't keep the -community from creating some. Take a look on the `Docker Hub`__ and pick one you -like. For more details on their usage, please refer to the readme of said -images. - -__ https://hub.docker.com/search?q=supysonic&type=image - .. _source: Source ------ You can install Supysonic directly from a clone of the `Git repository`__. This -can be done either by cloning the repo and installing from the local clone, or -simply installing directly via :command:`pip`. - -:: +can be done either by cloning the repo and installing from the local clone:: $ git clone https://github.com/spl0k/supysonic.git $ cd supysonic $ pip install . -:: +or simply installing directly via :command:`pip`:: $ pip install git+https://github.com/spl0k/supysonic.git diff --git a/docs/transcoding.rst b/docs/transcoding.rst index ba45744..34105a7 100644 --- a/docs/transcoding.rst +++ b/docs/transcoding.rst @@ -6,12 +6,12 @@ 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. +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 +can force Supysonic to transcode for that client by going to your profile page on the web interface. Configuration @@ -45,7 +45,7 @@ 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 +Supysonic will take the first available transcoding configuration in the following order: #. specific transcoder @@ -59,26 +59,37 @@ 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 + ``%title`` title of the file to transcode + ``%album`` album name of the file to transcode + ``%artist`` artist name of the file to transcode + ``%tracknumber`` track number of the file to transcode + ``%totaltracks`` number of tracks in the album of the file to transcode + ``%discnumber`` disc number of the file to transcode + ``%genre`` genre of the file to transcode (not always available, defaults to "") + ``%year`` year of the file to transcode (not always available, defaults to "") @@ -126,14 +137,14 @@ Enabling transcoding Once the transcoding configuration has been set, most clients will require the user to specify that they want to transcode files. This might be done on the -client itself, but most importantly it should be done on *Supysonic* web +client itself, but most importantly it should be done on Supysonic web interface. Not doing so might prevent some clients to properly request transcoding. To enable transcoding with the web interface, you should first start using the client you want to set transcoding for. Only browsing the library should suffice. Then open your browser of choice and navigate to the URL of your -*Supysonic* instance. Log in with your credentials and the click on your -username in the top bar. There you should be presented with a list of clients -you used to connect to *Supysonic* and be able to set you preferred streaming -format and bitrate. +Supysonic instance. Log in with your credentials and the click on your username +in the top bar. There you should be presented with a list of clients you used to +connect to Supysonic and be able to set your preferred streaming format +and bitrate. From 78337265bede08f62e4f2e41fd8a6a6e0b34edb6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Sun, 17 Jan 2021 17:06:44 +0100 Subject: [PATCH 14/14] Sphinx config, sidebar, etc. --- docs/Makefile | 20 ++++++++ docs/conf.py | 88 +++++++++++++++++++++++++++++++++ docs/index.rst | 3 +- docs/man/index.rst | 6 +-- docs/setup/configuration.rst | 24 ++++----- docs/setup/deploying/apache.rst | 4 +- docs/setup/deploying/index.rst | 4 +- docs/setup/deploying/other.rst | 18 ++++--- docs/setup/index.rst | 9 ++-- docs/transcoding.rst | 8 ++- 10 files changed, 143 insertions(+), 41 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/conf.py diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..fd69c42 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,88 @@ +# -- Project information ----------------------------------------------------- + +project = "Supysonic" +author = "Alban FΓ©ron" +copyright = "2013-2021, " + author + +version = "0.6.2" +release = "0.6.2" + + +# -- General configuration --------------------------------------------------- + +extensions = [] +templates_path = [] +source_suffix = ".rst" +master_doc = "index" +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +primary_domain = None +highlight_language = "none" + +language = None + + +# -- Options for HTML output ------------------------------------------------- + +html_theme = "alabaster" +html_theme_options = { + "description": "A Python implementation of the Subsonic server API", + "github_user": "spl0k", + "github_repo": "supysonic", +} +html_static_path = [] + +# Default alabaseter sidebars + localtoc +html_sidebars = { + "**": [ + "about.html", + "localtoc.html", + "navigation.html", + "relations.html", + "searchbox.html", + "donate.html", + ] +} + +html_domain_indices = False + + +# -- Options for manual page output ------------------------------------------ + +_man_authors = ["Louis-Philippe VΓ©ronneau", author] + +# Man pages, they are writter to be generated directly by `rst2man` so using +# Sphinx to build them will give weird sections, but if we ever need it it's +# there + +# (source start file, name, description, authors, manual section). +man_pages = [ + ( + "man/supysonic-cli", + "supysonic-cli", + "Python implementation of the Subsonic server API", + _man_authors, + 1, + ), + ( + "man/supysonic-cli-user", + "supysonic-cli-user", + "Supysonic user management commands", + _man_authors, + 1, + ), + ( + "man/supysonic-cli-folder", + "supysonic-cli-folder", + "Supysonic folder management commands", + _man_authors, + 1, + ), + ( + "man/supysonic-daemon", + "supysonic-daemon", + "Supysonic background daemon", + _man_authors, + 1, + ), +] diff --git a/docs/index.rst b/docs/index.rst index 571fa55..7ec46f8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,8 +17,7 @@ Current supported features are: __ http://www.subsonic.org/ __ https://www.last.fm/ -User's guide ------------- +.. rubric:: User's guide .. toctree:: :maxdepth: 2 diff --git a/docs/man/index.rst b/docs/man/index.rst index b4b5229..a5d55bc 100644 --- a/docs/man/index.rst +++ b/docs/man/index.rst @@ -1,8 +1,7 @@ Man pages ========= -Command-line interface ----------------------- +.. rubric:: Command-line interface .. toctree:: :maxdepth: 2 @@ -11,8 +10,7 @@ Command-line interface supysonic-cli-user supysonic-cli-folder -Daemon ------- +.. rubric:: Daemon .. toctree:: :maxdepth: 2 diff --git a/docs/setup/configuration.rst b/docs/setup/configuration.rst index 02c091c..8f536ba 100644 --- a/docs/setup/configuration.rst +++ b/docs/setup/configuration.rst @@ -41,7 +41,9 @@ This sections defines the database and additional scanning config. 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. - .. code-block:: ini + .. highlight:: ini + + :: ; Relative path database_uri = sqlite:///relative-file.db @@ -72,9 +74,7 @@ This sections defines the database and additional scanning config. Disabled by default, enable it only if you trust your file system as nothing is done to handle broken links or loops. -Sample configuration: - -.. code-block:: ini +Sample configuration:: [base] ; A database URI. Default: sqlite:////tmp/supysonic/supysonic.db @@ -142,9 +142,7 @@ Configuration relative to the HTTP server. case insensitive. Defaults to ``El La Le Las Les Los The``. -Sample configuration: - -.. code-block:: ini +Sample configuration:: [webapp] ; Optional cache directory. Default: /tmp/supysonic @@ -218,9 +216,7 @@ library folders and providing the jukebox feature. Defaults to ``WARNING``. -Sample configuration: - -.. code-block:: ini +Sample configuration:: [daemon] ; Socket file the daemon will listen on for incoming management commands @@ -261,9 +257,7 @@ page on Supysonic's administrative UI. ``secret`` secret key associated to the API key -Sample configuration: - -.. code-block:: ini +Sample configuration:: [lastfm] ; API and secret key to enable scrobbling. http://www.last.fm/api/accounts @@ -282,7 +276,7 @@ have **not** been thoroughly tested. For more details, please refer to the :doc:`transcoding configuration <../transcoding>`. -.. code-block:: ini +:: [transcoding] ; Programs used to convert from one format/bitrate to another. Defaults: none @@ -305,7 +299,7 @@ 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 -.. code-block:: ini +:: [mimetypes] ; Extension to mimetype mappings in case your system has some trouble guessing diff --git a/docs/setup/deploying/apache.rst b/docs/setup/deploying/apache.rst index eba8af7..2f8eebb 100644 --- a/docs/setup/deploying/apache.rst +++ b/docs/setup/deploying/apache.rst @@ -20,7 +20,9 @@ Creating a `.wsgi` file ----------------------- To run Supysonic within Apache you need a :file:`supysonic.wsgi` file. Create -one somewhere and fill it with the following content:: +one somewhere and fill it with the following content: + +.. code-block:: python3 from supysonic.web import create_application application = create_application() diff --git a/docs/setup/deploying/index.rst b/docs/setup/deploying/index.rst index 3d65ffd..79b4502 100644 --- a/docs/setup/deploying/index.rst +++ b/docs/setup/deploying/index.rst @@ -18,5 +18,5 @@ You'll find some common (and less common) deployment option below: As Supysonic is a WSGI application, you have numerous deployment options available to you. If you want to deploy it to a WSGI server not listed here, look up the server documentation about how to use a WSGI app with it. When -setting one of those, you'll want to call the :func:`create_application` factory -function from module :mod:`supysonic.web`. +setting one of those, you'll want to call the :py:func:`create_application` +factory function from module :py:mod:`supysonic.web`. diff --git a/docs/setup/deploying/other.rst b/docs/setup/deploying/other.rst index 28a9e03..90fa449 100644 --- a/docs/setup/deploying/other.rst +++ b/docs/setup/deploying/other.rst @@ -18,23 +18,27 @@ Creating a `.fcgi` file ^^^^^^^^^^^^^^^^^^^^^^^ First you need to create the FastCGI server file. Let's call it -:file:`supysonic.fcgi`:: +:file:`supysonic.fcgi`: + +.. code-block:: python3 #!/usr/bin/python3 from flup.server.fcgi import WSGIServer from supysonic.web import create_application - if __name__ == '__main__': + if __name__ == "__main__": app = create_application() WSGIServer(app).run() This should be enough for Apache to work, however nginx and older versions of lighttpd need a socket to be explicitly passed to communicate with the FastCGI server. For that to work you need to pass the path to the socket -to the :class:`~flup.server.fcgi.WSGIServer`:: +to the :py:class:`~flup.server.fcgi.WSGIServer`: - WSGIServer(app, bindAddress='/path/to/fcgi.sock').run() +.. code-block:: python3 + + WSGIServer(app, bindAddress="/path/to/fcgi.sock").run() The path has to be the exact same path you define in the server config. @@ -72,7 +76,9 @@ Creating a `.cgi` file ^^^^^^^^^^^^^^^^^^^^^^ First you need to create the CGI application file. Let's call it -:file:`supysonic.cgi`:: +:file:`supysonic.cgi`: + +.. code-block:: python3 #!/usr/bin/python3 @@ -91,6 +97,6 @@ rewrite the URL) or let the server point to the file directly. In Apache for example you can put something like this into the config: -.. sourcecode:: apache +.. code-block:: apache ScriptAlias /supysonic /path/to/the/supysonic.cgi diff --git a/docs/setup/index.rst b/docs/setup/index.rst index cc7e4cb..610c25f 100644 --- a/docs/setup/index.rst +++ b/docs/setup/index.rst @@ -4,8 +4,7 @@ Supysonic setup This guide details the required steps to get a Supysonic instance ready to start serving your music. -TL;DR ------ +.. rubric:: TL;DR For the impatient, here's a quick summary to get Supysonic installed and ready to start serving (but this doesn't create any user nor specifies where your @@ -20,8 +19,7 @@ music is located 😏). This uses `gunicorn`__, but there are __ https://gunicorn.org/ -Table of contents ------------------ +.. rubric:: Table of contents .. toctree:: :maxdepth: 2 @@ -34,8 +32,7 @@ Table of contents .. _docker: -Docker ------- +.. rubric:: Docker Another solution rather than going through the whole setup process yourself is to use a ready-to-use Docker image. While we don't provide images for Supysonic, diff --git a/docs/transcoding.rst b/docs/transcoding.rst index 34105a7..fe53410 100644 --- a/docs/transcoding.rst +++ b/docs/transcoding.rst @@ -104,9 +104,9 @@ Suggested configuration Here is an example configuration that you could use. This is provided as-is, and some configurations haven't been tested. -Basic configuration: +.. highlight:: ini -.. code-block:: ini +Basic configuration:: [transcoding] transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath - @@ -118,9 +118,7 @@ Basic configuration: encoder_ogg = oggenc2 -Q -M %outrate - default_transcode_target = mp3 -To include track metadata in the transcoded stream: - -.. code-block:: ini +To include track metadata in the transcoded stream:: [transcoding] transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate --tt %title --tl %album --ta %artist --tn %tracknumber/%totaltracks --tv TPOS=%discnumber --tg %genre --ty %year --add-id3v2 %srcpath -