Shairport Sync (Finishing) Setup Guide

Setup instructions for configuring shairport-sync on a Raspberry Pi with a hardware DAC, after completing the BUILD.md instructions, in place of the Finish Setting Up guide.

Direct ALSA hardware access to the DAC provides:

• Better audio fidelity (no PulseAudio processing/degradation)
• Hardware volume control (instant response to volume/mute)
• Lower CPU overhead (hardware mixer offloads work)

Prerequisites

1. Identify your hardware DAC device name:

   shairport-sync -h

   Look for the hardware output devices listed (e.g., hw:BossDAC)

2. Find the mixer control name:

   amixer -c BossDAC scontrols

   or

   amixer -c BossDAC

   Look for volume controls with pvolume capability. Common names: Digital, PCM, Master

   For BossDAC specifically: the mixer control is Digital (207 steps, 0-207 range)

Configuration Steps

1. Disable PulseAudio

Since this is a dedicated music player, PulseAudio interferes with direct hardware access and should be disabled:

systemctl --user stop pulseaudio.socket
systemctl --user stop pulseaudio.service
systemctl --user disable pulseaudio.socket
systemctl --user disable pulseaudio.service

Why: PulseAudio blocks direct ALSA access to hardware. Desktop Linuxes use sound servers, but dedicated audio devices don't need them.

2. Configure shairport-sync

Edit /etc/shairport-sync.conf:

general = {
    name = "%H %v";
    output_backend = "alsa";
};

alsa = {
    output_device = "hw:BossDAC";       // Your hardware DAC name (step 1)
    mixer_control_name = "Digital";     // The volume control mixer name (step 2)
    disable_standby_mode = "auto";      // Prevents popping when DAC enters/exits standby
};

Critical gotcha: Even if the alsa section is configured correctly, shairport-sync may default to PulseAudio if output_backend = "alsa" is not explicitly set in the general section.

3. Optional Settings

Consider adding to the general section:

general = {
    name = "%H %v";
    output_backend = "alsa";
    volume_range_db = 60;               // Typical range for useful volume control
    // volume_max_db = 0.0;             // Reduce if DAC outputs too much volume
};

Why:

• volume_range_db: Ensures the full volume slider range is useful (not mostly inaudible at low end)
• volume_max_db: Prevents overloading downstream amplifiers if needed

4. Restart and Verify

sudo systemctl restart shairport-sync

Check logs for errors:

sudo journalctl -u shairport-sync -f

Test hardware directly:

speaker-test -D hw:BossDAC -c 2

Troubleshooting

No audio output

• Error: /home/shairport-sync/.config/pulse → You forgot to set output_backend = "alsa" in general section
• Device busy → PulseAudio is still running, or another process has the device open
• Permission denied → User needs access to audio group

Verify configuration

# Check if PulseAudio is running
ps aux | grep pulse
pactl info

# List ALSA devices
aplay -L

# List mixer controls
amixer -c BossDAC scontrols

References

• Configuration docs: shairport-sync/docs/ADVANCED TOPICS/InitialConfiguration.md
• Best practices: shairport-sync/docs/ADVANCED TOPICS/GetTheBest.md