Usage doc

README.md

@@ -55,14 +55,6 @@ jukebox mode.
 [docs-setup]: https://supysonic.readthedocs.io/en/latest/setup/index.html
 [docs-daemon]: https://supysonic.readthedocs.io/en/latest/setup/daemon.html
 
-## About client authentication
-
-The Subsonic API provides several authentication methods. One of them, known as
-_token authentication_ was added with API version 1.13.0. As Supysonic currently
-targets API version 1.9.0, the token based method isn't supported. So if your
-client offers you the option, you'll have to disable the token based
-authentication for it to work.
-
 ## Development stuff
 
 For those wishing to collaborate on the project, since Supysonic uses [Flask][]
@@ -78,4 +70,4 @@ And there's also the tests:
     $ python setup.py test
     $ python setup.py test --test-suite tests.with_net
 
-[flask]: https://flask.palletsprojects.com/
+[flask]: https://flask.palletsprojects.com/

docs/index.rst

@@ -23,6 +23,7 @@ __ https://www.last.fm/
    :maxdepth: 2
 
    setup/index
+   usage
    transcoding
    jukebox
    man/index

docs/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR="."
+set BUILDDIR="_build"
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
+

docs/setup/configuration.rst

@@ -239,6 +239,8 @@ Sample configuration::
    log_file = /var/supysonic/supysonic-daemon.log
    log_level = INFO
 
+.. _conf-lastfm:
+
 ``[lastfm]`` section
 --------------------
 

docs/transcoding.rst

@@ -130,6 +130,8 @@ To include track metadata in the transcoded stream::
    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
 
+.. _transcoding-enable:
+
 Enabling transcoding
 --------------------
 

docs/usage.rst

@@ -0,0 +1,145 @@
+Using Supysonic
+===============
+
+Now that everything is :doc:`set up <setup/index>`, there's actually some more
+administrative tasks to perform before really being able to access your music.
+The first one being :ref:`usage-users` and next :ref:`usage-folders`. Then you
+can choose one of the many :ref:`usage-clients` and you're good to go.
+
+.. _usage-users:
+
+Adding users
+------------
+
+One of the first thing you want to do is to create the user(s) that will be
+allowed to access Supysonic. The first user has to be created with the
+:abbr:`CLI (command-line interface)` (:doc:`manpage here <man/supysonic-cli>`),
+if you set them as an admin this new user will then be able to add more users
+through :ref:`usage-web`.
+
+Creating a new user and giving them administrative rights is done with the
+following two commands::
+
+   $ supysonic-cli user add TheUserName
+   $ supysonic-cli user setroles --admin TheUserName
+
+The first command will ask for a password but you can also provide it on the
+command-line::
+
+   $ supysonic-cli user add TheUserName --password ThePassword
+
+If you don't want to set the user as an admin but still want them to be able to
+use the :doc:`jukebox`, you can give them the right like so::
+
+   $ supysonic-cli user setroles --jukebox TheUserName
+
+This last one isn't needed for admins as they have full control over the
+installation.
+
+.. _usage-folders:
+
+Defining and scanning folders
+-----------------------------
+
+Supysonic will be pretty useless if you don't tell it where your music is
+located. This can once again be done with the CLI or the web interface.
+
+Using the CLI::
+
+   $ supysonic-cli folder add SomeFolderName /path/where/the/music/is
+
+The next step is now to scan the folder to find all the media files it holds::
+
+   $ supysonic-cli folder scan SomeFolderName
+
+If :doc:`setup/daemon` is running, this will start scanning in the background,
+otherwise you'll have to wait for the scan to end. This can take some time if
+you have a huge library.
+
+.. _usage-web:
+
+The web interface
+-----------------
+
+Once you have created a user, you can access the web interface at the root URL
+where the application is deployed. As Supysonic is mostly a server and not a
+media player this interface won't provide much. It is mainly used for
+administrative purposes but also provides some features for regular users that
+are only available through this interface.
+
+Once logged, users can click on their username in the top bar to access some
+settings. These include the ability to link their Last.fm__ account provided
+Supysonic was :ref:`configured <conf-lastfm>` with Last.fm API keys. Once linked
+clients will then be able to send *scrobbles*.
+
+.. note::
+
+   In the case of Android clients (this haven't been tested with iOS) this could
+   lead to *scrobbles* being sent twice if the official Last.fm application is
+   also installed on the device.
+
+Another setting also available only through the web interface is the ability to
+define the :ref:`preferred transcoding format <transcoding-enable>`.
+
+Admins got two more options accessible from the top bar: the ability to manage
+users and folders. But these have limitations compared to the CLI: you can't
+grant or revoke the users' jukebox privilege and you can scan folders you
+added only if :doc:`setup/daemon` is running.
+
+__ https://www.last.fm/
+
+.. _usage-clients:
+
+Clients
+-------
+
+You'll need a client to access your music. Whether you want an app for your
+smartphone, something running on your desktop or in a web page you got several
+options here.
+
+One good start would be looking at the list on `Subsonic website`__ but that
+list *could* be a bit out of date and there's also some players that don't
+appear here. Also disregard the trial notice there, Supysonic doesn't include
+such nonsense.
+
+Here are some hand-picked clients:
+
+* in your browser:
+
+  * SubPlayer__ (source__, especially designed to work with Supysonic)
+  * Jamstash__ (source__, whose maintainer contributed to Supysonic)
+
+* on Android:
+
+  * Ultrasonic__ (source__, whose maintainer contributed to Supysonic)
+  * DSub__ (source__)
+
+* on iOS device:
+
+  * you'll have to find one yourself 😉
+
+* for the desktop (none of them were tested)
+
+  * Clementine__
+  * MusicBee__ with a plugin__
+
+.. note::
+
+   The Subsonic API provides several authentication methods. One of them, known
+   as *token authentication* was added with API version 1.13.0. As Supysonic
+   currently targets API version 1.9.0, the token based method isn't supported.
+   So if your client offers you the option, you'll have to disable the token
+   based authentication for it to work.
+
+__ http://www.subsonic.org/pages/apps.jsp
+__ https://subplayer.netlify.app/
+__ https://github.com/peguerosdc/subplayer
+__ https://jamstash.com/
+__ https://github.com/tsquillario/Jamstash
+__ https://play.google.com/store/apps/details?id=org.moire.ultrasonic
+__ https://github.com/ultrasonic/ultrasonic/
+__ https://play.google.com/store/apps/details?id=github.daneren2005.dsub
+__ https://github.com/daneren2005/Subsonic
+__ https://www.clementine-player.org
+__ https://getmusicbee.com
+__ https://getmusicbee.com/addons/plugins/41/subsonic-client/