From d3bce834743cd3724b133fbfb684e9ffc873deea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Sat, 23 Nov 2019 15:08:18 +0100 Subject: [PATCH] Docs update --- README.md | 5 ++++ config.sample | 3 +++ docs/api.md | 14 +++++------ docs/configuration.md | 6 +++++ docs/jukebox.md | 43 ++++++++++++++++++++++++++++++++ tests/assets/folder/silence.mp3 | Bin 85812 -> 85812 bytes 6 files changed, 64 insertions(+), 7 deletions(-) create mode 100644 docs/jukebox.md diff --git a/README.md b/README.md index af435ee..66aaac7 100644 --- a/README.md +++ b/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_ diff --git a/config.sample b/config.sample index c980c0f..2c61feb 100644 --- a/config.sample +++ b/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 diff --git a/docs/api.md b/docs/api.md index d5ce91d..e81640e 100644 --- a/docs/api.md +++ b/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` | | 📅 | -| `index` | | 📅 | -| `offset` | | 📅 | -| `id` | | 📅 | -| `gain` | | 📅 | +| `action` | | ✔️ | +| `index` | | ✔️ | +| `offset` | | ✔️ | +| `id` | | ✔️ | +| `gain` | | ❌ | ### Internet radio diff --git a/docs/configuration.md b/docs/configuration.md index b1b8196..3e825bd 100644 --- a/docs/configuration.md +++ b/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 diff --git a/docs/jukebox.md b/docs/jukebox.md new file mode 100644 index 0000000..5d3a0b8 --- /dev/null +++ b/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 +``` diff --git a/tests/assets/folder/silence.mp3 b/tests/assets/folder/silence.mp3 index 02c2c8b5f482a68199251bad6352e17d128746fd..807aed4cde3d3643fb122e7931b4e2529b7cd5a5 100644 GIT binary patch delta 147 zcmdlok9EsD)_PADV-^M=ur~qI$mIue9m`XT!3uMdN^^nQ{eyuLqCg2tBO_yD jb0Y&|GYeA_b8}M*19Jw)fQ>QM^3A*Cx9^f?tkMSnsDvUb delta 115 zcmdlok9EsD)+kRGV-^M=ur~