Update documentation

changelog.md

@@ -15,7 +15,7 @@
 
 ### General
 
-- Update documentation (Issue #804, PR #945)
+- Update documentation (Issue #804, PR #945, PR #951)
 
 _Johannes Pohl <snapcast@badaix.de>  Fri, 24 Dec 2021 00:13:37 +0200_
 

debian/changelog

@@ -10,7 +10,7 @@ snapcast (0.26.0-1) unstable; urgency=medium
     -Server: systemd.unit starts server after network-online (Issue #950)
 
   * General
-    -Update documentation (Issue #804, PR #945)
+    -Update documentation (Issue #804, PR #945, PR #951)
 
  -- Johannes Pohl <snapcast@badaix.de>  Fri, 24 May 2021 00:13:37 +0200
 

doc/configuration.md

@@ -13,13 +13,30 @@ The following notation is used in this paragraph:
 The general format of an audio source is:
 
 ```sh
-TYPE://host/path?name=<name>[&codec=<codec>][&sampleformat=<sampleformat>][&chunk_ms=<chunk ms>]
+TYPE://host/path?name=<name>[&codec=<codec>][&sampleformat=<sampleformat>][&chunk_ms=<chunk ms>][&controlscript=<control script filename>]
 ```
 
-parameters have the form `key=value`, they are concatenated with an `&` character.
-Parameter `name` is mandatory for all sources, while `codec`, `sampleformat` and `chunk_ms` are optional
-and will override the default `codec`, `sampleformat` or `chunk_ms` settings.
-Non blocking sources support the `dryout_ms` parameter: when no new data is read from the source, send silence to the clients
+Within the `[stream]` section there are some global parameters valid for all `source`s:
+
+- `sampleformat`: Default sample format of the stream source, e.g. `48000:16:2`
+- `codec`: The codec to use to save bandwith, one of:
+  - `flac` [default]: lossless codec, mean codec latency ~26ms
+  - `ogg`: lossy codec
+  - `opus`: lossy low latency codec, only supports 48kHz, if your stream has a different sample rate, automatic resampling will be applied, introducing further latecy
+  - `pcm`: lossless, uncompresssed. No latency.
+- `chunk_ms`: Default source stream read chunk size [ms]. The server will continously read this number of milliseconds from the source into a buffer, before this buffer is passed to the encoder (the `codec` above)
+- `buffer`: Buffer [ms]. The end-to-end latency, from capturing a sample on the server until the sample is played-out on the client
+- `send_to_muted`: `true` or `false`: Send audio to clients that are muted
+
+`source` parameters have the form `key=value`, they are concatenated with an `&` character.
+Supported parameters for all source types:
+
+- `name`: The mandatory source name
+- `codec`: Override the global codec
+- `sampleformat`: Override the global sample format
+- `chunk_ms`: Override the global `chunk_ms`
+- `dryout_ms`: Supported by non-blocking sourced: when no new data is read from the source, send silence to the clients
+- `controlscript`: Script to control the stream source and read and provide meta data, see [stream_plugin.md](json_rpc_api/stream_plugin.md)
 
 Available audio source types are:
 

doc/json_rpc_api/stream_plugin.md

@@ -1,8 +1,16 @@
 
 # Stream plugin
 
-A stream plugin is (this might change in future) an executable binary or script that is started by the server for a specific stream and offers playback control capabilities and provides information about the stream's state, as well as metadata for the currently playing track.
-The Snapcast server communicates via stdin/stdout with the plugin and sends newline delimited JSON-RPC> commands and receives responses and notifications from the plugin, as described below. In upcoming releases shared library plugins might be supported as well.  
+A stream plugin is an executable binary or script that is started by the server for a specific stream and offers playback control capabilities and provides information about the stream's state, as well as metadata for the currently playing track.
+The Snapcast server communicates via stdin/stdout with the plugin and sends [newline delimited](http://ndjson.org/) [JSON-RPC-2.0](https://www.jsonrpc.org/specification) commands and receives responses and notifications from the plugin, as described below. In upcoming releases shared library plugins might be supported as well.  
+A stream is connected to a plugin with the `controlscript` stream source parameter, e.g.
+
+```ini
+[stream]
+source = pipe:///tmp/snapfifo?name=MPD&controlscript=meta_mpd.py
+```
+
+If a relative path is given, Snapserver will search the script in `/usr/share/snapserver/plug-ins`.
 
 A Stream plugin must support and handle the following [requests](#requests), sent by the Snapcast server
 
@@ -165,6 +173,9 @@ Any [json-rpc 2.0 conformant error](https://www.jsonrpc.org/specification#error_
   * `trackNumber`: [string] The track number on the album disc.
   * `url`: [string uri] The location of the media file.
   * `artUrl`: [string uri] The location of an image representing the track or album. Clients should not assume this will continue to exist when the media player stops giving out the URL.
+  * `artData`: [json] Base64 encoded image representing the track or album. if `artUrl` is not specified, Snapserver will decode and cache the image, and will publish the image via `artUrl`.
+    * `data`: [string] Base64 encoded image
+    * `extension`: [string] The image file extension (e.g. "png", "jpg", "svg")
   * `useCount`: [integer] The number of times the track has been played.
   * `userRating`: [float] A user-specified rating. This should be in the range 0.0 to 1.0.
   * `spotifyArtistId`: [string] The [Spotify Artist ID](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids)

server/etc/snapserver.conf

@@ -114,7 +114,7 @@ doc_root = /usr/share/snapserver/snapweb
 # [square brackets]: the whole expression is optional and can be left out
 # [key=value]: if you leave this option out, "value" will be the default for "key"
 #
-# Format: TYPE://host/path?name=<name>[&codec=<codec>][&sampleformat=<sampleformat>][&chunk_ms=<chunk ms>] 
+# Format: TYPE://host/path?name=<name>[&codec=<codec>][&sampleformat=<sampleformat>][&chunk_ms=<chunk ms>][&controlscript=<control script filename>]
 #  parameters have the form "key=value", they are concatenated with an "&" character
 #  parameter "name" is mandatory for all sources, while codec, sampleformat and chunk_ms are optional
 #  and will override the default codec, sampleformat or chunk_ms settings
@@ -136,18 +136,21 @@ doc_root = /usr/share/snapserver/snapweb
 source = pipe:///tmp/snapfifo?name=default
 #source = tcp://127.0.0.1?name=mopidy_tcp
 
-# Default sample format
+# Default sample format: <sample rate>:<bits per sample>:<channels>
 #sampleformat = 48000:16:2
 
 # Default transport codec
 # (flac|ogg|opus|pcm)[:options]
-# Type codec:? to get codec specific options
+# Start Snapserver with "--stream:codec=<codec>:?" to get codec specific options
 #codec = flac
 
-# Default source stream read chunk size [ms]
+# Default source stream read chunk size [ms]. 
+# The server will continously read this number of milliseconds from the source into buffer and pass this buffer to the encoder.
+# The encoded buffer is sent to the clients. Some codecs have a higher latency and will need more data, e.g. Flac will need ~26ms chunks
 #chunk_ms = 20
 
 # Buffer [ms]
+# The end-to-end latency, from capturing a sample on the server until the sample is played-out on the client
 #buffer = 1000
 
 # Send audio to muted clients