Notes about how to improve documentation in order to remove install hurdles for new users

[STPKITT]

Hi,
these days I installed Snapcast on a system using pure Pipewire, after having used and loved Snapcast prior on a system using both Pulseaudio and Pipewire and this time I decided to note down how I did everything and separately note down the problems I experienced. Overall installing Snapcast cost me way more time than necessary IMO since the documentation in the readme lacks important basic information. So I'll list the things here which I came across while lacking the background knowledge if everything or at least some of it is dependent on the underlying Linux distribution etc.. Maybe the hurdles I came across could be tackled in the documention in the near future.

1. Zero mention of Pipewire for both snapserver and client which I was especially sad about considering that Snapcast was "all across" the Linux news outlets when version 1.2 of Pipewire was released which added Snapcast Discover aka libpipewire-module-snapcast-discover, whose documentation I also found severly lacking (despite putting a lot of work into making it work I still don't even know if that module is supposed to be for the server- or client-side of Snapcast and Pipewire docs showing to conflicting how-tos in regards to Snapcast)(AFAIK the module is third party instead of by you/@badaix).

2. After configuring snapserver.conf when I tried to launch it port conflicts were shown, but snapserver still went on to seemingly launch fine which made me ignore those conflicts at first. After failing to get anything working in two hours or so (yes I also blame myself for that) I decided to have a look into the port conflcts which made me find out that another snapserver instance was already running! I had never rebooted until then. So when installing the deb-package (K)Ubuntu 24.10 not only automatically set snapserver to autostart on boot via systemd but also immediately started a snapserver instance. I think the latter has to be mentioned in the documentation (ideally with the needed systemd commands systemctl stop/start/retarrt snapserver.service) and/or (rather and) snapserver should cancel launching when it detects port conflicts.

3. I would find it useful if the documentation would mention how or with which method snapserver is resamling. Does it have it's own resampler built it in or does it resort to the resampler the user's Pulseaudio or Pipewire is set to. IMO that matters since depending on that the user could configure the whole setup so that the best resampling method available on the system is used.

4. documentation should list latency implications of the different codecs (or generally bullet points of pros/cons, when the use of which is recommended - configuration.md has some of that, but too scarce). So far for example I found that one of my older devices has much more pops/cracks when streaming flac compared to streaming pcm.

5. Easy fix: the default snapserver.conf has conflicting info about flac and it's recommended chunk sizes. In the commented info txt it says flac needs ~26 ms chunks but the default settings are coded = flac in combination with chunk_ms = 20.

6. snapserver.conf Buffer [ms] setting: the info text IMO doesn't make it clear what the setting is good for. At first thought you'd think the faster a sample is played out on the clients the better so why delay it artificially? Or do I read the explanation wrong and the user it supposed to measure his current latency on this playback devices and set the buffer accordingly. If that it the case how would a user be able to measure the latency?

7. snapserver.conf should mention if "Default sample format" is what the server sends out and therefor possibly resamples to when the incoming source stream is in another sample format. Generally the help texts don't make clear if sampleformat is what snapserver resamples to or if it tells snapserver in which format audio data will be coming in from a source. The user needs to know that so that he knows if the output format of a source does matter or not and configure the source's output optimally.

8. readme.md should link to configuration.md & player_setup.md since so far those documents are very easily overlocked.

9. IMO the naming of the Android client should be cleared up. Here on Github it is named Snapdroid while in F-Droid & Google Play and installed on devices including the app's packagename it's Snapcast. The name Snapcast also does fail to reveal it's function in the Snapcast eco system whether it's a client app, server app, controller app or any combination of those.

I hope my notes will lead to imroved documentation and answer the questions I still had despite already using Snapcast.

Thanks very much for the big effort developing this great project!
Greets!