github/supysonic
1
0
Fork 0
mirror of https://github.com/spl0k/supysonic.git synced 2024-11-09 11:42:16 +00:00
Code Issues Releases Wiki Activity

CRLF -> LF

Browse Source
This commit is contained in:
Alban Féron 2021-01-23 15:44:15 +01:00
parent 4735003bc4
commit 05b1a1123f
No known key found for this signature in database
GPG Key ID: 8CE0313646D16165
7 changed files with 2190 additions and 2190 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
config.sample
View File

@ -1,89 +1,89 @@
[base] [base]
; A database URI. See the 'schema' folder for schema creation scripts. Note that ; A database URI. See the 'schema' folder for schema creation scripts. Note that
; you don't have to run these scripts yourself. ; you don't have to run these scripts yourself.
; Default: sqlite:////tmp/supysonic/supysonic.db ; Default: sqlite:////tmp/supysonic/supysonic.db
;database_uri = sqlite:////var/supysonic/supysonic.db ;database_uri = sqlite:////var/supysonic/supysonic.db
;database_uri = mysql://supysonic:supysonic@localhost/supysonic ;database_uri = mysql://supysonic:supysonic@localhost/supysonic
;database_uri = postgres://supysonic:supysonic@localhost/supysonic ;database_uri = postgres://supysonic:supysonic@localhost/supysonic
; Optional, restrict scanner to these extensions. Default: none ; Optional, restrict scanner to these extensions. Default: none
;scanner_extensions = mp3 ogg ;scanner_extensions = mp3 ogg
; Should the scanner follow symbolic links? Default: no ; Should the scanner follow symbolic links? Default: no
follow_symlinks = no follow_symlinks = no
[webapp] [webapp]
; Optional cache directory. Default: /tmp/supysonic ; Optional cache directory. Default: /tmp/supysonic
cache_dir = /var/supysonic/cache cache_dir = /var/supysonic/cache
; Main cache max size in MB. Default: 512 ; Main cache max size in MB. Default: 512
cache_size = 512 cache_size = 512
; Transcode cache max size in MB. Default: 1024 (1GB) ; Transcode cache max size in MB. Default: 1024 (1GB)
transcode_cache_size = 1024 transcode_cache_size = 1024
; Optional rotating log file. Default: none ; Optional rotating log file. Default: none
log_file = /var/supysonic/supysonic.log log_file = /var/supysonic/supysonic.log
; Log level. Possible values: DEBUG, INFO, WARNING, ERROR, CRITICAL. ; Log level. Possible values: DEBUG, INFO, WARNING, ERROR, CRITICAL.
; Default: WARNING ; Default: WARNING
log_level = WARNING log_level = WARNING
; Enable the Subsonic REST API. You'll most likely want to keep this on, here ; Enable the Subsonic REST API. You'll most likely want to keep this on, here
; for testing purposes. Default: on ; for testing purposes. Default: on
;mount_api = on ;mount_api = on
; Enable the administrative web interface. Default: on ; Enable the administrative web interface. Default: on
;mount_webui = on ;mount_webui = on
; Space separated list of prefixes that should be ignored on index endpoints ; Space separated list of prefixes that should be ignored on index endpoints
; Default: El La Le Las Les Los The ; Default: El La Le Las Les Los The
index_ignored_prefixes = El La Le Las Les Los The index_ignored_prefixes = El La Le Las Les Los The
[daemon] [daemon]
; Socket file the daemon will listen on for incoming management commands ; Socket file the daemon will listen on for incoming management commands
; Default: /tmp/supysonic/supysonic.sock ; Default: /tmp/supysonic/supysonic.sock
socket = /var/run/supysonic.sock socket = /var/run/supysonic.sock
; Defines if the file watcher should be started. Default: yes ; Defines if the file watcher should be started. Default: yes
run_watcher = yes run_watcher = yes
; Delay in seconds before triggering scanning operation after a change have been ; Delay in seconds before triggering scanning operation after a change have been
; detected. ; detected.
; This prevents running too many scans when multiple changes are detected for a ; This prevents running too many scans when multiple changes are detected for a
; single file over a short time span. Default: 5 ; single file over a short time span. Default: 5
wait_delay = 5 wait_delay = 5
; Command used by the jukebox ; Command used by the jukebox
jukebox_command = mplayer -ss %offset %path jukebox_command = mplayer -ss %offset %path
; Optional rotating log file for the scanner daemon. Logs to stderr if empty ; Optional rotating log file for the scanner daemon. Logs to stderr if empty
log_file = /var/supysonic/supysonic-daemon.log log_file = /var/supysonic/supysonic-daemon.log
log_level = INFO log_level = INFO
[lastfm] [lastfm]
; API and secret key to enable scrobbling. http://www.last.fm/api/accounts ; API and secret key to enable scrobbling. http://www.last.fm/api/accounts
; Defaults: none ; Defaults: none
;api_key = ;api_key =
;secret = ;secret =
[transcoding] [transcoding]
; Programs used to convert from one format/bitrate to another. Defaults: none ; Programs used to convert from one format/bitrate to another. Defaults: none
transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath - transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath -
transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt - transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt -
decoder_mp3 = mpg123 --quiet -w - %srcpath decoder_mp3 = mpg123 --quiet -w - %srcpath
decoder_ogg = oggdec -o %srcpath decoder_ogg = oggdec -o %srcpath
decoder_flac = flac -d -c -s %srcpath decoder_flac = flac -d -c -s %srcpath
encoder_mp3 = lame --quiet -b %outrate - - encoder_mp3 = lame --quiet -b %outrate - -
encoder_ogg = oggenc2 -Q -M %outrate - encoder_ogg = oggenc2 -Q -M %outrate -
; Default format, used when a client requests a bitrate lower than the original ; Default format, used when a client requests a bitrate lower than the original
; file and no specific format ; file and no specific format
default_transcode_target = mp3 default_transcode_target = mp3
[mimetypes] [mimetypes]
; Extension to mimetype mappings in case your system has some trouble guessing ; Extension to mimetype mappings in case your system has some trouble guessing
; Default: none ; Default: none
;mp3 = audio/mpeg ;mp3 = audio/mpeg
;ogg = audio/vorbis ;ogg = audio/vorbis

2966
docs/api.rst
View File

File diff suppressed because it is too large Load Diff

176
docs/conf.py
View File

@ -1,88 +1,88 @@
# -- Project information ----------------------------------------------------- # -- Project information -----------------------------------------------------
project = "Supysonic" project = "Supysonic"
author = "Alban Féron" author = "Alban Féron"
copyright = "2013-2021, " + author copyright = "2013-2021, " + author
version = "0.6.2" version = "0.6.2"
release = "0.6.2" release = "0.6.2"
# -- General configuration --------------------------------------------------- # -- General configuration ---------------------------------------------------
extensions = [] extensions = []
templates_path = [] templates_path = []
source_suffix = ".rst" source_suffix = ".rst"
master_doc = "index" master_doc = "index"
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
primary_domain = None primary_domain = None
highlight_language = "none" highlight_language = "none"
language = None language = None
# -- Options for HTML output ------------------------------------------------- # -- Options for HTML output -------------------------------------------------
html_theme = "alabaster" html_theme = "alabaster"
html_theme_options = { html_theme_options = {
"description": "A Python implementation of the Subsonic server API", "description": "A Python implementation of the Subsonic server API",
"github_user": "spl0k", "github_user": "spl0k",
"github_repo": "supysonic", "github_repo": "supysonic",
} }
html_static_path = ["_static"] html_static_path = ["_static"]
# Default alabaseter sidebars + localtoc # Default alabaseter sidebars + localtoc
html_sidebars = { html_sidebars = {
"**": [ "**": [
"about.html", "about.html",
"localtoc.html", "localtoc.html",
"navigation.html", "navigation.html",
"relations.html", "relations.html",
"searchbox.html", "searchbox.html",
"donate.html", "donate.html",
] ]
} }
html_domain_indices = False html_domain_indices = False
# -- Options for manual page output ------------------------------------------ # -- Options for manual page output ------------------------------------------
_man_authors = ["Louis-Philippe Véronneau", author] _man_authors = ["Louis-Philippe Véronneau", author]
# Man pages, they are writter to be generated directly by `rst2man` so using # 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 # Sphinx to build them will give weird sections, but if we ever need it it's
# there # there
# (source start file, name, description, authors, manual section). # (source start file, name, description, authors, manual section).
man_pages = [ man_pages = [
( (
"man/supysonic-cli", "man/supysonic-cli",
"supysonic-cli", "supysonic-cli",
"Python implementation of the Subsonic server API", "Python implementation of the Subsonic server API",
_man_authors, _man_authors,
1, 1,
), ),
( (
"man/supysonic-cli-user", "man/supysonic-cli-user",
"supysonic-cli-user", "supysonic-cli-user",
"Supysonic user management commands", "Supysonic user management commands",
_man_authors, _man_authors,
1, 1,
), ),
( (
"man/supysonic-cli-folder", "man/supysonic-cli-folder",
"supysonic-cli-folder", "supysonic-cli-folder",
"Supysonic folder management commands", "Supysonic folder management commands",
_man_authors, _man_authors,
1, 1,
), ),
( (
"man/supysonic-daemon", "man/supysonic-daemon",
"supysonic-daemon", "supysonic-daemon",
"Supysonic background daemon", "Supysonic background daemon",
_man_authors, _man_authors,
1, 1,
), ),
] ]

58
docs/index.rst
View File

@ -1,29 +1,29 @@
Welcome to Supysonic's documentation! Welcome to Supysonic's documentation!
===================================== =====================================
Supysonic is a Python implementation of the `Subsonic`__ server API. Supysonic is a Python implementation of the `Subsonic`__ server API.
Current supported features are: Current supported features are:
* browsing (by folders or tags) * browsing (by folders or tags)
* streaming of various audio file formats * streaming of various audio file formats
* transcoding * transcoding
* user or random playlists * user or random playlists
* cover arts (as image files in the same folder as music files) * cover arts (as image files in the same folder as music files)
* starred tracks/albums and ratings * starred tracks/albums and ratings
* `Last.FM`__ scrobbling * `Last.FM`__ scrobbling
* Jukebox mode * Jukebox mode
__ http://www.subsonic.org/ __ http://www.subsonic.org/
__ https://www.last.fm/ __ https://www.last.fm/
.. rubric:: User's guide .. rubric:: User's guide
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
setup/index setup/index
transcoding transcoding
jukebox jukebox
man/index man/index
api api

90
docs/jukebox.rst
View File

@ -1,45 +1,45 @@
Jukebox mode Jukebox mode
============ ============
The jukebox mode allow playing audio files on the hardware of the machine 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.
:doc:`setup/daemon` must be running in order to be able to use the jukebox mode. :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. So be sure to start the :doc:`man/supysonic-daemon` command and keep it running.
Setting the player program Setting the player program
-------------------------- --------------------------
Jukebox mode in Supysonic works through the use of third-party command-line 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 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 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. single audio file from a path specified on its command-line.
The configuration is done in the :ref:`conf-daemon` of the configuration file, The configuration is done in the :ref:`conf-daemon` of the configuration file,
with the ``jukebox_command`` variable. This variable should include the with the ``jukebox_command`` variable. This variable should include the
following fields: following fields:
``%path`` ``%path``
absolute path of the file to be played absolute path of the file to be played
``%offset`` ``%offset``
time in seconds where to start playing (used for seeking) time in seconds where to start playing (used for seeking)
Here's an example using ``mplayer``:: Here's an example using ``mplayer``::
jukebox_command = mplayer -ss %offset %path jukebox_command = mplayer -ss %offset %path
Or using ``mpv``:: Or using ``mpv``::
jukebox_command = mpv --start=%offset %path jukebox_command = mpv --start=%offset %path
Setting the output volume isn't currently supported. Setting the output volume isn't currently supported.
Allowing users to act on the jukebox Allowing users to act on the jukebox
------------------------------------ ------------------------------------
The jukebox mode is only accessible to chosen users. Granting (or revoking) The jukebox mode is only accessible to chosen users. Granting (or revoking)
jukebox usage rights to a specific user is done with the jukebox usage rights to a specific user is done with the
:doc:`command line interface <man/supysonic-cli-user>`:: :doc:`command line interface <man/supysonic-cli-user>`::
$ supysonic-cli user setroles --jukebox <username> $ supysonic-cli user setroles --jukebox <username>

616
docs/setup/configuration.rst
View File

@ -1,308 +1,308 @@
Configuration Configuration
============= =============
Supysonic looks for four files for its configuration: :file:`/etc/supysonic`, Supysonic looks for four files for its configuration: :file:`/etc/supysonic`,
:file:`~/.supysonic`, :file:`~/.config/supysonic/supysonic.conf` and :file:`~/.supysonic`, :file:`~/.config/supysonic/supysonic.conf` and
:file:`supysonic.conf` in the current working directory, in this order, merging :file:`supysonic.conf` in the current working directory, in this order, merging
values from all files. values from all files.
Configuration files must respect a structure similar to Windows INI file, with Configuration files must respect a structure similar to Windows INI file, with
``[section]`` headers and using a ``KEY = VALUE`` or ``KEY: VALUE`` syntax. ``[section]`` headers and using a ``KEY = VALUE`` or ``KEY: VALUE`` syntax.
If you cloned Supysonic from its `GitHub repository`__ you'll find a roughly If you cloned Supysonic from its `GitHub repository`__ you'll find a roughly
documented configuration sample file at the root of the project, file documented configuration sample file at the root of the project, file
conveniently named :file:`config.sample`. More details below. conveniently named :file:`config.sample`. More details below.
__ https://github.com/spl0k/supysonic __ https://github.com/spl0k/supysonic
``[base]`` section ``[base]`` section
------------------ ------------------
This sections defines the database and additional scanning config. This sections defines the database and additional scanning config.
``database_uri`` ``database_uri``
The most important configuration, defines the type and 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 username, password, hostname and database name. The typical form of a
database URI is:: database URI is::
driver://username:password@host:port/database driver://username:password@host:port/database
If the connection needs some additional parameters, they can be provided as a If the connection needs some additional parameters, they can be provided as a
query string, such as:: query string, such as::
driver://username:password@host:port/database?param1=value1&param2=value2 driver://username:password@host:port/database?param1=value1&param2=value2
Supported drivers are ``sqlite``, ``mysql`` and ``postgres`` (or Supported drivers are ``sqlite``, ``mysql`` and ``postgres`` (or
``postgresql``). ``postgresql``).
As SQLite connects to local files, the format is slightly different. The 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 "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 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. followed by the absolute path, meaning actually four slashes on Unix systems.
.. highlight:: ini .. highlight:: ini
:: ::
; Relative path ; Relative path
database_uri = sqlite:///relative-file.db database_uri = sqlite:///relative-file.db
; Absolute path on Unix-based systems ; Absolute path on Unix-based systems
database_uri = sqlite:////home/user/supysonic.db database_uri = sqlite:////home/user/supysonic.db
; Absolute path on Windows ; Absolute path on Windows
database_uri = sqlite:///C:\Users\user\supysonic.db database_uri = sqlite:///C:\Users\user\supysonic.db
A MySQL-compatible database requires either ``MySQLdb`` or ``pymysql`` to be A MySQL-compatible database requires either ``MySQLdb`` or ``pymysql`` to be
installed. PostgreSQL needs ``psycopg2``. installed. PostgreSQL needs ``psycopg2``.
.. note:: .. note::
For MySQL if no character set is defined on the URI it defaults to For MySQL if no character set is defined on the URI it defaults to
``utf8mb4`` regardless of what's set on your MySQL installation. ``utf8mb4`` regardless of what's set on your MySQL installation.
If ``database_uri`` isn't provided, it defaults to a SQLite database stored If ``database_uri`` isn't provided, it defaults to a SQLite database stored
in :file:`/tmp/supysonic/supysonic.db`. in :file:`/tmp/supysonic/supysonic.db`.
``scanner_extensions`` ``scanner_extensions``
A space separated list of file extensions the scanner is restricted to. 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 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. serve some. If left empty, the scanner will try to read every file it finds.
``follow_symlinks`` ``follow_symlinks``
If set to ``yes``, allows the scanner to follow symbolic links. 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 Disabled by default, enable it only if you trust your file system as nothing
is done to handle broken links or loops. is done to handle broken links or loops.
Sample configuration:: Sample configuration::
[base] [base]
; A database URI. Default: sqlite:////tmp/supysonic/supysonic.db ; A database URI. Default: sqlite:////tmp/supysonic/supysonic.db
database_uri = sqlite:////var/supysonic/supysonic.db database_uri = sqlite:////var/supysonic/supysonic.db
;database_uri = mysql://supysonic:supysonic@localhost/supysonic ;database_uri = mysql://supysonic:supysonic@localhost/supysonic
;database_uri = postgres://supysonic:supysonic@localhost/supysonic ;database_uri = postgres://supysonic:supysonic@localhost/supysonic
; Optional, restrict scanner to these extensions. Default: none ; Optional, restrict scanner to these extensions. Default: none
scanner_extensions = mp3 ogg scanner_extensions = mp3 ogg
; Should the scanner follow symbolic links? Default: no ; Should the scanner follow symbolic links? Default: no
follow_symlinks = no follow_symlinks = no
``[webapp]`` section ``[webapp]`` section
-------------------- --------------------
Configuration relative to the HTTP server. Configuration relative to the HTTP server.
``cache_dir`` ``cache_dir``
Directory used to store generated files, such as resized cover art or Directory used to store generated files, such as resized cover art or
transcoded files. Defaults to :file:`/tmp/supysonic`. transcoded files. Defaults to :file:`/tmp/supysonic`.
``cache_size`` ``cache_size``
Maximum size (in megabytes) of the cache (except for trancodes). Maximum size (in megabytes) of the cache (except for trancodes).
Defaults to 512 MB. Defaults to 512 MB.
``transcode_cache_size`` ``transcode_cache_size``
Maximum size (in megabytes) of the transcode cache. Maximum size (in megabytes) of the transcode cache.
Defaults to 1024 MB (1 GB). Defaults to 1024 MB (1 GB).
``log_file`` ``log_file``
Rotating file where some events generated by the web server are Rotating file where some events generated by the web server are
logged. Leave empty to disable logging. logged. Leave empty to disable logging.
``log_level`` ``log_level``
Defines the minimum severity threshold of messages to be added to Defines the minimum severity threshold of messages to be added to
``log_file``. Possible values are: ``log_file``. Possible values are:
* ``DEBUG`` * ``DEBUG``
* ``INFO`` * ``INFO``
* ``WARNING`` * ``WARNING``
* ``ERROR`` * ``ERROR``
* ``CRITICAL`` * ``CRITICAL``
Defaults to ``WARNING``. Defaults to ``WARNING``.
``mount_api`` (``on`` or ``off``) ``mount_api`` (``on`` or ``off``)
Enable or disable the Subsonic REST API. Should be kept on or Supysonic would Enable or disable the Subsonic REST API. Should be kept on or Supysonic would
be quite useless. Exists mostly for testing purposes. be quite useless. Exists mostly for testing purposes.
Defaults to ``on``. Defaults to ``on``.
``mount_webui`` (``on`` or ``off``) ``mount_webui`` (``on`` or ``off``)
Enable or disable the administrative web interface. Enable or disable the administrative web interface.
.. note:: .. note::
Setting this off will prevent users from defining a preferred transcoding Setting this off will prevent users from defining a preferred transcoding
format. format.
Defaults to ``on``. Defaults to ``on``.
``index_ignored_prefixes`` ``index_ignored_prefixes``
Space-separated list of prefixes that should be ignored from artist names 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, 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 artist *The Rolling Stones* will be listed under the letter *R*. The match is
case insensitive. case insensitive.
Defaults to ``El La Le Las Les Los The``. Defaults to ``El La Le Las Les Los The``.
Sample configuration:: Sample configuration::
[webapp] [webapp]
; Optional cache directory. Default: /tmp/supysonic ; Optional cache directory. Default: /tmp/supysonic
cache_dir = /var/supysonic/cache cache_dir = /var/supysonic/cache
; Main cache max size in MB. Default: 512 ; Main cache max size in MB. Default: 512
cache_size = 512 cache_size = 512
; Transcode cache max size in MB. Default: 1024 (1GB) ; Transcode cache max size in MB. Default: 1024 (1GB)
transcode_cache_size = 1024 transcode_cache_size = 1024
; Optional rotating log file. Default: none ; Optional rotating log file. Default: none
log_file = /var/supysonic/supysonic.log log_file = /var/supysonic/supysonic.log
; Log level. Possible values: DEBUG, INFO, WARNING, ERROR, CRITICAL. ; Log level. Possible values: DEBUG, INFO, WARNING, ERROR, CRITICAL.
; Default: WARNING ; Default: WARNING
log_level = WARNING log_level = WARNING
; Enable the Subsonic REST API. You'll most likely want to keep this on. ; Enable the Subsonic REST API. You'll most likely want to keep this on.
; Here for testing purposes. Default: on ; Here for testing purposes. Default: on
;mount_api = on ;mount_api = on
; Enable the administrative web interface. Default: on ; Enable the administrative web interface. Default: on
;mount_webui = on ;mount_webui = on
; Space separated list of prefixes that should be ignored on index endpoints ; Space separated list of prefixes that should be ignored on index endpoints
; Default: El La Le Las Les Los The ; Default: El La Le Las Les Los The
index_ignored_prefixes = El La Le Las Les Los The index_ignored_prefixes = El La Le Las Les Los The
.. _conf-daemon: .. _conf-daemon:
``[daemon]`` section ``[daemon]`` section
-------------------- --------------------
Configuration for the daemon process that is used to watch for changes in the Configuration for the daemon process that is used to watch for changes in the
library folders and providing the jukebox feature. library folders and providing the jukebox feature.
``socket`` ``socket``
Unix domain socket file (or named pipe on Windows) used to communicate 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 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. page, etc.). Note that using an IP address here isn't supported.
Default: :file:`/tmp/supysonic/supysonic.sock` Default: :file:`/tmp/supysonic/supysonic.sock`
``run_watcher`` ``run_watcher``
Whether or not to start the watcher that will listen for library changes. Whether or not to start the watcher that will listen for library changes.
Default: yes Default: yes
``wait_delay`` ``wait_delay``
Delay (in seconds) before triggering the scanning operation after a change Delay (in seconds) before triggering the scanning operation after a change
have been detected. This prevents running too many scans when multiple have been detected. This prevents running too many scans when multiple
changes are detected for a single file over a short time span. changes are detected for a single file over a short time span.
Default: 5 seconds. Default: 5 seconds.
``jukebox_command`` ``jukebox_command``
Command used by the jukebox mode to play a single file. Command used by the jukebox mode to play a single file.
See the :doc:`jukebox documentation <../jukebox>` for more details. See the :doc:`jukebox documentation <../jukebox>` for more details.
``log_file`` ``log_file``
Rotating file where events generated by the file watcher are logged. Rotating file where events generated by the file watcher are logged.
If left empty, any logging will be sent to stderr. If left empty, any logging will be sent to stderr.
``log_level`` ``log_level``
Defines the minimum severity threshold of messages to be added to Defines the minimum severity threshold of messages to be added to
``log_file``. Possible values are: ``log_file``. Possible values are:
* ``DEBUG`` * ``DEBUG``
* ``INFO`` * ``INFO``
* ``WARNING`` * ``WARNING``
* ``ERROR`` * ``ERROR``
* ``CRITICAL`` * ``CRITICAL``
Defaults to ``WARNING``. Defaults to ``WARNING``.
Sample configuration:: Sample configuration::
[daemon] [daemon]
; Socket file the daemon will listen on for incoming management commands ; Socket file the daemon will listen on for incoming management commands
; Default: /tmp/supysonic/supysonic.sock ; Default: /tmp/supysonic/supysonic.sock
socket = /var/run/supysonic.sock socket = /var/run/supysonic.sock
; Defines if the file watcher should be started. Default: yes ; Defines if the file watcher should be started. Default: yes
run_watcher = yes run_watcher = yes
; Delay in seconds before triggering scanning operation after a change have been ; Delay in seconds before triggering scanning operation after a change have been
; detected. ; detected.
; This prevents running too many scans when multiple changes are detected for a ; This prevents running too many scans when multiple changes are detected for a
; single file over a short time span. Default: 5 ; single file over a short time span. Default: 5
wait_delay = 5 wait_delay = 5
; Command used by the jukebox ; Command used by the jukebox
jukebox_command = mplayer -ss %offset %path jukebox_command = mplayer -ss %offset %path
; Optional rotating log file for the scanner daemon. Logs to stderr if empty ; Optional rotating log file for the scanner daemon. Logs to stderr if empty
log_file = /var/supysonic/supysonic-daemon.log log_file = /var/supysonic/supysonic-daemon.log
log_level = INFO log_level = INFO
``[lastfm]`` section ``[lastfm]`` section
-------------------- --------------------
This section allow defining API keys to enable Last.FM integration in 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. the *now playing* information.
See https://www.last.fm/api to obtain such keys. See https://www.last.fm/api to obtain such keys.
Once keys are set, users have to link their account by visiting their profile 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`` ``api_key``
Last.FM API key Last.FM API key
``secret`` ``secret``
secret key associated to the API key secret key associated to the API key
Sample configuration:: Sample configuration::
[lastfm] [lastfm]
; API and secret key to enable scrobbling. http://www.last.fm/api/accounts ; API and secret key to enable scrobbling. http://www.last.fm/api/accounts
; Defaults: none ; Defaults: none
;api_key = ;api_key =
;secret = ;secret =
.. _conf-transcoding: .. _conf-transcoding:
``[transcoding]`` section ``[transcoding]`` section
------------------------- -------------------------
This section defines command-line programs to be used to convert an audio file 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 to another format or change its bitrate. All configurations in the sample below
have **not** been thoroughly tested. have **not** been thoroughly tested.
For more details, please refer to the For more details, please refer to the
:doc:`transcoding configuration <../transcoding>`. :doc:`transcoding configuration <../transcoding>`.
:: ::
[transcoding] [transcoding]
; Programs used to convert from one format/bitrate to another. Defaults: none ; Programs used to convert from one format/bitrate to another. Defaults: none
transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath - transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath -
transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt - transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt -
decoder_mp3 = mpg123 --quiet -w - %srcpath decoder_mp3 = mpg123 --quiet -w - %srcpath
decoder_ogg = oggdec -o %srcpath decoder_ogg = oggdec -o %srcpath
decoder_flac = flac -d -c -s %srcpath decoder_flac = flac -d -c -s %srcpath
encoder_mp3 = lame --quiet -b %outrate - - encoder_mp3 = lame --quiet -b %outrate - -
encoder_ogg = oggenc2 -q -M %outrate - encoder_ogg = oggenc2 -q -M %outrate -
``[mimetypes]`` section ``[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. the mimetype of some files. This might only be useful in some rare cases.
See the following links for a list of examples: See the following links for a list of examples:
* https://en.wikipedia.org/wiki/Media_type#Common_examples * https://en.wikipedia.org/wiki/Media_type#Common_examples
* https://www.iana.org/assignments/media-types/media-types.xhtml * https://www.iana.org/assignments/media-types/media-types.xhtml
:: ::
[mimetypes] [mimetypes]
; Extension to mimetype mappings in case your system has some trouble guessing ; Extension to mimetype mappings in case your system has some trouble guessing
; Default: none ; Default: none
;mp3 = audio/mpeg ;mp3 = audio/mpeg
;ogg = audio/vorbis ;ogg = audio/vorbis

296
docs/transcoding.rst
View File

@ -1,148 +1,148 @@
Transcoding Transcoding
=========== ===========
Transcoding is the process of converting from one audio format to another. This 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 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 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. 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 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 programs. Supysonic isn't bundled with such programs, and you are left to choose
which one you want to use. which one you want to use.
If you want to use transcoding but your client doesn't allow you to do so, you 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. on the web interface.
Configuration Configuration
------------- -------------
Configuration of transcoders is done on the :ref:`conf-transcoding` of the Configuration of transcoders is done on the :ref:`conf-transcoding` of the
configuration file. configuration file.
Transcoding can be done by one single program which is able to convert from one 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. format directly to another one, or by two programs: a decoder and an encoder.
All these are defined by the following variables: All these are defined by the following variables:
* ``transcoder_EXT_EXT`` * ``transcoder_EXT_EXT``
* ``decoder_EXT`` * ``decoder_EXT``
* ``encoder_EXT`` * ``encoder_EXT``
* ``trancoder`` * ``trancoder``
* ``decoder`` * ``decoder``
* ``encoder`` * ``encoder``
* ``default_transcode_target`` * ``default_transcode_target``
where ``EXT`` is the lowercase file extension of the matching audio format. where ``EXT`` is the lowercase file extension of the matching audio format.
``transcoder``\ s variables have two extensions: the first one is the source ``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, 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 ``decoder``\ s extension is the source extension, and ``encoder``\ s extension
is the extension to convert to. is the extension to convert to.
The value of ``default_transcode_target`` will be used as output format when a 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. 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 Notice that all of them have a version without extension. Those are generic
versions. The programs defined with these variables should be able to 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 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. 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: following order:
#. specific transcoder #. specific transcoder
#. specific decoder / specific encoder #. specific decoder / specific encoder
#. generic decoder / generic encoder (with the possibility to use a generic #. generic decoder / generic encoder (with the possibility to use a generic
decoder with a specific encoder, and vice-versa) decoder with a specific encoder, and vice-versa)
#. generic transcoder #. generic transcoder
All the variables should be set to the command-line used to run the converter All the variables should be set to the command-line used to run the converter
program. The command-lines can include the following fields: program. The command-lines can include the following fields:
``%srcpath`` ``%srcpath``
path to the original file to transcode path to the original file to transcode
``%srcfmt`` ``%srcfmt``
extension of the original file extension of the original file
``%outfmt`` ``%outfmt``
extension of the resulting file extension of the resulting file
``%outrate`` ``%outrate``
bitrate of the resulting file bitrate of the resulting file
``%title`` ``%title``
title of the file to transcode title of the file to transcode
``%album`` ``%album``
album name of the file to transcode album name of the file to transcode
``%artist`` ``%artist``
artist name of the file to transcode artist name of the file to transcode
``%tracknumber`` ``%tracknumber``
track number of the file to transcode track number of the file to transcode
``%totaltracks`` ``%totaltracks``
number of tracks in the album of the file to transcode number of tracks in the album of the file to transcode
``%discnumber`` ``%discnumber``
disc number of the file to transcode disc number of the file to transcode
``%genre`` ``%genre``
genre of the file to transcode (not always available, defaults to "") genre of the file to transcode (not always available, defaults to "")
``%year`` ``%year``
year of the file to transcode (not always available, defaults to "") year of the file to transcode (not always available, defaults to "")
One final note: the original file should be provided as an argument of One final note: the original file should be provided as an argument of
transcoders and decoders. All transcoders, decoders and encoders should write transcoders and decoders. All transcoders, decoders and encoders should write
to standard output, and encoders should read from standard input (decoders to standard output, and encoders should read from standard input (decoders
output being piped into encoders) output being piped into encoders)
Suggested configuration Suggested configuration
^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
Here is an example configuration that you could use. This is provided as-is, Here is an example configuration that you could use. This is provided as-is,
and some configurations haven't been tested. and some configurations haven't been tested.
.. highlight:: ini .. highlight:: ini
Basic configuration:: Basic configuration::
[transcoding] [transcoding]
transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath - transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath -
transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt - transcoder = ffmpeg -i %srcpath -ab %outratek -v 0 -f %outfmt -
decoder_mp3 = mpg123 --quiet -w - %srcpath decoder_mp3 = mpg123 --quiet -w - %srcpath
decoder_ogg = oggdec -o %srcpath decoder_ogg = oggdec -o %srcpath
decoder_flac = flac -d -c -s %srcpath decoder_flac = flac -d -c -s %srcpath
encoder_mp3 = lame --quiet -b %outrate - - encoder_mp3 = lame --quiet -b %outrate - -
encoder_ogg = oggenc2 -Q -M %outrate - encoder_ogg = oggenc2 -Q -M %outrate -
default_transcode_target = mp3 default_transcode_target = mp3
To include track metadata in the transcoded stream:: To include track metadata in the transcoded stream::
[transcoding] [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_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 - 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_mp3 = mpg123 --quiet -w - %srcpath
decoder_ogg = oggdec -o %srcpath decoder_ogg = oggdec -o %srcpath
decoder_flac = flac -d -c -s %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_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 - 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 default_transcode_target = mp3
Enabling transcoding Enabling transcoding
-------------------- --------------------
Once the transcoding configuration has been set, most clients will require the 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 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 interface. Not doing so might prevent some clients to properly request
transcoding. transcoding.
To enable transcoding with the web interface, you should first start using the 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 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 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 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 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 connect to Supysonic and be able to set your preferred streaming format
and bitrate. and bitrate.