Document configuration changes for Version 5.0 [skip ci]

This document outlines the significant changes to the `shairport-sync.conf` configuration file for users upgrading to Version 5.0, including new features, settings, and recommendations for optimal use.

diff --git a/CONFIGURATIONFILECHANGES5.md b/CONFIGURATIONFILECHANGES5.md
new file mode 100644 (file)
index 0000000..e80931b
--- /dev/null
+++ b/CONFIGURATIONFILECHANGES5.md
@@ -0,0 +1,154 @@
+# Configuration File Changes in Version 5.0
+
+This document summarizes the important changes to the `shairport-sync.conf` configuration file for normal users upgrading to Version 5.0.
+
+## Multi-Channel Audio Support (NEW!)
+
+Version 5.0 adds support for multi-channel audio (up to 8 channels), including surround sound formats like 5.1 and 7.1.
+
+**New Settings in `general` section (showing defaults):**
+
+* `eight_channel_mode = "on"` - Enable 8-channel (7.1 surround) audio reception.
+* `six_channel_mode = "on"` - Enable 6-channel (5.1 surround) audio reception.  
+* `mixdown = "auto"` - Control how multi-channel audio is mixed down to fewer channels.
+* `output_channel_mapping = "auto"` - Control how audio channels map to your output device.
+
+**What this means for you:** If you have a surround sound system, you can now receive and play multi-channel audio directly. Most users can leave these at their defaults.
+
+## Audio Format and Rate Settings
+
+**Enhanced Interpolation Options:**
+
+The `interpolation` setting now supports a new `"vernier"` mode especially intended for low-power devices:
+* `"auto"` (default, recommended) - Automatically chooses the best method for your processor.
+* `"vernier"` (new!) - Optimized for low-power devices like Raspberry Pi.
+* `"soxr"` - High quality, needs fast processor.
+* `"basic"` - No longer recommended.
+
+**New FFmpeg Decoder:**
+
+The `alac_decoder` setting has changed:
+* Default is now `"ffmpeg"` (if built with FFmpeg support).
+* Old `"hammerton"` and `"apple"` decoders are deprecated for security reasons.
+
+**New Buffer Setting:**
+
+* `audio_decoded_buffer_desired_length_in_seconds = 1.0` - (Advanced.) Controls the internal audio buffer size (AirPlay 2 only).
+
+## Backend-Specific Changes
+
+### ALSA Backend
+
+**New format/rate/channel settings** - You can now specify multiple options and let Shairport Sync auto-select:
+
+* `output_rate = "auto"` - Can be "auto", a single rate like `48000`, or a list like `(44100, 48000)`.
+* `output_format = "auto"` - Can be "auto", a format like `"S32_LE"`, or a list.
+* `output_channels = "auto"` - Can be "auto", a number like `2`, or a list like `(2, 6, 8)`.
+
+**What this means:** Shairport Sync can now automatically switch between different audio formats and rates to match your source, or you can lock it to specific settings.
+
+**Other ALSA changes:**
+
+* `use_mmap_if_available` default changed from `"yes"` to `"no"`.
+* `disable_standby_mode_silence_scan_interval` default changed from `0.004` to `0.030`.
+* New: `disable_standby_mode_default_channels = 2` - Initial channel setting when standby mode is disabled.
+* New: `disable_standby_mode_default_rate` - Initial sample rate when standby mode is disabled.
+
+### PipeWire Backend
+
+**Renamed section:** The `pw` section is now called `pipewire`.
+
+**New settings:**
+* `output_rate = "auto"`.
+* `output_format = "auto"`.  
+* `output_channels = "auto"`.
+
+**What this means:** PipeWire now has the same flexible format/rate/channel options as ALSA.
+
+### PulseAudio Backend
+
+**Renamed section:** The `pa` section is now called `pulseaudio`.
+
+**New settings:**
+* `output_rate = "auto"`.
+* `output_format = "auto"`.
+* `output_channels = "auto"`.
+* `default_channel_layouts = "alsa"` - Use ALSA-compatible channel layouts (default) or PulseAudio's own layouts.
+
+### Other Backends
+
+`sndio`, `pipe`, `stdout`, and `ao` backends have all gained the new `output_rate`, `output_format`, and `output_channels` settings with similar functionality.
+
+## DSP (Convolution and Loudness) Changes
+
+**Convolution Filter:**
+
+Settings have been renamed for clarity:
+* `convolution` → `convolution_enabled`.
+* `convolution_ir_file` → `convolution_ir_files`.
+* `convolution_max_length` → `convolution_max_length_in_seconds`.
+
+**New convolution setting:**
+* `convolution_thread_pool_size = 1` - Number of CPU threads for convolution processing.
+
+**What this means:** 
+- You can now specify multiple impulse response files for different sample rates.
+- The convolution filter works with both stereo and multi-channel audio.
+- You can use multiple CPU cores for faster processing (but core management by the OS may cause power supply noise on some systems).
+
+**Loudness Filter:**
+
+* `loudness` → `loudness_enabled`.
+* The loudness filter now works with stereo and multi-channel audio at both 44.1k and 48k.
+
+## MQTT Changes
+
+**New setting:**
+
+* `publish_retain = "no"` - Set to `"yes"` to make the MQTT broker store the last message for each topic.
+
+**What this means:** When enabled, new MQTT subscribers will immediately receive the most recent values instead of having to wait for the next update.
+
+## Session Control Changes
+
+**Default timeout changed:**
+
+* `session_timeout` default changed from `120` seconds to `60` seconds.
+
+**What this means:** Shairport Sync will now become available again 60 seconds (instead of 120) after a source disappears.
+
+## Removed Settings
+
+The following old settings have been removed:
+
+* `resync_recovery_time_in_seconds` - No longer needed with improved synchronization.
+
+## What Should You Do?
+
+**For most users:** Your existing configuration file will continue to work, though you might have to make some minimal changes.
+
+**Must Do**
+
+* If you use PipeWire or PulseAudio, please change over to the new configuration file settings and backend names immediately.
+
+**Should Do**
+
+* If you are using ALSA plugins, e.g. `plughw:1` to transcode from 44.1k to 48k, consider outputing directly to the underlying hardware device -- `hw:1` in this example -- allowing Shairport Sync to transcode if needed.
+
+**If you want to use new features:**
+
+1. **Multi-channel audio:** Leave `eight_channel_mode` and `six_channel_mode` settings at default, or set them to `"on"` if you have a surround sound system.
+
+2. **Better performance on low-power devices:** Leave the `interpolation` setting at default, or set  it to `"vernier"`.
+
+3. **MQTT retain:** Set `publish_retain = "yes"` if you want MQTT clients to receive the last known state immediately.
+
+4. **Convolution improvements:** Update your `convolution_ir_file` to `convolution_ir_files` and add multiple impulse response files for different sample rates.
+
+5. **Backend-specific formats:** Specify exact rates/formats/channels if you want to lock Shairport Sync to specific settings, or use "auto" to let it adapt.
+
+**To prepare for the future:** Consider updating deprecated setting names to their new equivalents:
+- `convolution` → `convolution_enabled`.
+- `convolution_ir_file` → `convolution_ir_files`.  
+- `convolution_max_length` → `convolution_max_length_in_seconds`.
+- `loudness` → `loudness_enabled`.