shairport-sync/CONFIGURATIONFILECHANGES5.md

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.