Docs update

README.md

@@ -14,6 +14,7 @@ Current supported features are:
 * cover arts (as image files in the same folder as music files)
 * starred tracks/albums and ratings
 * [Last.FM][lastfm] scrobbling
+* Jukebox mode
 
 _Supysonic_ currently targets the version 1.9.0 of the _Subsonic_ API. For more
 details, go check the [API implementation status][docs-api].
@@ -221,6 +222,7 @@ _Supysonic_ comes with an optional daemon service that currently provides the
 following features:
 - background scans
 - library changes detection
+- jukebox mode
 
 First of all, the daemon allows running backgrounds scans, meaning you can start
 scans from the CLI and do something else while it's scanning (otherwise the scan
@@ -233,6 +235,9 @@ 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.
 
+Finally, the daemon acts as a backend for the jukebox mode, allowing to play
+audio on the machine running Supysonic.
+
 The daemon is `supysonic-daemon`, it is a non-exiting process. If you want to
 keep it running in background, either use the old `nohup` or `screen` methods,
 or start it as a _systemd_ unit (see the very basic _supysonic-daemon.service_

config.sample

@@ -46,6 +46,9 @@ run_watcher = yes
 ; 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

docs/api.md

@@ -85,7 +85,7 @@ or with version 1.8.0.
 | [`deletePodcastChannel`](#deletepodcastchannel)             | 1.9.0  | ❔ |
 | [`deletePodcastEpisode`](#deletepodcastepisode)             | 1.9.0  | ❔ |
 | [`downloadPodcastEpisode`](#downloadpodcastepisode)         | 1.9.0  | ❔ |
-| [`jukeboxControl`](#jukeboxcontrol)                         |        | 📅 |
+| [`jukeboxControl`](#jukeboxcontrol)                         |        | ✔️ |
 | [`getInternetRadioStations`](#getinternetradiostations)     | 1.9.0  | ❔ |
 | [`createInternetRadioStation`](#createinternetradiostation) | 1.16.0 | ❔ |
 | [`updateInternetRadioStation`](#updateinternetradiostation) | 1.16.0 | ❔ |
@@ -606,15 +606,15 @@ No parameter
 ### Jukebox
 
 #### `jukeboxControl`
-📅
+✔️
 
 | Parameter | Vers. |   |
 |-----------|-------|---|
-| `action`  |       | 📅 |
+| `action`  |       | ✔️ |
-| `index`   |       | 📅 |
+| `index`   |       | ✔️ |
-| `offset`  |       | 📅 |
+| `offset`  |       | ✔️ |
-| `id`      |       | 📅 |
+| `id`      |       | ✔️ |
-| `gain`    |       | 📅 |
+| `gain`    |       | ❌ |
 
 ### Internet radio
 

docs/configuration.md

@@ -146,6 +146,9 @@ changes. Default: yes
 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.
 
@@ -167,6 +170,9 @@ run_watcher = yes
 ; 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

docs/jukebox.md

@@ -0,0 +1,43 @@
+# 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 <username>
+```