BUILD.md

   1 # Build and Install Shairport Sync
   2 This guide is for a basic installation of Shairport Sync in a recent (2018 onwards) Linux or FreeBSD.
   3
   4 Shairport Sync can be built as an AirPlay 2 player (with [some limitations](AIRPLAY2.md#features-and-limitations)) or as "classic" Shairport Sync – a player for the older, but still supported, AirPlay (aka "AirPlay 1") protocol. Check ["What You Need"](AIRPLAY2.md#what-you-need) for some basic system requirements.
   5
   6 Overall, you'll be building and installing two programs – Shairport Sync itself and [NQPTP](https://github.com/mikebrady/nqptp), a companion app that Shairport Sync uses for AirPlay 2 timing. If you are building classic Shairport Sync, NQPTP is unnecessary and can be omitted.
   7
   8 In the commands below, note the convention that a `#` prompt means you are in superuser mode and a `$` prompt means you are in a regular unprivileged user mode. You can use `sudo` *("SUperuser DO")* to temporarily promote yourself from user to superuser, if permitted. For example, if you want to execute `apt-get update` in superuser mode and you are in user mode, enter `sudo apt-get update`.
   9
  10 ## 1. Prepare
  11 #### Remove Old Copies of Shairport Sync
  12 Before you begin building Shairport Sync, it's best to remove any existing copies of the application, called `shairport-sync`. Use the command `$ which shairport-sync` to find them. For example, if `shairport-sync` has been installed previously, this might happen:
  13 ```
  14 $ which shairport-sync
  15 /usr/local/bin/shairport-sync
  16 ```
  17 Remove it as follows:
  18 ```
  19 # rm /usr/local/bin/shairport-sync
  20 ```
  21 Do this until no more copies of `shairport-sync` are found.
  22 #### Remove Old Service Files
  23 You should also remove any of the following service files that may be present:
  24 * `/etc/systemd/system/shairport-sync.service`
  25 * `/etc/systemd/user/shairport-sync.service`
  26 * `/lib/systemd/system/shairport-sync.service`
  27 * `/lib/systemd/user/shairport-sync.service`
  28 * `/etc/init.d/shairport-sync`
  29
  30 New service files will be installed if necessary at the `# make install` stage.
  31 #### Reboot after Cleaning Up
  32 If you removed any installations of Shairport Sync or any of its service files in the last two steps, you should reboot.
  33
  34 ## 2. Get Tools and Libraries
  35 Okay, now let's get the tools and libraries for building and installing Shairport Sync (and NQPTP).
  36
  37 ### Debian / Raspberry Pi OS / Ubuntu
  38 ```
  39 # apt update
  40 # apt upgrade # this is optional but recommended
  41 # apt install --no-install-recommends build-essential git autoconf automake libtool \
  42     libpopt-dev libconfig-dev libasound2-dev avahi-daemon libavahi-client-dev libssl-dev libsoxr-dev \
  43     libplist-dev libsodium-dev libavutil-dev libavcodec-dev libavformat-dev uuid-dev libgcrypt-dev xxd
  44 ```
  45 If you are building classic Shairport Sync, the list of packages is shorter:
  46 ```
  47 # apt update
  48 # apt upgrade # this is optional but recommended
  49 # apt-get install --no-install-recommends build-essential git autoconf automake libtool \
  50     libpopt-dev libconfig-dev libasound2-dev avahi-daemon libavahi-client-dev libssl-dev libsoxr-dev
  51 ```
  52 ### Fedora
  53 For AirPlay 2 operation, _before you install the libraries_, please ensure the you have [enabled](https://docs.fedoraproject.org/en-US/quick-docs/setup_rpmfusion) RPM Fusion software repositories at least to the "Free" level. If this is not done, FFmpeg libraries will be installed that lack a suitable AAC decoder, preventing Shairport Sync from working in AirPlay 2 mode.
  54 ```
  55 # yum update
  56 # yum install make automake gcc gcc-c++ \
  57     git autoconf automake avahi-devel libconfig-devel openssl-devel popt-devel soxr-devel \
  58     ffmpeg ffmpeg-devel libplist-devel libsodium-devel libgcrypt-devel libuuid-devel vim-common \
  59     alsa-lib-devel
  60 ```
  61 If you are building classic Shairport Sync, the list of packages is shorter:
  62 ```
  63 # yum update
  64 # yum install make automake gcc gcc-c++ \
  65     git autoconf automake avahi-devel libconfig-devel openssl-devel popt-devel soxr-devel \
  66     alsa-lib-devel
  67 ```
  68 ### Arch Linux
  69 After you have installed the libraries, note that you should enable and start the `avahi-daemon` service.
  70 ```
  71 # pacman -Syu
  72 # pacman -Sy git base-devel alsa-lib popt libsoxr avahi libconfig \
  73     libsndfile libsodium ffmpeg vim libplist
  74 ```
  75 If you are building classic Shairport Sync, the list of packages is shorter:
  76 ```
  77 # pacman -Syu
  78 # pacman -Sy git base-devel alsa-lib popt libsoxr avahi libconfig
  79 ```
  80 Enable and start the `avahi-daemon` service.
  81 ```
  82 # systemctl enable avahi-daemon
  83 # systemctl start avahi-daemon
  84 ```
  85 ### FreeBSD
  86 First, update everything:
  87 ```
  88 # freebsd-update fetch
  89 # freebsd-update install
  90 # pkg
  91 # pkg update
  92 ```
  93 Next, install the Avahi subsystem. FYI, `avahi-app` is chosen because it doesn’t require X11. `nss_mdns` is included to allow FreeBSD to resolve mDNS-originated addresses – it's not actually needed by Shairport Sync. Thanks to [reidransom](https://gist.github.com/reidransom/6033227) for this.
  94 ```
  95 # pkg install avahi-app nss_mdns
  96 ```
  97 Add these lines to `/etc/rc.conf`:
  98 ```
  99 dbus_enable="YES"
 100 avahi_daemon_enable="YES"
 101 ```
 102 Next, change the `hosts:` line in `/etc/nsswitch.conf` to
 103 ```
 104 hosts: files dns mdns
 105 ```
 106 Reboot for these changes to take effect.
 107
 108 Next, install the packages that are needed for Shairport Sync and NQPTP:
 109 ```
 110 # pkg install git autotools pkgconf popt libconfig openssl alsa-utils \
 111       libplist libsodium ffmpeg e2fsprogs-libuuid vim
 112 ```
 113 If you are building classic Shairport Sync, the list of packages is shorter:
 114 ```
 115 # pkg install git autotools pkgconf popt libconfig openssl alsa-utils
 116 ```
 117 ## 3. Build
 118 ### NQPTP
 119 Skip this section if you are building classic Shairport Sync – NQPTP is not needed for classic Shairport Sync.
 120
 121 Download, install, enable and start NQPTP from [here](https://github.com/mikebrady/nqptp).
 122
 123 ### Shairport Sync
 124 #### Build and Install
 125 Download Shairport Sync, check out the `development` branch and configure, compile and install it. Before executing the commands, please note the following:
 126
 127 * If building for FreeBSD, replace `--with-systemd` with `--with-os=freebsd --with-freebsd-service`.
 128 * Omit the `--with-airplay-2` from the `./configure` options if you are building classic Shairport Sync.
 129 * If you wish to add extra features, for example an extra audio backend, take a look at the [configuration flags](CONFIGURATION%20FLAGS.md). For this walkthrough, though, please do not remove the `--with-alsa` flag.
 130
 131 ```
 132 $ git clone https://github.com/mikebrady/shairport-sync.git
 133 $ cd shairport-sync
 134 $ git checkout development
 135 $ autoreconf -fi
 136 $ ./configure --sysconfdir=/etc --with-alsa \
 137     --with-soxr --with-avahi --with-ssl=openssl --with-systemd --with-airplay-2
 138 $ make
 139 # make install
 140 ```
 141 By the way, the `autoreconf` step may take quite a while – please be patient!
 142
 143 ## 4. Test
 144 At this point, Shairport Sync should be built and installed but not running. If the user you are logged in as is a member of the unix `audio` group, Shairport Sync should run from the command line:
 145 ```
 146 $ shairport-sync
 147 ```
 148 * Add the `-v` command line option to get some diagnostics.
 149 * Add the `--statistics` option to get some infomation about the audio received.
 150
 151 The AirPlay service should appear on the network and the audio you play should come through to the default ALSA device. (Use `alsamixer` or similar to adjust levels.)
 152
 153 If you have problems, please check the items in Final Notes below, or in the [TROUBLESHOOTING.md](TROUBLESHOOTING.md) guide.
 154
 155 Note: Shairport Sync will run indefinitely -- use Control-C it to stop it.
 156
 157 ## 5. Enable and Start Service
 158 If your system has a Graphical User Interface (GUI) it probably uses PulseAudio or PipeWire for audio services. If that is the case, please review [Working with PulseAudio or PipeWire](https://github.com/mikebrady/shairport-sync/blob/development/ADVANCED%20TOPICS/PulseAudioAndPipeWire.md).
 159 Otherwise, once you are happy that Shairport Sync runs from the command line, you should enable and start the `shairport-sync` service. This will launch Shairport Sync automatically as a background "daemon" service when the system powers up:
 160
 161 ### Linux
 162 ```
 163 # systemctl enable shairport-sync
 164 ```
 165 ### FreeBSD
 166 To make the `shairport-sync` daemon load at startup, add the following line to `/etc/rc.conf`:
 167 ```
 168 shairport_sync_enable="YES"
 169 ```
 170 ## 6. Check
 171 Reboot the machine. The AirPlay service should once again be visible on the network and audio will be sent to the default ALSA device.
 172
 173 ## 7. Final Notes
 174 A number of system settings can affect Shairport Sync. Please review them as follows:
 175
 176 ### Power Saving
 177 If your computer has an `Automatic Suspend` Power Saving Option, you should experiment with disabling it, because your computer has to be available for AirPlay service at all times.
 178 ### WiFi Power Management – Linux
 179 If you are using WiFi, you should turn off WiFi Power Management:
 180 ```
 181 # iwconfig wlan0 power off
 182 ```
 183 or
 184 ```
 185 # iw dev wlan0 set power_save off
 186 ```
 187 The motivation for this is that WiFi Power Management will put the WiFi system in low-power mode when the WiFi system is considered inactive. In this mode, the system may not respond to events initiated from the network, such as AirPlay requests. Hence, WiFi Power Management should be turned off. See [TROUBLESHOOTING.md](https://github.com/mikebrady/shairport-sync/blob/master/TROUBLESHOOTING.md#wifi-adapter-running-in-power-saving--low-power-mode) for more details.
 188
 189 (You can find WiFi device names (e.g. `wlan0`) with `$ ifconfig`.)
 190 ### Firewall
 191 If a firewall is running (some systems, e.g. Fedora, run a firewall by default), ensure it is not blocking ports needed by Shairport Sync and [NQPTP](https://github.com/mikebrady/nqptp/blob/main/README.md#firewall).
 192
 193 ## 8. Connect and enjoy...
 194 ### Add to Home
 195 With AirPlay 2, you can follow the steps in [ADDINGTOHOME.md](ADDINGTOHOME.md) to add your device to the Apple Home system.
 196 ### Wait, there's more...
 197 Instead of using default values for everything, you can use the configuration file to get finer control over the setup, particularly the output device and mixer control -- see [Finish Setting Up](ADVANCED%20TOPICS/InitialConfiguration.md).
 198
 199 Please take a look at [Advanced Topics](ADVANCED%20TOPICS/README.md) for some ideas about what else you can do to enhance the operation of Shairport Sync. For example, you can adjust synchronisation to compensate for delays in your system.