From: Mike Brady <4265913+mikebrady@users.noreply.github.com> Date: Fri, 13 Feb 2026 15:55:25 +0000 (+0000) Subject: Document configuration changes for Version 5.0 [skip ci] X-Git-Tag: 5.0-rc0~4 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e2c247cd335d72c8d71517ce97bf350fe4321e31;p=thirdparty%2Fshairport-sync.git 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 index 00000000..e80931ba --- /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`.