diff --git a/changelog.md b/changelog.md index 459e5cc9..83d1e7e7 100644 --- a/changelog.md +++ b/changelog.md @@ -15,7 +15,7 @@ ### General -- Update documentation (Issue #804, PR #945) +- Update documentation (Issue #804, PR #945, PR #951) _Johannes Pohl Fri, 24 Dec 2021 00:13:37 +0200_ diff --git a/debian/changelog b/debian/changelog index c579bb13..7cdcacbd 100644 --- a/debian/changelog +++ b/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 Fri, 24 May 2021 00:13:37 +0200 diff --git a/doc/configuration.md b/doc/configuration.md index d10e299b..7fc6f502 100644 --- a/doc/configuration.md +++ b/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=[&codec=][&sampleformat=][&chunk_ms=] +TYPE://host/path?name=[&codec=][&sampleformat=][&chunk_ms=][&controlscript=] ``` -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: diff --git a/doc/json_rpc_api/stream_plugin.md b/doc/json_rpc_api/stream_plugin.md index 0321b0cb..68439f38 100644 --- a/doc/json_rpc_api/stream_plugin.md +++ b/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) diff --git a/server/etc/snapserver.conf b/server/etc/snapserver.conf index a4a1915b..cfa48cd4 100644 --- a/server/etc/snapserver.conf +++ b/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=[&codec=][&sampleformat=][&chunk_ms=] +# Format: TYPE://host/path?name=[&codec=][&sampleformat=][&chunk_ms=][&controlscript=] # 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: :: #sampleformat = 48000:16:2 # Default transport codec # (flac|ogg|opus|pcm)[:options] -# Type codec:? to get codec specific options +# Start Snapserver with "--stream: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