CONFIGURATION FLAGS.md

   1 # Configuration Flags
   2 When the application is being built, these flags determine what capabilities are included in Shairport Sync.
   3 For example, to include DSP capabilities – needed for a loudness filter – you would include the `--with-convolution` flag in the list of
   4 options at the `./configure ...` stage when building the application.
   5
   6 In the following sections, Shairport Sync's compilation configuration options are detailed by catgegory.
   7
   8 ## AirPlay 2 or AirPlay
   9
  10 | Flag |
  11 | ---- |
  12 | `--with-airplay-2` |
  13
  14 AirPlay 2 is the current version of the AirPlay protocol. It offers multi-room operation and integration with the Home application. However, the Shairport Sync implementation is doesn't support iTunes on Windows, and its integration with the Home app and support for remote control is incomplete. Additionally, it requires a somewhat more powerful computer system (Raspberry Pi 2 equivalent or better) and a recent (2018 or later) version of a Debian-like Linux, Alpine Linux or FreeBSD. It has not been tested on other Linux distributions such as OpenWrt. Finally, AirPlay 2 can be lossy – in one mode of operation, audio is encoded in 256kbps AAC.
  15
  16 AirPlay (aka AirPlay 1) is an older version of the AirPlay protocol. If offers multi-room operation to iTunes on macOS or Windows, the Music app on macOS and some third-party computer applications such as [OwnTone](https://owntone.github.io/owntone-server/). It will run on lower powered machines, e.g. the original Raspberry Pi and many embedded devices. This version of AirPlay is lossless – audio is received in 44,100 frames per second 16-bit interleaved stereo ALAC format. It is compatible with a wider range of Linux distributions, back to around 2012. However, support for this version of AirPlay seems to be gradually waning. It does not offer multi-room operation to iOS, iPadOS or AppleTV and is incompatible with HomePod. It is not integrated with the Home app.
  17
  18 To build Shairport Sync for AirPlay 2, include the `--with-airplay-2` option in the `./configure ...` options. You will also have to include extra libraries. Omitting this option will cause Shairport Sync to be built for the older AirPlay protocol.
  19
  20 ## Audio Output
  21 | Flags |
  22 | ----- |
  23 | `--with-alsa` |
  24 | `--with-sndio` |
  25 | `--with-pa` |
  26 | `--with-pw` |
  27 | `--with-ao` |
  28 | `--with-jack` |
  29 | `--with-soundio` |
  30 | `--with-stdout` |
  31 | `--with-pipe` |
  32
  33 Shairport Sync has a number of different "backends" that send audio to an onward destination, e.g. an audio subsystem for output to a Digital to Audio Converter and thence to loudspeakers, or to a pipe for further processing. You can use configuration options to include support for multiple backends at build time and select one of them at runtime.
  34
  35 Here are the audio backend configuration options:
  36
  37 - `--with-alsa` Output to the Advanced Linux Sound Architecture ([ALSA](https://www.alsa-project.org/wiki/Main_Page)) system. This is recommended for highest quality.
  38 - `--with-sndio` Output to the FreeBSD-native [sndio](https://sndio.org) system.
  39 - `--with-pa` Include the PulseAudio audio back end.
  40 - `--with-pw` Output to the [PipeWire](https://pipewire.org) system.
  41 - `--with-ao` Output to the [libao](https://xiph.org/ao/) system. No synchronisation.
  42 - `--with-jack` Output to the [Jack Audio](https://jackaudio.org) system.
  43 - `--with-soundio` Include an optional backend module for audio to be output through the [`soundio`](http://libsound.io) system. No synchronisation.
  44 - `--with-stdout` Include an optional backend module to enable raw audio to be output through standard output (`STDOUT`).
  45 - `--with-pipe` Include an optional backend module to enable raw audio to be output through a unix pipe.
  46
  47 ### PulseAudio and PipeWire
  48 Many recent Linux distributions with a GUI -- "desktop" Linuxes -- use PulseAudio or PipeWire to handle sound. There are two things to consider with these sound servers:
  49 1. They may not always be available: a sound server generally becomes available when a user logs in via the GUI and disappears when the user logs out; it is not available when the system starts up and it is not available to non-GUI users. This means that Shairport Sync can not run as a daemon (see "Daemonisation" below) using a sound server unless the sound server is configured as a system-wide service.
  50 2. The fidelity of the audio is unknown: once audio is delivered to the sound server, it is unknown what happens to it as it is processed through PulseAudio to arrives eventually at the loudspeakers.
  51
  52 It should be noted that both PulseAudio and PipeWire provide a default ALSA pseudo device that enables ALSA-compatible programs to send audio. Shairport Sync can therefore use the ALSA backend with PulseAudio- or PipeWire-based systems.
  53
  54 ## Audio Options
  55 | Flags |
  56 | ----- |
  57 | `--with-soxr` |
  58 | `--with-apple-alac` |
  59 | `--with-convolution` |
  60
  61 - `--with-soxr` Allows Shairport Sync to use [libsoxr](https://sourceforge.net/p/soxr/wiki/Home/)-based resampling for improved interpolation. Recommended.
  62 - `--with-apple-alac` Allows Shairport Sync to use the Apple ALAC Decoder. Requires [`libalac`](https://github.com/mikebrady/alac).
  63 - `--with-convolution` Includes a convolution filter that can be used to apply effects such as frequency and phase correction, and a loudness filter that compensates for the non-linearity of the human auditory system. Requires `libsndfile`.
  64
  65 ## Metadata
  66 | Flags |
  67 | ----- |
  68 | `--with-metadata` |
  69
  70 Metadata such as track name, artist name, album name, cover art and more can be requested from the player and passed to other applications.
  71
  72 - `--with-metadata` Adds support for Shairport Sync to request metadata and to pipe it to a compatible application. See https://github.com/mikebrady/shairport-sync-metadata-reader for a sample metadata reader.
  73
  74 ## Inter Process Communication
  75
  76 | Flags |
  77 | ----- |
  78 | `--with-mqtt-client` |
  79 | `--with-dbus-interface` |
  80 | `--with-dbus-test-client` |
  81 | `--with-mpris-interface` |
  82 | `--with-mpris-test-client` |
  83
  84 Shairport Sync offers three Inter Process Communication (IPC) interfaces: an [MQTT](https://mqtt.org) interface, an [MPRIS](https://specifications.freedesktop.org/mpris-spec/latest/)-like interface and a Shairport Sync specific "native" D-Bus interface loosely based on MPRIS.
  85 The options are as follows:
  86
  87 - `--with-mqtt-client` Includes a client for [MQTT](https://mqtt.org),
  88 - `--with-dbus-interface`  Includes support for the native Shairport Sync D-Bus interface,
  89   - `--with-dbus-test-client` Compiles a D-Bus test client application,
  90 - `--with-mpris-interface` Includes support for a D-Bus interface conforming as far as possible with the MPRIS standard,
  91   - `--with-mpris-test-client` Compiles an MPRIS test client application.
  92
  93 D-Bus and MPRIS commands and properties can be viewed using utilities such as [D-Feet](https://wiki.gnome.org/Apps/DFeet).
  94
  95 ##### MPRIS
  96 The MPRIS interface has to depart somewhat from full MPRIS compatibility due to logical differences between Shairport Sync and a full standalone audio player such as Rhythmbox. Basically there are some things that Shairport Sync itself can not control that a standalone player can control.
  97 A good example is volume control. MPRIS has a read-write `Volume` property, so the volume can be read or set. However, all Shairport Sync can do is *request* the player to change the volume control. This request may or may not be carried out, and it may or may not be done accurately. So, in Shairport Sync's MPRIS interface, `Volume` is a read-only property, and an extra command called `SetVolume` is provided.
  98
  99 ## Other Configuration Options
 100
 101 ### Configuration Files
 102 | Flags |
 103 | ----- |
 104 | `--sysconfdir=<directory>` |
 105
 106 Shairport Sync will look for a configuration file – `shairport-sync.conf` by default – when it starts up. By default, it will look in the directory specified by the `sysconfdir` configuration variable, which defaults to `/usr/local/etc`. This is normal in BSD Unixes, but is unusual in Linux. Hence, for Linux installations, you need to set the `sysconfdir` variable to `/etc` using the configuration setting `--sysconfdir=/etc`.
 107
 108 ### Daemonisation
 109 | Flags |
 110 | ----- |
 111 | `--with-libdaemon` |
 112 | `--with-piddir=<pathname>` |
 113
 114 A [daemon](https://en.wikipedia.org/wiki/Daemon_(computing)) is a computer program that runs as a background process, rather than being under the direct control of an interactive user. Shairport Sync is designed to run as a daemon.
 115 FreeBSD and most recent Linux distributions can run an application as a daemon without special modifications. However, in certain older distributions and in special cases it may be necessary to enable Shairport Sync to daemonise itself. Use the `--with-libdaemon` configuration option:
 116
 117 - `--with-libdaemon` Includes a demonising library needed if you want Shairport Sync to demonise itself with the `-d` option. Not needed for `systemd`-based systems which demonise programs differently.
 118 - `--with-piddir=<pathname>` Specifies a pathname to a directory in which to write the PID file which is created when Shairport Sync daemonises itself and used to locate the deamon process to be killed with the `-k` command line option.
 119
 120 ### Automatic Start
 121 | Flags |
 122 | ----- |
 123 | `--with-systemd` |
 124 | `--with-systemdsystemunitdir=<dir>` |
 125 | `--with-systemv` |
 126 | `--with-freebsd-service` |
 127 | `--with-sygwin-service` |
 128
 129 Daemon programs such as Shairport Sync need to be started automatically, so that the service they provide becomes available without further intervention. Typically this is done using startup scripts. Four options are provided – two for Linux, one for FreeBSD and one for CYGWIN. In Linux, the choice depends on whether [systemd](https://en.wikipedia.org/wiki/Systemd) is used or not. If `systemd` is installed, then the `--with-systemd` option is suggested. If not, the `--with-systemv` option is suggested.
 130
 131 - `--with-systemd` Includes a script to create a Shairport Sync service that can optionally launch automatically at startup on `systemd`-based Linuxes. Default is not to to install. Note: an associated special-purpose option allows you to specify where the `systemd` service file will be placed:
 132   - `--with-systemdsystemunitdir=<dir>` Specifies the directory for `systemd` service files.
 133 - `--with-systemv` Includes a script to create a Shairport Sync service that can optionally launch automatically at startup on System V based Linuxes. Default is not to to install.
 134 - `--with-freebsd-service` Includes a script to create a Shairport Sync service that can optionally launch automatically at startup on FreeBSD. Default is not to to install.
 135 - `--with-cygwin-service` Includes a script to create a Shairport Sync service that can optionally launch automatically at startup on CYGWIN. Default is not to to install.
 136
 137 ### Cryptography
 138 | Flags |
 139 | ----- |
 140 | `--with-ssl=openssl` |
 141 | `--with-ssl=mbedtls` |
 142 | `--with-ssl=polarssl` |
 143
 144 AirPlay 2 operation requires the OpenSSL libraries, so the option `--with-ssl=openssl` is mandatory.
 145
 146 For classic Shairport Sync, the options are as follows:
 147
 148 - `--with-ssl=openssl` Uses the [OpenSSL](https://www.openssl.org) cryptography toolkit. This is mandatory for AirPlay 2 operation.
 149 - `--with-ssl=mbedtls` Uses the [Mbed TLS](https://github.com/Mbed-TLS/mbedtls) cryptography library. Only suitable for classic AirPlay operation – do not include it in an AirPlay 2 configuration.
 150 - `--with-ssl=polarssl` Uses the PolarSSL cryptography library. This is deprecated – PolarSSL has been replaced by Mbed TLS. Only suitable for classic AirPlay operation – do not include it in an AirPlay 2 configuration.
 151
 152 ### Zeroconf/Bonjour
 153 | Flags |
 154 | ----- |
 155 | `--with-avahi` |
 156 | `--with-tinysvcmdns` |
 157 | `--with-external-mdns` |
 158 | `--with-dns_sd` |
 159
 160 AirPlay devices advertise their existence and status using [Zeroconf](http://www.zeroconf.org) (aka [Bonjour](https://en.wikipedia.org/wiki/Bonjour_(software))).
 161
 162 AirPlay 2 operation requires the [Avahi](https://www.avahi.org) libraries, so the option `--with-avahi` is mandatory.
 163
 164 For classic Shairport Sync, the options are as follows:
 165
 166 The Zeroconf-related options are as follows:
 167 - `--with-avahi` Chooses [Avahi](https://www.avahi.org)-based Zeroconf support. This is mandatory for AirPlay 2 operation.
 168 - `--with-tinysvcmdns` Chooses [tinysvcmdns](https://github.com/philippe44/TinySVCmDNS)-based Zeroconf support (deprecated).
 169 - `--with-external-mdns` Supports the use of ['avahi-publish-service'](https://linux.die.net/man/1/avahi-publish-service) or 'mDNSPublish' to advertise the service on Bonjour/ZeroConf.
 170 - `--with-dns_sd` Chooses `dns-sd` Zeroconf support.
 171
 172 ### Miscellaneous
 173 | Flag                 | Significance |
 174 | -------------------- | ---- |
 175 | `--with-os=<OSType>`   | Specifies the Operating System to target: One of `linux` (default), `freebsd`, `openbsd` or `darwin`. |
 176 | `--with-configfiles` | Installs configuration files (including a sample configuration file) during `make install`. |
 177 | `--with-pkg-config`  | Specifies the use of `pkg-config` to find libraries. (Obselete for AirPlay 2. Special purpose use only.) |
 178