--- /dev/null
+## Events
+Shairport Sync can run programs just before it starts to play an audio stream and just after it finishes.
+You specify them using the `sessioncontrol` group settings `run_this_before_play_begins` and `run_this_after_play_ends`.
+This is to facilitate situations where something has to be done before and after playing, e.g. switching on an amplifier beforehand
+and switching it off afterwards.
+Set the `wait_for_completion` value to `"yes"` for Shairport Sync to wait until the respective commands have been completed before continuing.
+
+Note that the full path to the programs must be specified, and script files will not be executed unless they are marked as executable
+and have the appropriate shebang `#!/bin/...` as the first line. (This behaviour may be different from other Shairports.)
+
+Shairport Sync can run a program whenever the volume is set or changed. You specify it using the `general` group setting `run_this_when_volume_changes`.
+This is to facilitate situations where something has to be done when the volume changes, e.g. adjust an external mixer value. Set the `wait_for_completion` value to `"yes"` for Shairport Sync to wait until the command has been completed before continuing. Again, please note that the full path to the program must be specified, and script files will not be executed unless they are marked as executable and have the appropriate shebang `#!/bin/...` as the first line.
--- /dev/null
+# Get The Best from Shairport Sync
+Shairport Sync was designed to run best on dedicated stand-alone low-power "headless" Linux/FreeBSD systems with ALSA as the audio system
+and with a decent CD-quality Digital to Analog Converter (DAC).
+
+## CPU Power and Memory
+Computer power and memory requirements are modest -- a Raspberry Pi 2 or better, including the Pi Zero 2 W, is fine.
+Unfortunately, while the original Raspberry Pi and the Pi Zero are powerful enough for AirPlay operation,
+they are not really suitable for AirPlay 2 operation.
+
+## CPU Clock
+For best performance, Shairport Sync requires a stable and accurate system clock.
+This is because the output DAC's output rate is normally determined by the system clock (some high-end USB streamers use their own built-in clocks).
+If the clock drifts, or if its actual frequency is far from its nominal frequency, Shairport Sync will have to do more interpolation,
+which inevitably must degrade the audio fidelity, even if it is very hard to hear.
+Some very old laptops are known to have inaccurate clocks and and some embedded systems can suffer from temperature-related clock drift.
+
+Recent Raspberry Pis seem to have very accurate clocks with low drift.
+
+## Linux
+The best kind of Linux for Shairport Sync is a "bare" Linux.
+Raspberry Pi OS Lite, Debian Minimal Server, Ubuntu Server, Fedora Server and Arch Linux (Minimal Configuration) are good examples.
+
+Shairport Sync also runs on "desktop" Linuxes such as Raspberry Pi OS with desktop, Debian with a desktop environment,
+Ubuntu Desktop and Fedora Workstation.
+Desktop Linuxes are less suitable because they almost always use a sound server like PulseAudio or PipeWire.
+These can interfere with Shairport Sync, which needs direct and exclusive access to the audio hardware.
+
+## DAC
+A good Digital to Analog Converter (DAC) will have a huge influence on the quality of the audio.
+
+Shairport Sync runs at 44,100 frames per second (FPS), each frame consisting of a pair of signed 16 bit linear samples, one for left and one for right.
+Actually, Shairport Sync will take advantage to 24- or 32-bit DACs if available, and will run at 44,100 or 88,200, 176,400 or 352,800 FPS if necessary,
+though there is no advantage to the higher rates. The 44,100 FPS rate was chosen to match the rate of AirPlay.
+
+Good DACs are available at a very wide range of prices, from low-cost USB "Sound Cards" to very high-end HiFi streaming DACs.
+
+In the Raspberry Pi world, many very good low-cost I2S DACs, some with integrated amplifiers, are available. Staying with the Raspberry Pi, the DAC powering the built-in audio jack is not great. It may be good enough for trying out Shairport Sync, but it has a very limited frequency response and can generate very large transients when it starts up. A separate DAC will transform the output quality.
+
+**Note**
+Make sure that the DAC is capable of 44,100 FPS operation -- this is really mandatory.
+Most recent DACs are okay, but some older DACs will only run at 48,000 FPS or multiples of it, and Shairport Sync can not use them.
+## Maximum Output Level
+The `volume_max_db` setting allows you to reduce the maximum level of DAC output to prevent possible overloading of the amplifier or premplifier it feeds.
+## Volume Range
+The volume range is the difference (technically the ratio, expressed in dB) between the highest and lowest level of the volume control. Ideally, this should give the highest volume at the high end and a barely audible sound at the lowest level. Typical volume ranges are 60 dB to 75dB. If the range is much less than this, the difference between high and low volume won't seem large enough to the listener. If the range is much more, much of the low end of the volume control range will be inaudible. (The built-in DAC of the Raspberry Pi has this problem.) Use the `volume_range_db` setting to set the volume range. The built-in attenuator will be used to augment the volume range if necessary.
+## Volume Control
+Audio is sent at full volume in AirPlay and AirPlay 2 with separate information being sent to set the actual volume. This volume information can be used in three ways:
+* It can be used to control a built-in attenuator. This is the default.
+* It can be used to control a mixer built in to the DAC. To use a mixer, set the `mixer_control_name` in the configuration file to the name of the mixer you wish to use.
+* It can be ignored by Shairport Sync. This may be appropriate when you want the volume to be controlled by just one control, typically an audio system's volume control knob or the volume control of a car radio. To make Shairport Sync ignore the volume information, set `ignore_volume_control` to `"yes"`.
+* AirPlay volume changes cause events when an executable -- a program or executable script -- can be called. So, you could get Shairport Sync to ignore volume control information but call an executable to control an external volume control.
+## Other Settings
+* The `disable_standby_mode` setting can be used to prevent the DAC from transitioning between active and standby states, which can sometimes cause a faint popping noise. If activated, Shairport Sync sends frames of silence to keep the DAC busy, preventing it from entering standby mode.
+* The `disable_synchronisation` setting can be used to prevent Shairport Sync from doing any interpolation whatever. Normally, this would lead to a problem when the DAC's buffer either overflowed or underflowed, but some very high-end streamers adjust the rate at which their DACs run to match the exact rate at which audio arrives, thus preventing underflow or overflow.
--- /dev/null
+# Initial Configuration
+Shairport Sync reads settings from a configuration file at `/etc/shairport-sync.conf` (note that in FreeBSD it will be at `/usr/local/etc/shairport-sync.conf`). When you run `$sudo make install`, a sample configuration file is installed or updated at `/etc/shairport-sync.conf.sample` (`/usr/local/etc/shairport-sync.conf.sample` in FreeBSD). This contains all the setting groups and all the settings available, but they all are commented out (comments begin with `//`) so that default values are used. The file contains explanations of the settings, useful hints and suggestions. In addition, if the file doesn't already exist, a default configuration is installed, which should work in almost any system with a sound card.
+
+Settings in the configuration file are grouped. For instance, there is a `general` group within which you can use the `name` tag to set the service name. Suppose you wanted to set the name of the service to `Front Room` and give the service the password `secret`, then you should do the following:
+
+```
+general =
+{
+ name = "Front Room";
+ password = "secret";
+ // ... other general settings
+};
+
+```
+The password setting is only valid for classic Shairport Sync.
+
+(Remember, anything preceded by `//` is a comment and will have no effect on the setting of Shairport Sync.)
+
+**Important:** You should *never* use an important password as the AirPlay password for a Shairport Sync player -- the password is stored in Shairport Sync's configuration file in plain text and is thus completely vulnerable.
+
+No backend is specified here, so it will default to the `alsa` backend if more than one back end has been compiled. To route the output to PulseAudio, add:
+```
+ output_backend = "pa";
+```
+to the `general` group.
+
+The `alsa` group is used to specify properties of the output device. The most obvious setting is the name of the output device which you can set using the `output_device` tag.
+
+The following `alsa` group settings are very important for maximum performance. If your audio device has a mixer that can be use to control the volume, then Shairport Sync can use it to give instant response to volume and mute commands and it can offload some work from the processor.
+* The `mixer_control_name` tag allows you to specify the name of the mixer volume control.
+* The `mixer_device` tag allows you specify where the mixer is. By default, the mixer is on the `output_device`, so you only need to use the `mixer_device` tag if the mixer is elsewhere. This can happen if you specify a *device* rather than a *card* with the `output_device` tag, because normally a mixer is associated with a *card* rather than a device. Suppose you wish to use the output device `5` of card `hw:0` and the mixer volume-control named `PCM`:
+
+```
+alsa =
+{
+ output_device = "hw:0,5";
+ mixer_device = "hw:0";
+ mixer_control_name = "PCM";
+ // ... other alsa settings
+};
+```
+
+The `pa` group is used to specify settings relevant to the PulseAudio backend. You can set the "Application Name" that will appear in the "Sound" control panel.
+
+Note: Shairport Sync can take configuration settings from command line options. This is mainly for backward compatibility, but sometimes still useful. For normal use, it is strongly recommended that you use the configuration file method.
+
+**Raspberry Pi**
+
+The Raspberry Pi Models A and B have a built-in audio DAC that is connected to the device's headphone jack. Apart from a loud click when used for the first time after power-up, it is now quite adequate for casual listening.
+
+To get the benefits of improvements in the Pi's software and firmware, you should update to the Raspian release of October 2018 or later, as a number of improvements have been made to the built-in DAC.
+
+Do the usual update and upgrade:
+```
+# apt update
+# apt upgrade
+```
+To make Shairport Sync output to the built-in audio DAC and use its hardware mixer, in the `alsa` section of the configuration file, set the output device and mixer as follows:
+```
+alsa =
+{
+ output_device = "hw:0"; // the name of the alsa output device. Use "alsamixer" or "aplay" to find out the names of devices, mixers, etc.
+ mixer_control_name = "PCM"; // the name of the mixer to use to adjust output volume. If not specified, volume in adjusted in software.
+ // ... other alsa settings
+```
+(Remember to uncomment the lines by removing the `//` at the start of each.) When these changes have been made, reboot the machine.
+
+A problem with the built-in DAC that it declares itself to have a very large mixer volume control range – all the way from -102.38dB up to +4dB, a range of 106.38 dB. In reality, only the top 60 dB of it is in any way usable. To help get the most from it, consider using the `volume_range_db` setting in the `general` group to instruct Shairport Sync to use the top of the DAC mixer's declared range. For example, if you set the `volume_range_db` figure to 60, the top 60 dB of the range will the used. With this setting on the Raspberry Pi, maximum volume will be +4dB and minimum volume will be -56dB, below which muting will occur.
+
+From a user's point of view, the effect of using this setting is to move the minimum usable volume all the way down to the bottom of the user's volume control, rather than have the minimum usable volume concentrated very close to the maximum volume.
+
+*Command Line Arguments*
+
+As previously mentioned, you can use command line arguments to provide settings to Shairport Sync as before, though newer settings will only be available via the configuration file. For full information, please read the Shairport Sync `man` page, also available at http://htmlpreview.github.io/?https://github.com/mikebrady/shairport-sync/blob/master/man/shairport-sync.html.
+
+Apart from the following options, all command line options can be replaced by settings in the configuration file. Here is a brief description of command line options that are not replicated by settings in the settings file.
+
+* The `-c` option allows you to specify the location of the configuration file.
+* The `-V` option gives you version information about Shairport Sync and then quits.
+* The `-d` option causes Shairport Sync to properly daemonise itself, that is, to run in the background. You may need sudo privileges for this.
+* The `-k` option causes Shairport Sync to kill an existing Shairport Sync daemon. You may need to have sudo privileges for this.
+
+The System V init script at `/etc/init.d/shairport-sync` has a bare minimum :
+`-d`. Basically all it does is put the program in daemon mode. The program will read its settings from the configuration file.
+
+Examples
+--------
+
+Here are some examples of complete configuration files.
+
+```
+general = {
+ name = "Joe's Stereo";
+};
+
+alsa = {
+ output_device = "hw:0";
+};
+```
+
+This gives the service a particular name — "Joe's Stereo" and specifies that audio device `hw:0` be used.
+
+For best results with the `alsa` backend — including getting true mute and instant response to volume control and pause commands — you should access the hardware volume controls. Use `amixer` or `alsamixer` or similar to discover the name of the mixer control to be used as the `mixer_control_name`.
+
+Here is an example for for a Raspberry Pi using its internal soundcard — device hw:0 — that drives the headphone jack:
+```
+general = {
+ name = "Mike's Boombox";
+};
+
+alsa = {
+ output_device = "hw:0";
+ mixer_control_name = "PCM";
+};
+```
+
+Here is an example of driving a Topping TP30 Digital Amplifier, which has an integrated USB DAC and which is connected as audio device `hw:1`:
+```
+general = {
+ name = "Kitchen";
+};
+
+alsa = {
+ output_device = "hw:1";
+ mixer_control_name = "PCM";
+};
+```
+
+For a cheapo "3D Sound" USB card (Stereo output and input only) on a Raspberry Pi:
+```
+general = {
+ name = "Front Room";
+};
+
+alsa = {
+ output_device = "hw:1";
+ mixer_control_name = "Speaker";
+};
+```
+
+For a first generation Griffin iMic on a Raspberry Pi:
+```
+general = {
+ name = "Attic";
+};
+
+alsa = {
+ output_device = "hw:1";
+ mixer_control_name = "PCM";
+};
+```
+
+For an NSLU2, which has no internal sound card, there appears to be a bug in ALSA — you can not specify a device other than "default". Thus:
+
+On an NSLU2, to drive a first generation Griffin iMic:
+```
+general = {
+ name = "Den";
+};
+
+alsa = {
+ mixer_control_name = "PCM";
+};
+```
+
+On an NSLU2, to drive the "3D Sound" USB card:
+```
+general = {
+ name = "TV Room";
+};
+
+alsa = {
+ mixer_control_name = "Speaker";
+};
+```
+
+Finally, here is an example of using the PulseAudio backend:
+```
+general = {
+ name = "Zoe's Computer";
+ output_backend = "pa";
+};
+
+```
+
+
+Latency
+-------
+Latency is the exact time from a sound signal's original timestamp until that signal actually "appears" on the output of the audio output device, usually a Digital to Audio Converter (DAC), irrespective of any internal delays, processing times, etc. in the computer.
+
+Shairport Sync uses latencies supplied by the source, typically either 2 seconds or just over 2.25 seconds. You shouldn't need to change them.
+
+Problems can arise when you are trying to synchronise with speaker systems — typically surround-sound home theatre systems — that have their own inherent delays. You can compensate for an inherent delay using the appropriate backend (typically `alsa`) `audio_backend_latency_offset_in_seconds`. Set this offset (in frames) to compensate for a fixed delay in the audio back end; for example, if the output device delays by 100 ms, set this to -0.1.
+
+Resynchronisation
+-------------
+Shairport Sync actively maintains synchronisation with the source.
+If synchronisation is lost — say due to a busy source or a congested network — Shairport Sync will mute its output and resynchronise. The loss-of-sync threshold is a very conservative 0.050 seconds — i.e. the actual time and the expected time must differ by more than 50 ms to trigger a resynchronisation. Smaller disparities are corrected by insertions or deletions, as described above.
+* You can vary the resync threshold, or turn resync off completely, with the `general` `resync_threshold_in_seconds` setting.
+
+Tolerance
+---------
+Playback synchronisation is allowed to wander — to "drift" — a small amount before attempting to correct it. The default is 0.002 seconds, i.e. 2 ms. The smaller the tolerance, the more likely it is that overcorrection will occur. Overcorrection is when more corrections (insertions and deletions) are made than are strictly necessary to keep the stream in sync. Use the `statistics` setting to monitor correction levels. Corrections should not greatly exceed net corrections.
+* You can vary the tolerance with the `general` `drift_tolerance_in_seconds` setting.
+
--- /dev/null
+# Metadata
+
+Shairport Sync can deliver metadata supplied by the source, such as Album Name, Artist Name, Cover Art, etc.
+through a pipe or UDP socket to a recipient application program — see https://github.com/mikebrady/shairport-sync-metadata-reader for a sample recipient.
+Sources that supply metadata include iTunes and the Music app in macOS and iOS.
+
+
+## Metadata over UDP**
+
+As an alternative to sending metadata to a pipe, the `socket_address` and `socket_port` tags may be set in the metadata group to cause Shairport Sync
+to broadcast UDP packets containing the track metadata.
+
+The advantage of UDP is that packets can be sent to a single listener or, if a multicast address is used, to multiple listeners.
+It also allows metadata to be routed to a different host. However UDP has a maximum packet size of about 65000 bytes; while large enough for most data, Cover Art will often exceed this value. Any metadata exceeding this limit will not be sent over the socket interface. The maximum packet size may be set with the `socket_msglength` tag to any value between 500 and 65000 to control this - lower values may be used to ensure that each UDP packet is sent in a single network frame. The default is 500. Other than this restriction, metadata sent over the socket interface is identical to metadata sent over the pipe interface.
+
+The UDP metadata format is very simple - the first four bytes are the metadata *type*, and the next four bytes are the metadata *code*
+(both are sent in network byte order - see https://github.com/mikebrady/shairport-sync-metadata-reader for a definition of those terms).
+The remaining bytes of the packet, if any, make up the raw value of the metadata.
+
--- /dev/null
+# Advanced Topics
+Here you will find links to some of the more advanced features and things you can do with Shairport Sync.
+* [Finish setting up](InitialConfiguration.md).
+* [Get the best](GetTheBest.md) from Shairport Sync.
+* [Metadata](Metadata.md).
+* [Events](Events.md).
+* [Update Shairport Sync](https://github.com/mikebrady/shairport-sync/blob/development/UPDATING.md) in place.
+* The configuration file -- which contains lots of documentation -- on your system. By default, the sample configuration file is
+placed at `/etc/shairport-sync.conf.sample` (`/usr/local/etc/shairport-sync.conf.sample` on FreeBSD).
+You can also view it online [here](https://github.com/mikebrady/shairport-sync/blob/master/scripts/shairport-sync.conf).
+* [Statistics](Statistics.md).
+* Setting up an [MQTT](https://github.com/mikebrady/shairport-sync/blob/development/MQTT.md) system.
+* Jack Audio.
+* [Digital Signal Processing](https://github.com/mikebrady/shairport-sync/wiki/Digital-Signal-Processing-with-Shairport-Sync).
+* [Build Configuration Flags](https://github.com/mikebrady/shairport-sync/blob/development/CONFIGURATION%20FLAGS.md).
+* [Car Installation](https://github.com/mikebrady/shairport-sync/blob/development/CAR%20INSTALL.md)
+– build an isolated WiFi network containing a Shairport Sync player on a Raspberry Pi. Suitable for a car radio with an `aux` input or for the stereo in that broadband-free holiday cottage.
--- /dev/null
+# Statistics
+
+If you set the `statistics` setting in the `diagnostics` section of the configuration file to `"YES"`, some statistics will be logged at regular intervals. The items logged will depend on the type of stream being processed: AirPlay 1, AirPlay 2 Buffered Audio or AirPlay 2 Realtime Audio. If the `log_verbosity` is set to 1, 2 or 3, additional items will be logged.
+
+From an audio enthusiast's point of view, the most important figure is possibly the `All Sync PPM` figure. This is the total amount of interpolation needed by Shairport Sync to keep the audio stream in sync. The number represents is the ratio of frames added and removed from the audio stream relative to all the frames output in the last interval, expressed in parts per million (PPM). For reference, adding or removing one frame per second into a 44,100 frames per second stream is ± 22.68 PPM. The lower this number number is, the higher the fidelity of the audio signal passed to the output device. On a well sorted system, this figure can be 0.0 for considerable periods, but it can't really be zero forever unless the output device is adapting to the true data rate (some very high-end streamers seem to do so). You may also find that the number might be higher at the start while the system settles down.
+
+The second most important figure is possibly the `Sync Error ms`. This is the average synchronisation error in milliseconds in the last interval. Ideally it should be 0.0. By default, Shairport Sync has a tolerance of a sync error of ± 2.0 milliseconds without triggering interpolation.
+
+Two other interesting measurements of the output rate may be available -- `Output FPS (r)` and `Output FPS (c)`, where `(r)` means "raw" and the `(c)` means "corrected".
+
+The "raw" figure is the rate at which the output device (typically a DAC) accepts data measured relative to the computer's own system clock (specifically the `CLOCK_MONOTONIC_RAW` clock). The accuracy of the number depends on the accuracy of the clock, which will typically be accurate to within anything from 20 to 100 ppm.
+
+The "corrected" figure is the rate at which the output device accepts data relative to the computer's network-time-disciplined clock (specifically the `CLOCK_MONOTONIC` clock). This clock is normally adjusted ("disciplined") to keep time with network time and should be accurate to with a few tens of milliseconds over a _long_ period. So (1) if you could run a play session for a long period -- say a day -- and (2) if network time synchronisation is enabled and (3) if the network connection to the network time service is fast and stable, then you should get an accurate absolute measure of exact frame rate of the output device. If your internet connection is not good, the corrected figure will be very inaccurate indeed.
+
+Here is a brief description of the figures that might be provided.
+##### Sync Error ms
+Average playback synchronisation error in milliseconds in the last interval. By default, Shairport Sync will allow a sync error of ± 2.0 milliseconds without any interpolation. Positive means late, negative means early.
+##### Net Sync PPM
+This is the total amount of interpolation done by Shairport Sync to keep the audio stream in sync. The number represents is the total number of frames added and removed from the audio stream, expressed in parts per million (PPM) in the last interval. For reference, adding or removing one frame per second into a 44,100 frames per second stream is 22.68 ppm.
+##### All Sync PPM
+This is the net amount of interpolation done by Shairport Sync to keep the audio stream in sync. The number represents is the number of frames added plus the number removed from the audio stream, expressed in parts per million (PPM) in the last interval. The magnitude of this should be the same as the `net sync ppm'. If it is much larger it means that Shairport Sync is overcorrecting for sync errors -- try increasing the drift tolerance to reduce it.
+##### Packets
+This is the number of packets of audio frames received since the start of the session. A packet normally contains 352 ± 1 audio frames.
+##### Missing
+This is the number of packets of audio frames that were expected but not received in the last interval. It should be zero, and if not it usually indicates a significant problem with the network. AirPlay 1 and AirPlay 2 Realtime Streams only.
+##### Late
+This is the number of packets of audio frames that were received late -- but still in time to be used -- in the last interval. AirPlay 1 and AirPlay 2 Realtime Streams only.
+##### Too Late
+This is the number of packets of audio frames that were received too late to be used in the last interval. It is possible that these packets were already received, so those frames might not actually be missing when the time comes to play them. AirPlay 1 and AirPlay 2 Realtime Streams only.
+##### Resend Reqs
+This is the number of times Shairport Sync requests the resending of missing frames. Requests can be for one or more frames. AirPlay 1 and AirPlay 2 Realtime Streams only.
+##### Min DAC Queue
+The is the smallest number of frames of audio in the DAC's hardware queue. If it goes too low, the DAC may begin to underrun.
+##### Min Buffers
+The is the smallest number of packets of audio in the queue to be processed in the last interval. It is related to the overall latency in AirPlay 1 and AirPlay 2 Realtime Streams. If it comes close to zero it's often a sign that the network is poor.
+##### Max Buffers
+The is the largest number of packets of audio in the queue to be processed in the last interval.
+##### Min Buffer Size
+The is smallest remaining number of bytes in the Buffered Audio buffer in the last interval. It can legitimately be zero when a track ends or begins. If it reaches zero while a track is playing, it means that audio data is not arriving at Shairport Sync quickly enough and may indicate network problems. AirPlay 2 Buffered Audio streams only.
+##### Nominal FPS
+This is the rate specified in the AirPlay stream itself. AirPlay 1 only.
+##### Received FPS
+This is the rate at which frames are received from the network averaged since the start of the play session. AirPlay 1 only.
+##### Output FPS (r)
+Output rate measured relative to the computer system's clock since the start of the play session. See above for a discussion.
+##### Output FPS (c)
+Output rate measured relative to the network-clock-disciplined computer system's clock since the start of the play session. See above for a discussion.
+##### Source Drift PPM
+This is a measure of the difference between the source clock and Shairport Sync's clock expressed in parts per million. Only valid when 10 or more drift samples have been received. AirPlay 1 only.
+##### Drift Samples
+This is the number drift samples have been accepted for calculating the source drift. AirPlay 1 only.
+#### Example
+The following example is of an AirPlay 2 Buffered Audio Stream from a HomePod mini to a WiFi-connected Raspberry Pi 3 equipped with a Pimoroni "Audio DAC SHIM (Line-Out)" with `log_verbosity` set to `1` after 3 hours and 37 minutes of operation. The audio is from a radio station accessed through Apple Music:
+
+```
+ 5.292055362 "rtsp.c:3112" Connection 1. AP2 Buffered Audio Stream.
+ 1.382815677 "player.c:2650" Connection 1: Playback Started -- AirPlay 2 Buffered.
+ 7.899808955 "player.c:2491" Sync Error ms | Net Sync PPM | All Sync PPM | Min DAC Queue | Min Buffer Size | Output FPS (r) | Output FPS (c)
+...
+ 8.014025361 "player.c:2491" -1.69 2.8 2.8 7341 198k 44100.04 44100.35
+ 7.992082237 "player.c:2491" -1.70 2.8 2.8 7332 188k 44100.04 44100.34
+ 8.015987549 "player.c:2491" -1.68 0.0 0.0 7334 186k 44100.04 44100.35
+ 8.010537393 "player.c:2491" -1.68 2.8 2.8 7335 187k 44100.04 44100.36
+ 7.993940934 "player.c:2491" -1.85 0.0 0.0 7329 198k 44100.04 44100.37
+ 8.015796195 "player.c:2491" -1.87 5.7 5.7 7325 194k 44100.04 44100.37
+ 8.021665934 "player.c:2491" -1.92 5.7 5.7 7329 190k 44100.04 44100.37
+ 7.990409477 "player.c:2491" -1.85 2.8 2.8 7347 201k 44100.04 44100.37
+ 8.001858278 "player.c:2491" -1.96 17.0 17.0 7332 204k 44100.04 44100.37
+ 8.007150986 "player.c:2491" -1.89 2.8 2.8 7327 195k 44100.04 44100.36
+ 7.998612862 "player.c:2491" -1.87 2.8 2.8 7317 199k 44100.04 44100.36
+ 8.020592653 "player.c:2491" -1.89 11.3 11.3 7323 203k 44100.04 44100.35
+ 8.003245674 "player.c:2491" -1.89 8.5 8.5 7325 198k 44100.04 44100.35
+ 7.990874789 "player.c:2491" -1.98 19.8 19.8 7103 197k 44100.04 44100.34
+ 8.010600257 "player.c:2491" -1.85 2.8 2.8 7327 187k 44100.04 44100.33
+ 8.004573122 "player.c:2491" -1.89 5.7 5.7 7327 187k 44100.04 44100.33
+ 8.012853278 "player.c:2491" -1.89 5.7 5.7 7326 190k 44100.04 44100.32
+ 8.005596664 "player.c:2491" -1.95 22.7 22.7 7322 165k 44100.04 44100.31
+ 8.019198695 "player.c:2491" -1.85 5.7 5.7 7333 166k 44100.04 44100.31
+ 7.999363382 "player.c:2491" -1.79 2.8 2.8 7349 153k 44100.04 44100.30
+ 7.990332549 "player.c:2491" -1.87 5.7 5.7 7328 155k 44100.04 44100.29
+ 8.012287445 "player.c:2491" -1.84 2.8 2.8 7352 185k 44100.04 44100.28
+ 7.998929528 "player.c:2491" -1.94 14.2 14.2 7331 171k 44100.04 44100.28
+ 8.008170622 "player.c:2491" -1.88 5.7 5.7 7327 188k 44100.04 44100.27
+ 8.012935257 "player.c:2491" -1.87 19.8 19.8 7270 205k 44100.04 44100.26
+ 8.006337966 "player.c:2491" -1.86 0.0 0.0 7334 199k 44100.04 44100.25
+ 8.004206612 "player.c:2491" -1.76 2.8 2.8 7331 204k 44100.04 44100.25
+ 7.998495257 "player.c:2491" -1.82 2.8 2.8 7329 204k 44100.04 44100.24
+ 8.016859059 "player.c:2491" -1.88 2.8 2.8 7335 201k 44100.04 44100.23
+ 7.993529320 "player.c:2491" -1.92 14.2 14.2 7329 205k 44100.04 44100.22
+ 8.021956820 "player.c:2491" -1.96 11.3 11.3 7322 206k 44100.04 44100.21
+ 8.006401820 "player.c:2491" -1.93 11.3 11.3 7322 199k 44100.04 44100.21
+ 8.001469111 "player.c:2491" -1.89 5.7 5.7 7336 204k 44100.04 44100.20
+ 7.995194320 "player.c:2491" -1.86 5.7 5.7 7330 202k 44100.04 44100.19
+ 8.017805206 "player.c:2491" -1.99 22.7 22.7 7322 201k 44100.04 44100.18
+ 7.995541038 "player.c:2491" -1.95 22.7 22.7 7331 203k 44100.04 44100.18
+ 8.011463643 "player.c:2491" -1.87 0.0 0.0 7331 207k 44100.04 44100.17
+ 7.995941403 "player.c:2491" -1.85 2.8 2.8 7331 206k 44100.04 44100.16
+ 8.013330570 "player.c:2491" -1.71 2.8 2.8 7344 212k 44100.04 44100.15
+ 8.012214580 "player.c:2491" -1.82 0.0 0.0 7333 203k 44100.04 44100.15
+ 7.998585049 "player.c:2491" -1.85 8.5 8.5 7332 207k 44100.04 44100.14
+ 8.023448799 "player.c:2491" -1.86 5.7 5.7 7328 206k 44100.04 44100.13
+ 7.984586612 "player.c:2491" -1.87 8.5 8.5 7277 205k 44100.04 44100.12
+ 8.017339372 "player.c:2491" -1.91 17.0 17.0 7327 207k 44100.04 44100.12
+ 8.007090309 "player.c:2491" -1.94 17.0 17.0 7286 199k 44100.04 44100.11
+ 8.007894164 "player.c:2491" -1.87 2.8 2.8 7334 201k 44100.04 44100.10
+ 7.991787497 "player.c:2491" -1.89 2.8 2.8 7327 194k 44100.04 44100.09
+ 8.019011611 "player.c:2491" -1.94 5.7 5.7 7323 185k 44100.04 44100.09
+ 7.994695362 "player.c:2491" -1.99 14.2 14.2 7321 199k 44100.04 44100.08
+ 8.010284632 "player.c:2491" -1.93 11.3 11.3 7325 191k 44100.04 44100.07
+ 8.011451612 "player.c:2491" -1.87 8.5 8.5 7329 156k 44100.04 44100.09
+ 7.993112549 "player.c:2491" -1.84 2.8 2.8 7330 150k 44100.04 44100.13
+ 8.004971455 "player.c:2491" -1.77 11.3 11.3 7325 157k 44100.04 44100.16
+ 8.010517133 "player.c:2491" -1.85 0.0 0.0 7322 182k 44100.04 44100.19
+ 8.005598851 "player.c:2491" -2.00 39.7 39.7 7207 180k 44100.04 44100.22
+ 8.006777965 "player.c:2491" -1.99 39.7 39.7 7320 183k 44100.04 44100.24
+ 7.115508696 "player.c:1643" Connection 1: Playback Stopped. Total playing time 03:37:20. Output: 44100.04 (raw), 44100.24 (corrected) frames per second.
+```
+For reference, a drift of one second per day is approximately 11.57 ppm. Left uncorrected, even a drift this small between two audio outputs will be audible after a short time.
## What Works
- AirPlay 2 audio for iOS, HomePod mini, AppleTV and Mac players.
- * Two types of audio are received by Shairport Sync – "Realtime" streams of CD quality ALAC (like "classic" AirPlay) and "Buffered Audio" streams of AAC stereo at 44,100 frames per second. The selection of stream type is made by the player. Realtime streams generally have a latency of about two seconds. Buffered Audio streams typically have a latency of half a second or less.
* Audio is synchronised with other AirPlay 2 devices.
- * Shairport Sync offers "classic" AirPlay compatibility for situations where iTunes on macOS or macOS Music plays to multiple speakers and where one of more of them is compatible with AirPlay only.
+ * Two types of audio are received by Shairport Sync – "Realtime" streams of CD quality ALAC (like "classic" AirPlay) and "Buffered Audio" streams of AAC stereo at 44,100 frames per second.
+ * The selection of stream type is made by the player.
+ * Realtime streams generally have a latency of about two seconds. Buffered Audio streams typically have a latency of half a second or less.
+ * In AirPlay 2 mode, Shairport Sync reverts to "classic" AirPlay when iTunes on macOS or macOS Music plays to multiple speakers and one of more of them is compatible with AirPlay only.
- Devices running Shairport Sync in AirPlay 2 mode can be [added](https://github.com/mikebrady/shairport-sync/blob/development/ADDINGTOHOME.md) to the Home app.
- Remote control facilities are not implemented.
## General
-Shairport Sync uses a companion application called [`nqptp`](https://github.com/mikebrady/nqptp) ("Not Quite PTP") for timing and synchronisation in AirPlay 2. `nqptp` must run as `root` and must have exclusive access to ports `319` and `320`.
+Shairport Sync uses a companion application called [NQPTP](https://github.com/mikebrady/nqptp) ("Not Quite PTP")
+for timing and synchronisation in AirPlay 2. NQPTP must run as `root` and must have exclusive access to ports `319` and `320`.
Lossless and High Definition Lossless material is transcoded to AAC before it reaches Shairport Sync.
* Ports 319 and 320 must be free to use (i.e. they must not be in use by another service such as a PTP service) and must not be blocked by a firewall.
* An up-to-date Linux or FreeBSD. This is important, as some of the libraries must be the latest available.
* Shairport Sync will not run on a Mac because NQPTP, on which it relies, needs ports 319 and 320, which are already used by macOS.
-* A version of the [ffmpeg](https://www.ffmpeg.org) library with an AAC decoder capable of decoding Floating Planar -- `fltp` -- material. There is a guide [here](https://github.com/mikebrady/shairport-sync/blob/development/TROUBLESHOOTING.md#aac-decoder-issues-airplay-2-only) to help you find out if your system has it.
-* An audio output, for example an `alsa` device (or `sndio` in FreeBSD). You can use an application called [`sps-alsa-explore`](https://github.com/mikebrady/sps-alsa-explore) to test the suitability of hardware `alsa` audio devices on your device. Other backends continue to work as with "classic" Shairport Sync.
+* A version of the [FFmpeg](https://www.ffmpeg.org) library with an AAC decoder capable of decoding Floating Planar -- `fltp` -- material. There is a guide [here](https://github.com/mikebrady/shairport-sync/blob/development/TROUBLESHOOTING.md#aac-decoder-issues-airplay-2-only) to help you find out if your system has it.
+* An audio output, for example an ALSA device (or `sndio` in FreeBSD). The device must be capable of running at 44,100 frames per second. You can use an `sps-alsa-explore`](https://github.com/mikebrady/sps-alsa-explore) to test the suitability of hardware ALSA audio devices on your device.
+Other backends continue to work as with "classic" Shairport Sync.
## Guides
-* To build Shairport Sync for AirPlay 2 on Linux, please follow the guide at [BUILDFORAP2.md](https://github.com/mikebrady/shairport-sync/blob/development/BUILDFORAP2.md).
-* A guide for building on FreeBSD is available [here](https://github.com/mikebrady/shairport-sync/blob/development/FREEBSD.md).
-
-## Note
-The functionality offered by Shairport Sync is the result of study and analysis of the AirPlay and AirPlay 2 protocols by many people over the years. These protocols have not been officially published, and there is no assurance that Shairport Sync will continue to work with AirPlay in future.
-
-## Acknowledgements
-Huge thanks are due to a number of individuals who made direct and valuable contributions to Shairport Sync:
-1. [ejurgensen](https://github.com/ejurgensen) contributed ideas and code. The `pair_ap` submodule and related code in `rtsp.c` is theirs.
-2. [JD Smith](https://github.com/jdtsmith) contributed ideas, comments and suggestions along with extensive and thorough testing.
-3. [Charles Omer](https://github.com/charlesomer) contributed ideas, comments, bug fixes, documentation and Docker automation (forthcoming).
-4. [ckdo](https://github.com/ckdo) for their pathfinding work on AirPlay 2, especially the HomeKit pairing.
-
-Much of Shairport Sync's AirPlay 2 functionality is based on ideas developed at the [openairplay airplay2-receiver]( https://github.com/openairplay/airplay2-receiver) repository. It is a pleasure to acknowledge the work of the contributors there.
+* A building guide is available at [BUILD.md](https://github.com/mikebrady/shairport-sync/blob/development/BUILD.md).
--- /dev/null
+# Build and Install Shairport Sync
+This guide is for a basic installation of Shairport Sync in a recent (2018 onwards) Linux or FreeBSD.
+
+Shairport Sync can be built as an AirPlay 2 player (with [some limitations](https://github.com/mikebrady/shairport-sync/blob/development/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"](https://github.com/mikebrady/shairport-sync/blob/development/AIRPLAY2.md#what-you-need) for some basic system requirements.
+
+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.
+
+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`.
+
+## 1. Prepare
+#### Remove Old Copies of Shairport Sync
+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:
+```
+$ which shairport-sync
+/usr/local/bin/shairport-sync
+```
+Remove it as follows:
+```
+# rm /usr/local/bin/shairport-sync
+```
+Do this until no more copies of `shairport-sync` are found.
+#### Remove Old Service Files
+You should also remove any of the following service files that may be present:
+* `/etc/systemd/system/shairport-sync.service`
+* `/etc/systemd/user/shairport-sync.service`
+* `/lib/systemd/user/shairport-sync.service`
+* `/etc/init.d/shairport-sync`
+
+New service files will be installed if necessary at the `# make install` stage.
+#### Reboot after Cleaning Up
+If you removed any installations of Shairport Sync or any of its service files in the last two steps, you should reboot.
+
+## 2. Get Tools and Libraries
+Okay, now let's get the tools and libraries for building and installing Shairport Sync (and NQPTP).
+
+### Debian / Raspberry Pi OS / Ubuntu
+```
+# apt update
+# apt upgrade # this is optional but recommended
+# apt install --no-install-recommends build-essential git xmltoman autoconf automake libtool \
+ libpopt-dev libconfig-dev libasound2-dev avahi-daemon libavahi-client-dev libssl-dev libsoxr-dev \
+ libplist-dev libsodium-dev libavutil-dev libavcodec-dev libavformat-dev uuid-dev libgcrypt-dev xxd
+```
+If you are building classic Shairport Sync, the list of packages is shorter:
+```
+# apt update
+# apt upgrade # this is optional but recommended
+# apt-get install --no-install-recommends build-essential git xmltoman autoconf automake libtool \
+ libpopt-dev libconfig-dev libasound2-dev avahi-daemon libavahi-client-dev libssl-dev libsoxr-dev
+```
+### Fedora
+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.
+```
+# yum update
+# yum install make automake gcc gcc-c++ \
+ git xmltoman autoconf automake avahi-devel libconfig-devel openssl-devel popt-devel soxr-devel \
+ ffmpeg ffmpeg-devel libplist-devel libsodium-devel libgcrypt-devel libuuid-devel vim-common \
+ alsa-lib-devel
+```
+If you are building classic Shairport Sync, the list of packages is shorter:
+```
+# yum update
+# yum install make automake gcc gcc-c++ \
+ git xmltoman autoconf automake avahi-devel libconfig-devel openssl-devel popt-devel soxr-devel \
+ alsa-lib-devel
+```
+### Arch Linux
+After you have installed the libraries, note that you should enable and start the `avahi-daemon` service.
+```
+# pacman -Syu
+# pacman -Sy git base-devel alsa-lib popt libsoxr avahi libconfig \
+ libsndfile libsodium ffmpeg vim libplist
+```
+If you are building classic Shairport Sync, the list of packages is shorter:
+```
+# pacman -Syu
+# pacman -Sy git base-devel alsa-lib popt libsoxr avahi libconfig
+```
+Enable and start the `avahi-daemon` service.
+```
+# systemctl enable avahi-daemon
+# systemctl start avahi-daemon
+```
+### FreeBSD
+First, update everything:
+```
+# freebsd-update fetch
+# freebsd-update install
+# pkg
+# pkg update
+```
+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.
+```
+# pkg install avahi-app nss_mdns
+```
+Add these lines to `/etc/rc.conf`:
+```
+dbus_enable="YES"
+avahi_daemon_enable="YES"
+```
+Next, change the `hosts:` line in `/etc/nsswitch.conf` to
+```
+hosts: files dns mdns
+```
+Reboot for these changes to take effect.
+
+Next, install the packages that are needed for Shairport Sync and NQPTP:
+```
+# pkg install git autotools pkgconf popt libconfig openssl alsa-utils \
+ libplist libsodium ffmpeg e2fsprogs-libuuid vim
+```
+If you are building classic Shairport Sync, the list of packages is shorter:
+```
+# pkg install git autotools pkgconf popt libconfig openssl alsa-utils
+```
+## 3. Build
+### NQPTP
+Skip this section if you are building classic Shairport Sync – NQPTP is not needed for classic Shairport Sync.
+
+Download, install, enable and start NQPTP from [here](https://github.com/mikebrady/nqptp).
+
+### Shairport Sync
+#### Build and Install
+Download Shairport Sync, check out the `development` branch and configure, compile and install it. Before executing the commands, please note the following:
+
+* If building for FreeBSD, replace `--with-systemd` with `--with-os=freebsd --with-freebsd-service`.
+* Omit the `--with-airplay-2` from the `./configure` options if you are building classic Shairport Sync.
+* If you wish to add extra features, for example an extra audio backend, take a look at the [configuration flags](https://github.com/mikebrady/shairport-sync/blob/development/CONFIGURATION%20FLAGS.md). For this walkthrough, though, please do not remove the `--with-alsa` flag.
+
+```
+$ git clone https://github.com/mikebrady/shairport-sync.git
+$ cd shairport-sync
+$ git checkout development
+$ autoreconf -fi
+$ ./configure --sysconfdir=/etc --with-alsa \
+ --with-soxr --with-avahi --with-ssl=openssl --with-systemd --with-airplay-2
+$ make
+# make install
+```
+By the way, the `autoreconf` step may take quite a while – please be patient!
+
+## 4. Test
+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:
+```
+$ shairport-sync
+```
+* Add the `-v` command line option to get some diagnostics.
+* Add the `--statistics` option to get some infomation about the audio received.
+
+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.)
+
+If you have problems, please check the items in [Final Notes](final_notes) below, or in the [TROUBLESHOOTING.md](https://github.com/mikebrady/shairport-sync/blob/development/TROUBLESHOOTING.md) guide.
+
+Note: Shairport Sync will run indefinitely -- use Control-C it to stop it.
+
+## 5. Enable and Start Service
+Once you are happy that Shairport Sync runs from the command line, you should Control-C out of it and enable and start the `shairport-sync` service. This will launch Shairport Sync automatically as a background "daemon" service when the system powers up:
+
+### Linux
+```
+# systemctl enable shairport-sync
+```
+### FreeBSD
+To make the `shairport-sync` daemon load at startup, add the following line to `/etc/rc.conf`:
+```
+shairport_sync_enable="YES"
+```
+## 6. Check
+Reboot the machine. The AirPlay service should once again be visible on the network and audio will be sent to the default ALSA device.
+
+## 7. Final Notes
+A number of system settings can affect Shairport Sync. Please review them as follows:
+
+### Power Saving
+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.
+### WiFi Power Management – Linux
+If you are using WiFi, you should turn off WiFi Power Management:
+```
+# iwconfig wlan0 power off
+```
+or
+```
+# iw dev wlan0 set power_save off
+```
+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.
+
+(You can find WiFi device names (e.g. `wlan0`) with `$ ifconfig`.)
+### Firewall
+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).
+
+## 8. Connect and enjoy...
+### Add to Home
+With AirPlay 2, you can follow the steps in [ADDINGTOHOME.md](https://github.com/mikebrady/shairport-sync/blob/development/ADDINGTOHOME.md) to add your device to the Apple Home system.
+### Wait, there's more...
+Shairport Sync has many extra [features](https://github.com/mikebrady/spsdoc/blob/main/README.md#features) and [settings](https://github.com/mikebrady/shairport-sync/blob/development/scripts/shairport-sync.conf). For instance, you can [add an MQTT service](https://github.com/mikebrady/shairport-sync/blob/master/MQTT.md), change the AirPlay service name, adjust for delays in other equipment (many TVs and AVRs introduce slight delays in their audio processing chains) and more. Explore runtime settings in `/etc/shairport-sync.conf` or [here](https://github.com/mikebrady/shairport-sync/blob/development/scripts/shairport-sync.conf). Build configuration flags are [here](https://github.com/mikebrady/shairport-sync/blob/development/CONFIGURATION%20FLAGS.md).
-Build Instructions for AirPlay 1
-==
-Here are simple instructions for building and installing Shairport Sync to provide an AirPlay 1 service on a recent Linux based on Debian, including Ubuntu and Raspberry Pi OS.
+# Build Instructions for AirPlay 1
-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`.
-
-### Configure and Update
-Do the usual update and upgrade:
-```
-# apt-get update
-# apt-get upgrade
-```
-(Separately, on a Raspberry Pi only, if you haven't done so already, consider using the `raspi-config` tool to expand the file system to use the entire card.)
-
-### Turn Off WiFi Power Management
-If you are using WiFi, you should turn off WiFi Power Management:
-```
-# iwconfig wlan0 power off
-```
-WiFi Power Management will put the WiFi system in low-power mode when the WiFi system is considered inactive, and in this mode it 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.)
-
-Reboot the computer.
-
-### Remove Old Copies
-Before you begin building Shairport Sync, it's best to search for and 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:
-```
-$ which shairport-sync
-/usr/local/bin/shairport-sync
-```
-Remove it as follows:
-```
-# rm /usr/local/bin/shairport-sync
-```
-Do this until no more copies of `shairport-sync` are found.
-
-### Remove Old Startup and Service Scripts
-You should also remove the startup script and service definition files `/etc/systemd/system/shairport-sync.service`, `/lib/systemd/system/shairport-sync.service`, `/etc/init.d/shairport-sync`, `/etc/dbus-1/system.d/shairport-sync-dbus.conf` and `/etc/dbus-1/system.d/shairport-sync-mpris.conf` if they exist – new ones will be installed if necessary.
-
-### Reboot after Cleaning Up
-If you removed any installations of Shairport Sync or any of its startup script files in the last two steps, you should reboot.
-
-### Build and Install
-Okay, now let's get the tools and sources for building and installing Shairport Sync.
-
-First, install the packages needed by Shairport Sync:
-```
-# apt-get install build-essential git xmltoman autoconf automake libtool \
- libpopt-dev libconfig-dev libasound2-dev avahi-daemon libavahi-client-dev libssl-dev libsoxr-dev
-```
-Next, download Shairport Sync, check out the `development` branch, configure it, compile and install it:
-```
-$ git clone https://github.com/mikebrady/shairport-sync.git
-$ cd shairport-sync
-$ git checkout development
-$ autoreconf -fi
-$ ./configure --sysconfdir=/etc --with-alsa --with-soxr --with-avahi --with-ssl=openssl --with-systemd
-$ make
-$ sudo make install
-```
-By the way, the `autoreconf` step may take quite a while -- be patient!
-
-### Configure
-
-Now to configure Shairport Sync. In this walkthrough, it will be configured for an `alsa` output device. A list of `alsa` output devices is given at the end of the help information. For example, on a Raspberry Pi, at the end of the output from the command `$ shairport-sync -h`, the following appears:
-
-```
-...
-Settings and options for the audio backend "alsa":
- -d output-device set the output device, default is "default".
- -c mixer-control set the mixer control name, default is to use no mixer.
- -m mixer-device set the mixer device, default is the output device.
- -i mixer-index set the mixer index, default is 0.
- hardware output devices:
- "hw:Headphones"
-```
-Using a program such as `alsamixer`, the name of a mixer (i.e. an attenuator or volume control that could be used to control the output level) can be determined. In this case, the name of the mixer is `Headphone`.
-
-Following this, here are the important options for the Shairport Sync configuration file at `/etc/shairport-sync.conf`. Note that everything is case-sensitive:
-```
-// Sample Configuration File for Shairport Sync on a Raspberry Pi using the built-in audio DAC
-general =
-{
- volume_range_db = 60;
-};
-
-alsa =
-{
- output_device = "hw:Headphones";
- mixer_control_name = "Headphone";
-};
-
-```
-The `volume_range_db = 60;` setting makes Shairport Sync use only the usable part of the Raspberry Pi's built-in audio card mixer's attenuation range. It may not be necessary for other output devices.
-
-The next step is to enable Shairport Sync to start automatically on boot up:
-```
-# systemctl enable shairport-sync
-```
-Finally, either reboot the Pi or start the `shairport-sync` service:
-```
-# systemctl start shairport-sync
-```
-The Shairport Sync AirPlay service should now appear on the network with a service name made from the computer's hostname with the first letter capitalised, e.g. hostname `ubuntu` gives a service name `Ubuntu`. You can change the service name and set a password in the configuration file.
-
-Connect and enjoy...
+This guide has been superseded by the general building guide at [BUILD.md](https://github.com/mikebrady/shairport-sync/blob/development/BUILD.md).
-Building Shairport Sync for AirPlay 2
-==
-* Before building Shairport Sync, you might wish to [check the features and limitations](https://github.com/mikebrady/shairport-sync/blob/development/AIRPLAY2.md#features-and-limitations) of the AirPlay 2 service it provides.
-* Recent versions of Linux / FreeBSD are required for AirPlay 2 operation. At the time of writing, May 2, 2021, everything is on the latest version of the software -- macOS 11.3, iOS 14.5, Raspberry Pi OS 5.10.17-v7l+ (Buster), FreeBSD 12.1, Ubuntu 18.04 -- fully updated. A further requirement is an AAC decoder capable of decoding Planar Floating Point `"fltp"` material. Unfortuately, some prominent Linux distributions -- notably Fedora 36 -- do not include this decoder. See [here](https://github.com/mikebrady/shairport-sync/blob/development/TROUBLESHOOTING.md#aac-decoder-issues-airplay-2-only) for more on this.
-* Be very careful with audio systems capable of very high volume output -- the volume control in this software may not be reliable!
-* Shairport Sync relies on a companion program called [`nqptp`](https://github.com/mikebrady/nqptp) to monitor timing signals. This program uses ports 319 and 320 and replaces any PTP service you have on the computer.
- FYI, most computers do not have a PTP service running. They often use a (totally different) [Network Timing Protocol (NTP)](http://www.ntp.org) service to keep the system clock synchronised with civil time. The POSIX Shared Memory Interface (SMI) Version numbers of `nqptp` and Shairport Sync must match. If they don't, you'll get a message in the logs. It means that one of the programs is out of date with respect to the other.
+# Building Shairport Sync for AirPlay 2
-Instructions
-==
-Build instructions are different from previous versions of Shairport Sync and may change further. For now, leave the settings in the configuration file at default except as noted below.
-
-Overall, you'll be building and installing two programs. The first one is `nqptp` and the second one is Shairport Sync itself. Build and install `nqptp` first.
-
-In the commands below, for a Debian/Ubuntu-like Linux, 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`.
-
-### Turn Off WiFi Power Management
-If you are using WiFi, you should turn off WiFi Power Management:
-```
-# iwconfig wlan0 power off
-```
-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.)
-
-### Update Your System
-Do the usual update and upgrade:
-```
-# apt-get update
-# apt-get upgrade
-```
-Reboot.
-
-### Remove Old Copies
-Before you begin building Shairport Sync, it's best to search for and 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:
-```
-$ which shairport-sync
-/usr/local/bin/shairport-sync
-```
-Remove it as follows:
-```
-# rm /usr/local/bin/shairport-sync
-```
-Do this until no more copies of `shairport-sync` are found.
-
-### Remove Old Service Files
-You should also remove any of the following service files that may be present: `/etc/systemd/system/shairport-sync.service`, `/lib/systemd/system/shairport-sync.service`, `/etc/dbus-1/system.d/shairport-sync-dbus.conf`, `/etc/dbus-1/system.d/shairport-sync-mpris.conf`, and `/etc/init.d/shairport-sync`. New ones will be installed if necessary at the `# make install` stage.
-
-### Reboot after Cleaning Up
-If you removed any installations of Shairport Sync or any of its startup script files in the last two steps, you should reboot.
-
-### Tools and Libraries
-Okay, now let's get the tools and libraries for building and installing Shairport Sync.
-
-First, install the packages needed by Shairport Sync:
-```
-# apt install --no-install-recommends build-essential git xxd xmltoman autoconf automake libtool \
- libpopt-dev libconfig-dev libasound2-dev avahi-daemon libavahi-client-dev libssl-dev libsoxr-dev \
- libplist-dev libsodium-dev libavutil-dev libavcodec-dev libavformat-dev uuid-dev libgcrypt-dev
-```
-
-### nqptp ###
-Download, install, enable and start `nqptp` from [here](https://github.com/mikebrady/nqptp).
-
-### Shairport Sync
-
-#### Please use `git` to clone the repository!
-As you probably know, you can download the repository in two ways: (1) using `git` to clone it -- recommended -- or (2) downloading the repository as a ZIP archive. Please use the `git` method. The reason it that when you use `git`, the build process can incorporate the `git` build information in the version string you get when you execute the command `$ shairport-sync -V`. This will be very useful for identifying the exact build if you are making comments or bug reports. Here is an example:
-```
-Version with git information:
-4.0-dev-138-g2789572-AirPlay2-OpenSSL-Avahi-ALSA-soxr-sysconfdir:/etc
-
-Version without git information:
-4.0-dev-AirPlay2-OpenSSL-Avahi-ALSA-soxr-sysconfdir:/etc
-```
-
-#### Build and Install
-Download Shairport Sync, check out the `development` branch and configure, compile and install it:
-```
-$ git clone https://github.com/mikebrady/shairport-sync.git
-$ cd shairport-sync
-$ git checkout development
-$ autoreconf -fi
-$ ./configure --sysconfdir=/etc --with-alsa \
- --with-soxr --with-avahi --with-ssl=openssl --with-systemd --with-airplay-2
-$ make -j
-# make install
-```
-By the way, the `autoreconf` step may take quite a while -- be patient!
-
-#### Configure
-Now to configure Shairport Sync. In this walkthrough, it is configured for an `alsa` output device.
-
-A list of `alsa` output devices is given at the end of the help information. For example, on a Raspberry Pi, at the end of the output from the command `$ shairport-sync -h`, the following appears:
-
-```
-...
-Settings and options for the audio backend "alsa":
- -d output-device set the output device, default is "default".
- -c mixer-control set the mixer control name, default is to use no mixer.
- -m mixer-device set the mixer device, default is the output device.
- -i mixer-index set the mixer index, default is 0.
- hardware output devices:
- "hw:Headphones"
-```
-Using a program such as `alsamixer`, the name of a mixer (i.e. an attenuator or volume control that could be used to control the output level) can be determined. In this case, the name of the mixer is `Headphone`.
-
-Following this, here are the important options for the Shairport Sync configuration file at `/etc/shairport-sync.conf`. Note that everything is case-sensitive:
-```
-// Sample Configuration File for Shairport Sync on a Raspberry Pi using the built-in audio DAC
-general =
-{
- volume_range_db = 60;
-};
-
-alsa =
-{
- output_device = "hw:Headphones";
- mixer_control_name = "Headphone";
-};
-
-```
-The `volume_range_db = 60;` setting makes Shairport Sync use only the usable part of the Raspberry Pi's built-in audio card mixer's attenuation range. It may not be necessary for other output devices.
-
-#### Automatic Start
-
-To enable Shairport Sync to start automatically on boot up:
-```
-# systemctl enable shairport-sync
-```
-Now, either reboot or start the `shairport-sync` service:
-```
-# systemctl start shairport-sync
-```
-
-#### Running From the Command Line
-
-You may wish to run Shairport Sync from the command line (but remember to ensure it is not already running as a daemon). To enable debug messages and statistics, use the following:
-
-```
-$ shairport-sync -vu --statistics
-```
-The user doesn't need to be privileged, but must be a member of the `audio` group for access to the `alsa` subsystem.
-
-### Using Shairport Sync
-
-The Shairport Sync AirPlay service should appear on the network with a service name made from the machine's hostname with the first letter capitalised, e.g. hostname `ubuntu` gives a service name `Ubuntu`. You can change the service name in the configuration file.
-
-Connect and enjoy...
-
-### Adding to Home
-
-Follow the steps in [ADDINGTOHOME.md](https://github.com/mikebrady/shairport-sync/blob/development/ADDINGTOHOME.md) to add your Shairport Sync device to the Apple Home system.
-
-### Update Your Mac!
-
-Many AirPlay 2 bugs have been fixed in recent versions of macOS, so it is strongly recommended that you update your Mac.
+This guide has been superseded by the general building guide at [BUILD.md](https://github.com/mikebrady/shairport-sync/blob/development/BUILD.md).
# Configuration Flags
-When the application is being built, the *compilation configuration options* determine what capabilities are included in Shairport Sync.
+When the application is being built, these flags determine what capabilities are included in Shairport Sync.
For example, to include DSP capabilities – needed for a loudness filter – you would include the `--with-convolution` flag in the list of
options at the `./configure ...` stage when building the application.
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.
-## Audio Output Backends
+## Audio Output
| Flags |
| ----- |
| `--with-alsa` |
- `--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.
- `--with-sndio` Output to the FreeBSD-native [sndio](https://sndio.org) system.
-- `--with-pa` Include the PulseAudio audio back end. This is recommended only if your Linux installation already has [PulseAudio](https://www.freedesktop.org/wiki/Software/PulseAudio/) installed. Although ALSA would be better, it requires direct and exclusive access to to a real (hardware) soundcard, and this is often impractical if PulseAudio is installed.
+- `--with-pa` Include the PulseAudio audio back end.
- `--with-pw` Output to the [PipeWire](https://pipewire.org) system.
- `--with-ao` Output to the [libao](https://xiph.org/ao/) system. No synchronisation.
- `--with-jack` Output to the [Jack Audio](https://jackaudio.org) system.
- `--with-stdout` Include an optional backend module to enable raw audio to be output through standard output (`STDOUT`).
- `--with-pipe` Include an optional backend module to enable raw audio to be output through a unix pipe.
-### PulseAudio
-Many recent Linux distributions that have a GUI – including Ubuntu, Debian and others – use PulseAudio to handle sound. In such cases, it is inadvisable to attempt to disable or remove PulseAudio. Therefore, if your system uses PulseAudio, you should build Shairport Sync with the PulseAudio backend. However, there are two issues with the use of PulseAudio.
-* First, the PulseAudio sound system may not always be available. In its normal configuration, PulseAudio only becomes available when a user logs in via the GUI or a terminal window and disappears when the user logs out; it is not available in time when the system starts up. This means that Shairport Sync can not be installed as a daemon (see "Daemonisation" below) in a PulseAudio-based system unless PulseAudio is [configured](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/SystemWide) as a system-wide daemon.
-* Second, the fidelity of the audio is unknown: once audio is delivered to PulseAudio, it is unknown what happens to it as it is processed through PulseAudio to arrives evenutally at the loudspeakers.
-
-In summary, Shairport Sync will work with PulseAudio, which is installed in many desktop Linuxes. PulseAudio normally runs in the *user mode* but can be configured to run in *system mode*, though this is [not recommended](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/WhatIsWrongWithSystemWide).
-
-#### Checking for PulseAudio
-You can check to see if PulseAudio is running by opening a Terminal window and entering the command `$ pactl info`. Here is an example of what you'll get if PulseAudio is installed, though the exact details may vary:
-```
-$ pactl info
-Server String: /run/user/1000/pulse/native
-Library Protocol Version: 35
-Server Protocol Version: 35
-Is Local: yes
-Client Index: 8
-Tile Size: 65472
-User Name: mike
-Host Name: ubuntu2204
-Server Name: pulseaudio
-Server Version: 15.99.1
-Default Sample Specification: s16le 2ch 44100Hz
-Default Channel Map: front-left,front-right
-Default Sink: alsa_output.pci-0000_02_02.0.analog-stereo
-Default Source: alsa_input.pci-0000_02_02.0.analog-stereo
-Cookie: 5a9f:56ee
-```
-If PulseAudio in not installed, you'll get something like this:
-```
-$ pactl info
--bash: pactl: command not found
-$
-```
-If your system does not use PulseAudio, it is likely that it uses the Advanced Linux Sound Architecture (ALSA), so you should build Shairport Sync with the ALSA backend. By the way, many systems with PulseAudio also have ALSA (in fact, PulseAudio is effectively a client of ALSA); in those cases you should choose the PulseAudio backend because PulseAudio will require exclusive access to the ALSA device being used as the output device.
+### PulseAudio and PipeWire
+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:
+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.
+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.
+
+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.
## Audio Options
| Flags |
| `--with-os=<OSType>` | Specifies the Operating System to target: One of `linux` (default), `freebsd`, `openbsd` or `darwin`. |
| `--with-configfiles` | Installs configuration files (including a sample configuration file) during `make install`. |
| `--with-pkg-config` | Specifies the use of `pkg-config` to find libraries. (Obselete for AirPlay 2. Special purpose use only.) |
+
# Fedora Installation Guide
-This guide is for a recent version of Fedora Linux (Fedora 36) outputting to the PipeWire sound system through a built-in ALSA adapter.
-Shairport Sync can be built as an AirPlay 2 player (with [some limitations](https://github.com/mikebrady/shairport-sync/blob/development/AIRPLAY2.md#features-and-limitations)) or as "classic" Shairport Sync – a player for the older, but still supported, AirPlay (aka "AirPlay 1") protocol.
-
-Fedora uses PipeWire for audio management [since Fedora 34](https://fedoramagazine.org/pipewire-the-new-audio-and-video-daemon-in-fedora-linux-34/). An [adapter](https://wiki.archlinux.org/title/PipeWire#ALSA_clients) is included to route audio from ALSA-compatible sources into the PipeWire infrastructure.
-
-It is recommended that Shairport Sync is built with the standard ALSA backend (`--with-alsa`).
-
-Shairport Sync also offers a PipeWire (`--with-pw`) backend – still new and still under development. The PulseAudio (`--with-pa`) backend may also be used thanks to a PulseAudio-to-PipeWire adapter.
-
-**Note:** The use of PipeWire, even indirectly, means that Shairport Sync can not be installed as a system service (aka a system daemon). The user must log in through the Fedora GUI for the audio received by Shairport Sync to be routed to the system audio output, e.g. the onboard speakers.
-
-Overall, you'll be building and installing two programs. The first one is NQPTP, a companion app that Shairport Sync uses for AirPlay 2 timing, and the second one is Shairport Sync itself. Build and install NQPTP first. If you are building classic Shairport Sync, NQPTP is unnecessary and can be omitted.
-
-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 `yum update` in superuser mode and you are in user mode, enter `sudo yum update`.
-
-## Turn Off WiFi Power Management
-If you are using WiFi, you should turn off WiFi Power Management, e.g. if the WiFi device name is `wlp5s0b1`:
-
-```
-# iw dev wlp5s0b1 set power_save off
-```
-The reason 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.)
-
-## Enable RPM Fusion Software Repositories (AirPlay 2 Only)
-For AirPlay 2, it is important to [enable](https://docs.fedoraproject.org/en-US/quick-docs/setup_rpmfusion) the RPM Fusion software repositories, at least to the "Free" level. This is so that [ffmpeg](https://ffmpeg.org) libraries will be installed that include a suitable AAC decoder.
-
-## Update Everything
-```
-# yum update
-```
-## Remove Old Stuff
-### Remove Old Copies of Shairport Sync
-Before you begin building Shairport Sync, it's best to search for and 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:
-```
-$ which shairport-sync
-/usr/local/bin/shairport-sync
-```
-Remove it as follows:
-```
-# rm /usr/local/bin/shairport-sync
-```
-Do this until no more copies of `shairport-sync` are found.
-
-### Remove Old Service Files
-You should also remove any of the following service files that may be present: `/etc/systemd/system/shairport-sync.service`, `/lib/systemd/system/shairport-sync.service`, `/etc/dbus-1/system.d/shairport-sync-dbus.conf`, `/etc/dbus-1/system.d/shairport-sync-mpris.conf`, and `/etc/init.d/shairport-sync`. New ones will be installed if necessary.
-
-### Reboot after Cleaning Up
-If you removed any installations of Shairport Sync or any of its startup script files in the last two steps, you should reboot.
-
-
-## Install Toolchain and Libraries
-Okay, now let's get the tools and libraries for building and installing Shairport Sync (and NQPTP).
-
-```
-# yum install make automake gcc gcc-c++
-# yum install autoconf automake avahi-devel libconfig-devel openssl-devel popt-devel soxr-devel
-# yum install alsa-lib-devel # for the ALSA back end -- used in this build
-```
-(To build the PipeWire backend, install the `pipewire-devel` library; for the PulseAudio backend, you'll need the `pulseaudio-libs-devel` library.)
-
-For AirPlay 2 operation, extra libraries must be installed. Before taking this step, once again 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.
-
-Install the extra libraries with the following command:
-```
-# yum install ffmpeg ffmpeg-devel libplist-devel libsodium-devel libgcrypt-devel libuuid-devel vim-common
-```
-
-## Build
-### NQPTP
-Skip this section if you are building Classic Shairport Sync – NQPTP is not used by Classic Shairport Sync.
-
-Download, install, enable and start NQPTP from [here](https://github.com/mikebrady/nqptp). By the way, Fedora has a firewall running by default, so make sure you enable UDP traffic to and from ports 319 and 320, as noted in the NQPTP guide.
-
-### Shairport Sync
-
-#### Please use `git` to clone the repository!
-As you probably know, you can download the repository in two ways: (1) using `git` to clone it – recommended – or (2) downloading the repository as a ZIP archive. Please use the `git` method. The reason it that when you use `git`, the build process can incorporate the `git` build information in the version string you get when you execute the command `$ shairport-sync -V`. This will be very useful for identifying the exact build if you are making comments or bug reports. Here is an example:
-```
-Version with git information:
-4.1-dev-389-gf317161a-AirPlay2-OpenSSL-Avahi-ALSA-soxr-sysconfdir:/etc
-
-Version without git information:
-4.1-dev-AirPlay2-OpenSSL-Avahi-ALSA-soxr-sysconfdir:/etc
-```
-
-#### Build and Install
-Download Shairport Sync, check out the `development` branch and configure, compile and install it.
-
-* Omit `--with-airplay-2` from the `./configure` options to build Classic Shairport Sync.
-
-```
-$ git clone https://github.com/mikebrady/shairport-sync.git
-$ cd shairport-sync
-$ git checkout development
-$ autoreconf -fi
-$ ./configure --sysconfdir=/etc --with-alsa \
- --with-soxr --with-avahi --with-ssl=openssl --with-systemd --with-airplay-2
-```
-If you get errors during the `./configure` step, check again that you have installed the toolchain and libraries correctly.
-```
-$ make -j
-# make install
-```
-By the way, the `autoreconf` step may take quite a while – please be patient!
-
-## Configuration
-By default when you start Shairport Sync, it will play to the default output device, which is just what is needed here – the default ALSA device routes audio into Fedora's PipeWire infrastructure. You can configure many Shairport Sync settings in the configuration file, installed during the `# make install` step at `/etc/shairport-sync.conf` along with a sample at `/etc/shairport-sync.conf.sample`.
-
-### Automatic Start
-
-To run automatically after user login, Shairport Sync can be set up as a user service.
-
-Placeholder: please refer to the discussion in [Issue #1260](https://github.com/mikebrady/shairport-sync/issues/1260).
-
-### Running From the Command Line
-
-You may wish to run Shairport Sync from the command line. To enable debug messages and statistics, use the following:
-
-```
-$ shairport-sync -v --statistics
-```
-
-### Adding to Home
-
-If you have built it for AirPlay 2, you can follow the steps in [ADDINGTOHOME.md](https://github.com/mikebrady/shairport-sync/blob/development/ADDINGTOHOME.md) to add your Shairport Sync device to the Apple Home system.
-
-## Update Your Mac!
-
-Many AirPlay 2 bugs have been fixed in recent versions of macOS, so it is strongly recommended that you update your Mac.
-
-## Using Shairport Sync
-
-The Shairport Sync AirPlay service should appear on the network with a service name made from the machine's hostname with the first letter capitalised, e.g. hostname `fedora` gives a service name `Fedora`. You can change the service name in the configuration file.
-
-Connect and enjoy...
+For the present, this guide has been superseded by the general building guide at [BUILD.md](https://github.com/mikebrady/shairport-sync/blob/development/BUILD.md).
-Shairport Sync on FreeBSD
-----
-This guide, for a recent FreeBSD system, is to build Shairport Sync to output to the [`sndio`](https://sndio.org) and/or the [ALSA](https://www.alsa-project.org/wiki/Main_Page) sound systems.
+# Shairport Sync on FreeBSD
-The `sndio` back end is based on the work of [Tobias Kortkamp](https://github.com/t6).
-
-ALSA is not "native" to FreeBSD, but it has been ported to some architectures.
-
-Shairport Sync can be built as an AirPlay 2 player (with [some limitations](https://github.com/mikebrady/shairport-sync/blob/development/AIRPLAY2.md#features-and-limitations)) or as "Classic" Shairport Sync – a player for the older, but still supported, AirPlay (aka "AirPlay 1") protocol.
-
-Overall, you'll be building and installing two programs. The first one is NQPTP, a companion app that Shairport Sync uses for AirPlay 2 timing, and the second one is Shairport Sync itself. Build and install NQPTP first. If you are building Classic Shairport Sync, NQPTP is unnecessary and can be omitted.
-
-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 `freebsd-update fetch` in superuser mode and you are in user mode, enter `sudo freebsd-update fetch`.
-
-General
-----
-This build was done on a default build of `freebsd 12.3-RELEASE-p5`.
-
-First, update everything:
-```
-# freebsd-update fetch
-# freebsd-update install
-```
-Next, install the `pkg` package manager and update its lists:
-
-```
-# pkg
-# pkg update
-```
-
-Subsystems
-----
-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.
-
-```
-# pkg install avahi-app nss_mdns
-```
-Add these lines to `/etc/rc.conf`:
-```
-dbus_enable="YES"
-avahi_daemon_enable="YES"
-```
-Next, change the `hosts:` line in `/etc/nsswitch.conf` to
-```
-hosts: files dns mdns
-```
-Reboot for these changes to take effect.
-
-Building
-----
-
-Install the packages that are needed for Shairport Sync to be downloaded and built:
-```
-# pkg install git autotools pkgconf popt libconfig openssl sndio
-```
-* Add `alsa-utils` if you wish to use ALSA.
-* Omit `sndio` if you don't intend to use the `sndio` subsystem.
-* Add `libplist libsodium ffmpeg e2fsprogs-libuuid vim` if you are building for AirPlay 2.
-
-At this point, if you intend to build Shairport Sync for AirPlay 2, you should build and install `NQPTP`, a companion application that provides AirPlay 2 timing support for Shairport Sync. You'll find the software itself and an installation guide [here](https://github.com/mikebrady/nqptp/blob/main/README.md). Once you have built, installed and enabled NQPTP, you can proceed with building Shairport Sync.
-
-Now, download Shairport Sync from GitHub:
-```
-$ git clone https://github.com/mikebrady/shairport-sync.git
-$ cd shairport-sync
-```
-If you are building the AirPlay 2 version of Shairport Sync, for the present you should checkout the `development` version:
-```
-$ git checkout development
-```
-Next, configure the build and compile the `shairport-sync` application:
-```
-$ autoreconf -i -f
-$ ./configure --with-avahi --with-ssl=openssl --with-sndio --with-os=freebsd --with-freebsd-service
-$ make
-```
-* Add `--with-airplay-2` if you wish to build the AirPlay 2 version of Shairport Sync.
-* Add `--with-alsa` if you wish to include the ALSA back end.
-* Omit the `--with-sndio` if you don't want the `sndio` back end.
-* Omit the `--with-freebsd-service` if you don't want to install a FreeBSD startup script, runtime folder and user and group -- see below for more details.
-
-Installation
-----
-
-Enter the superuser mode and do a `make install`:
-
-```
-$ su
-# make install
-```
-
-With the `./configure` options shown above, this will install the `shairport-sync` program along with a sample configuration file at `/usr/local/etc/shairport-sync.conf`. A service startup script will also be installed to launch Shairport Sync as a daemon. In addition, a `shairport-sync` user and group will be added to enable `shairport-sync` to run with a low level of privilege (a primitive form of extra security).
-
-Finally, edit `/usr/local/etc/shairport-sync.conf` to customise your installation, e.g. service name, etc. To make the `shairport-sync` daemon load at startup, add the following line to `/etc/rc.conf`:
-
-```
-shairport_sync_enable="YES"
-```
-You can launch the service as superuser, or simply reboot the machine.
-
-Using the `sndio` backend
-----
-
-The `sndio` back end does not yet have a hardware volume control facility. You should set the volume to maximum before use, using, for example, the `mixer` command described below.
-
-Setting Overall Volume
-----
-The `mixer` command can be used for setting the output device's volume settings. You may have to experiment to figure out which settings are appropriate.
-
-```
-$ mixer vol 100 # sets overall volume
-```
-If you've installed `alsa-utils`, then `alsamixer` and friends will also be available.
+This guide has been superseded by the general building guide at [BUILD.md](https://github.com/mikebrady/shairport-sync/blob/development/BUILD.md).
-More Information
-----------
-Shairport Sync offers *full audio synchronisation*, a feature of AirPlay that previous implementations do not provide. Full audio synchronisation means that audio is played on the output device at exactly the time specified by the audio source. To accomplish this, Shairport Sync needs access to audio systems – such as `alsa` on Linux and `sndio` on FreeBSD – that provide very accurate timing information about output devices. Shairport Sync must have direct access to the output device used, which must be a real sound card capable of working with 44,100, 88,200 or 176,400 samples per second, interleaved PCM stereo of 8, 16, 24 or 32 bits. The default is 44,100 samples per second / 16 bits (you'll get a message in the logfile if there's a problem).
-
-Alternatively, Shairport Sync works well with PulseAudio, a widely used sound server found on many desktop Linuxes. While the timing information is not as accurate as that of `alsa` or `sndio`, it is often impractical to remove or disable PulseAudio. In that case, the `pa` backend can be used.
-
-For other use cases, Shairport Sync can provide synchronised audio output to a unix pipe or to standard output, or to audio systems that do not provide timing information. This could perhaps be described as *partial audio synchronisation*, where synchronised audio is provided by Shairport Sync, but what happens to it in the subsequent processing chain, before it reaches the listener's ear, is outside the control of Shairport Sync.
-
-For more about the motivation behind Shairport Sync, please see the wiki at https://github.com/mikebrady/shairport-sync/wiki.
-
-Synchronisation, Latency, "Stuffing"
----------
-The AirPlay protocol uses an agreed *latency* – the time difference, or delay, between the time represented by a sound sample's `timestamp` and the time it is actually played by the audio output device, typically a Digital to Audio Converter (DAC). The latency to be used is specified by the audio source when it negotiates with Shairport Sync.
-
-As mentioned previously, Shairport Sync implements full audio synchronisation when used with `alsa`, `sndio` or PulseAudio systems. This is done by monitoring the timestamps present in data coming from the audio source and the timing information from the audio system, e.g. `alsa`. To maintain the latency required for exact synchronisation, if the output device is running slow relative to the source, Shairport Sync will delete frames of audio to allow the device to keep up. If the output device is running fast, Shairport Sync will insert frames to keep time. The number of frames inserted or deleted is so small as to be almost inaudible on normal audio material. Frames are inserted or deleted as necessary at pseudorandom intervals. Alternatively, with `libsoxr` support, Shairport Sync can resample the audio feed to ensure the output device can keep up. This is less obtrusive than insertion and deletion but requires a good deal of processing power — most embedded devices probably can't support it. The process of insertion/deletion or resampling is rather inelegantly called “stuffing”.
-
-Stuffing is not done for partial audio synchronisation – the audio samples are simply presented at exactly the right time to the next stage in the processing chain.
-
-Timestamps are referenced relative to the source computer's clock – the `source clock`, but timing must be done relative to the clock of the computer running Shairport Sync – the `local clock`. So, another thing Shairport Sync has to do is to synchronize the source clock and the local clock, and it does this usually to within a fraction of a millisecond, using either the PTP or NTP synchronisation protocols.
-
-What else?
---------------
-* Better Volume Control — Shairport Sync offers finer control at very top and very bottom of the volume range. See http://tangentsoft.net/audio/atten.html for a good discussion of audio "attenuators", upon which volume control in Shairport Sync is modelled. See also the diagram of the volume transfer function in the documents folder. In addition, Shairport Sync can offer an extended volume control range on devices with a restricted range.
-* Hardware Mute — Shairport Sync can mute properly if the hardware supports it.
-* Support for the Apple ALAC decoder.
-* Output bit depths of 8, 16, 24 and 32 bits, rather than the standard 16 bits.
-* Output frame rates of 44,100, 88,200, 176,000 or 352,000 frames per second.
-* Fast Response — With hardware volume control, response is instantaneous; otherwise the response time is 0.20 seconds with `alsa`, 0.35 seconds with `sndio`.
-* Metadata — Shairport Sync can deliver metadata supplied by the source, such as Album Name, Artist Name, Cover Art, etc. through a pipe or UDP socket to a recipient application program — see https://github.com/mikebrady/shairport-sync-metadata-reader for a sample recipient. Sources that supply metadata include iTunes and the Music app in macOS and iOS.
-* Compiles on Linux and FreeBSD.
-* Outputs to [`alsa`](https://www.alsa-project.org/wiki/Main_Page), [`sndio`](http://www.sndio.org), [PulseAudio](https://www.freedesktop.org/wiki/Software/PulseAudio/), [JACK](http://jackaudio.org), to a unix pipe or to `STDOUT`. It also has limited support for [libao](https://xiph.org/ao/) and for [`soundio`](http://libsound.io).
-* An [MPRIS](https://specifications.freedesktop.org/mpris-spec/2.2/) interface, partially complete and very functional, including access to metadata and artwork, and some limited remote control.
-* An interface to [MQTT](https://en.wikipedia.org/wiki/MQTT), an often-used protocol in home automation projects.
-* A native D-Bus interface, including access to metadata and artwork, some limited remote control and some system settings.
-
-Heritage
--------
-Shairport Sync is a substantial rewrite of the fantastic work done in Shairport 1.0 by James Laird and others — please see https://github.com/abrasive/shairport/blob/master/README.md#contributors-to-version-1x for a list of the contributors to Shairport 1.x and Shairport 0.x. From a "heritage" point of view, Shairport Sync is a fork of Shairport 1.0.
-
-
-Configuring Shairport Sync
---------
-To get the best from Shairport Sync, you’ll need to (a) give Shairport Sync a service name by which it will be seen in iTunes etc. and (b) specify the backend you wish to use - `alsa` for the ALSA backend, or `pa` for the PulseAudio back end, etc. If only one backend is included at compilation, or if the backend is ALSA, there is no need to explicitly specify the backend.
-
-For the ALSA backend you may need to (c) specify the output device to use and (d) specify the name of the mixer volume control to use to control the output level. To get values for (c) and (d) you might need to explore the ALSA output devices with a program like `alsamixer` or similar.
-
-Shairport Sync reads settings from a configuration file at `/etc/shairport-sync.conf` (note that in FreeBSD it will be at `/usr/local/etc/shairport-sync.conf`). When you run `$sudo make install`, a sample configuration file is installed or updated at `/etc/shairport-sync.conf.sample` (`/usr/local/etc/shairport-sync.conf.sample` in FreeBSD). This contains all the setting groups and all the settings available, but they all are commented out (comments begin with `//`) so that default values are used. The file contains explanations of the settings, useful hints and suggestions. In addition, if the file doesn't already exist, a default configuration is installed, which should work in almost any system with a sound card.
-
-Settings in the configuration file are grouped. For instance, there is a `general` group within which you can use the `name` tag to set the service name. Suppose you wanted to set the name of the service to `Front Room` asd give the service the password `secret`, then you should do the following:
-
-```
-general =
-{
- name = "Front Room";
- password = "secret";
- // ... other general settings
-};
-```
-(Remember, anything preceded by `//` is a comment and will have no effect on the setting of Shairport Sync.)
-
-**Important:** You should *never* use an important password as the AirPlay password for a Shairport Sync player -- the password is stored in Shairport Sync's configuration file in plain text and is thus completely vulnerable.
-
-No backend is specified here, so it will default to the `alsa` backend if more than one back end has been compiled. To route the output to PulseAudio, add:
-
-```
- output_backend = "pa";
-```
-to the `general` group.
-
-The `alsa` group is used to specify properties of the output device. The most obvious setting is the name of the output device which you can set using the `output_device` tag.
-
-The following `alsa` group settings are very important for maximum performance. If your audio device has a mixer that can be use to control the volume, then Shairport Sync can use it to give instant response to volume and mute commands and it can offload some work from the processor.
-* The `mixer_control_name` tag allows you to specify the name of the mixer volume control.
-* The `mixer_device` tag allows you specify where the mixer is. By default, the mixer is on the `output_device`, so you only need to use the `mixer_device` tag if the mixer is elsewhere. This can happen if you specify a *device* rather than a *card* with the `output_device` tag, because normally a mixer is associated with a *card* rather than a device. Suppose you wish to use the output device `5` of card `hw:0` and the mixer volume-control named `PCM`:
-
-```
-alsa =
-{
- output_device = "hw:0,5";
- mixer_device = "hw:0";
- mixer_control_name = "PCM";
- // ... other alsa settings
-};
-```
-
-The `pa` group is used to specify settings relevant to the PulseAudio backend. You can set the "Application Name" that will appear in the "Sound" control panel.
-
-Shairport Sync can run programs just before it starts to play an audio stream and just after it finishes. You specify them using the `sessioncontrol` group settings `run_this_before_play_begins` and `run_this_after_play_ends`. This is to facilitate situations where something has to be done before and after playing, e.g. switching on an amplifier beforehand and switching it off afterwards. Set the `wait_for_completion` value to `"yes"` for Shairport Sync to wait until the respective commands have been completed before continuing.
-
-Note that the full path to the programs must be specified, and script files will not be executed unless they are marked as executable and have the appropriate shebang `#!/bin/...` as the first line. (This behaviour may be different from other Shairports.)
-
-Shairport Sync can run a program whenever the volume is set or changed. You specify it using the `general` group setting `run_this_when_volume_changes`. This is to facilitate situations where something has to be done when the volume changes, e.g. adjust an external mixer value. Set the `wait_for_completion` value to `"yes"` for Shairport Sync to wait until the command has been completed before continuing. Again, please note that the full path to the program must be specified, and script files will not be executed unless they are marked as executable and have the appropriate shebang `#!/bin/...` as the first line.
-
-Note: Shairport Sync can take configuration settings from command line options. This is mainly for backward compatibility, but sometimes still useful. For normal use, it is strongly recommended that you use the configuration file method.
-
-**Raspberry Pi**
-
-Many Raspberry Pi Models have a built-in audio DAC that is connected to the device's headphone jack. Apart from a loud click when used for the first time after power-up, it is now quite adequate for casual listening.
-
-To make Shairport Sync output to the built-in audio DAC and use its hardware mixer, in the `alsa` section of the configuration file, set the output device and mixer as follows:
-```
-alsa =
-{
- output_device = "hw:0"; // the name of the alsa output device. Use "alsamixer" or "aplay" to find out the names of devices, mixers, etc.
- mixer_control_name = "Headphone"; // the name of the mixer to use to adjust output volume. If not specified, volume in adjusted in software.
- // ... other alsa settings
-```
-(Remember to uncomment the lines by removing the `//` at the start of each.) When these changes have been made, reboot the machine.
-
-A problem with the built-in DAC that it declares itself to have a very large mixer volume control range – all the way from -102.38dB up to +4dB, a range of 106.38 dB. In reality, only the top 60 dB of it is in any way usable. To help get the most from it, consider using the `volume_range_db` setting in the `general` group to instruct Shairport Sync to use the top of the DAC mixer's declared range. For example, if you set the `volume_range_db` figure to 60, the top 60 dB of the range will the used. With this setting on the Raspberry Pi, maximum volume will be +4dB and minimum volume will be -56dB, below which muting will occur.
-
-From a user's point of view, the effect of using this setting is to move the minimum usable volume all the way down to the bottom of the user's volume control, rather than have the minimum usable volume concentrated very close to the maximum volume.
-
-Examples
---------
-
-Here are some examples of complete configuration files.
-
-```
-general = {
- name = "Joe's Stereo";
-};
-
-alsa = {
- output_device = "hw:0";
-};
-```
-
-This gives the service a particular name — "Joe's Stereo" and specifies that audio device hw:0 be used.
-
-For best results with the `alsa` backend — including getting true mute and instant response to volume control and pause commands — you should access the hardware volume controls. Use `amixer` or `alsamixer` or similar to discover the name of the mixer control to be used as the `mixer_control_name`.
-
-Here is an example for for a Raspberry Pi using its internal soundcard — device hw:0 — that drives the headphone jack:
-```
-general = {
- name = "Mike's Boombox";
-};
-
-alsa = {
- output_device = "hw:0";
- mixer_control_name = "Headphone";
-};
-```
-
-Here is an example of driving a Topping TP30 Digital Amplifier, which has an integrated USB DAC and which is connected as audio device `hw:1`:
-```
-general = {
- name = "Kitchen";
-};
-
-alsa = {
- output_device = "hw:1";
- mixer_control_name = "PCM";
-};
-```
-
-For a cheapo "3D Sound" USB card (Stereo output and input only) on a Raspberry Pi:
-```
-general = {
- name = "Front Room";
-};
-
-alsa = {
- output_device = "hw:1";
- mixer_control_name = "Speaker";
-};
-```
-
-
-Finally, here is an example of using the PulseAudio backend:
-```
-general = {
- name = "Zoe's Computer";
- output_backend = "pa";
-};
-
-```
-
-
-Metadata
---------
-
-Shairport Sync can deliver metadata supplied by the source, such as Album Name, Artist Name, Cover Art, etc. through a pipe or UDP socket to a recipient application program — see https://github.com/mikebrady/shairport-sync-metadata-reader for a sample recipient. Sources that supply metadata include iTunes and the Music app in macOS and iOS.
-
-**Metadata broadcasting over UDP**
-
-As an alternative to sending metadata to a pipe, the `socket_address` and `socket_port` tags may be set in the metadata group to cause Shairport Sync to broadcast UDP packets containing the track metadata.
-
-The advantage of UDP is that packets can be sent to a single listener or, if a multicast address is used, to multiple listeners. It also allows metadata to be routed to a different host. However UDP has a maximum packet size of about 65000 bytes; while large enough for most data, Cover Art will often exceed this value. Any metadata exceeding this limit will not be sent over the socket interface. The maximum packet size may be set with the `socket_msglength` tag to any value between 500 and 65000 to control this - lower values may be used to ensure that each UDP packet is sent in a single network frame. The default is 500. Other than this restriction, metadata sent over the socket interface is identical to metadata sent over the pipe interface.
-
-The UDP metadata format is very simple - the first four bytes are the metadata *type*, and the next four bytes are the metadata *code* (both are sent in network byte order - see https://github.com/mikebrady/shairport-sync-metadata-reader for a definition of those terms). The remaining bytes of the packet, if any, make up the raw value of the metadata.
-
-Latency
--------
-Latency is the exact time from a sound signal's original timestamp until that signal actually "appears" on the output of the audio output device, usually a Digital to Audio Converter (DAC), irrespective of any internal delays, processing times, etc. in the computer.
-
-Problems can arise when you are trying to synchronise with speaker systems — typically surround-sound home theatre systems — that have their own inherent delays. You can compensate for an inherent delay using the appropriate backend (typically `alsa`) `audio_backend_latency_offset_in_seconds`. Set this offset to compensate for a fixed delay in the audio back end; for example, if the output device delays by 100 ms, set this to -0.1.
-
-Resynchronisation
--------------
-Shairport Sync actively maintains synchronisation with the source.
-If synchronisation is lost — say due to a busy source or a congested network — Shairport Sync will mute its output and resynchronise. The loss-of-sync threshold is a very conservative 0.050 seconds — i.e. the actual time and the expected time must differ by more than 50 ms to trigger a resynchronisation. Smaller disparities are corrected by insertions or deletions, as described above.
-* You can vary the resync threshold, or turn resync off completely, with the `general` `resync_threshold_in_seconds` setting.
-
-Tolerance
----------
-Playback synchronisation is allowed to wander — to "drift" — a small amount before attempting to correct it. The default is 0.002 seconds, i.e. 2 ms. The smaller the tolerance, the more likely it is that overcorrection will occur. Overcorrection is when more corrections (insertions and deletions) are made than are strictly necessary to keep the stream in sync. Use the `statistics` setting to monitor correction levels. Corrections should not greatly exceed net corrections.
-* You can vary the tolerance with the `general` `drift_tolerance_in_seconds` setting.
-
-Statistics
----------------
-If you set the `statistics` setting in the `diagnostics` section of the configuration file to `"YES"`, some statistics will be logged at regular intervals. The items logged will depend on the type of stream being processed: AirPlay 1, AirPlay 2 Buffered Audio or AirPlay 2 Realtime Audio. If the `log_verbosity` is set to 1, 2 or 3, additional items will be logged.
-
-From an audio enthusiast's point of view, the most important figure is possibly the `all sync ppm` figure. This is the total amount of interpolation needed by Shairport Sync to keep the audio stream in sync. The number represents is the ratio of frames added and removed from the audio stream relative to all the frames output in the last interval, expressed in parts per million (ppm). For reference, adding or removing one frame per second into a 44,100 frames per second stream is ± 22.68 ppm. The lower this number number is, the higher the fidelity of the audio signal passed to the output device. On a well sorted system, this figure can be 0.0 for considerable periods, but it can't really be zero forever. You may also find that the number might be higher at the start while the system settles down.
-
-The second most important figure is possibly the `sync error ms`. This is the average synchronisation error in milliseconds in the last interval. Ideally it should be 0.0. By default, Shairport Sync has a tolerance of a sync error of ± 2.0 milliseconds without triggering interpolation.
-
-Two other interesting measurements of the output rate may be available -- `output fps (r)` and `output fps (c)`, where `(r)` means "raw" and the `(c)` means "corrected".
-
-The "raw" figure is the rate at which the output device (typically a DAC) accepts data measured relative to the computer's own system clock (specifically the `CLOCK_MONOTONIC_RAW` clock). The accuracy of the number depends on the accuracy of the clock, which will typically be accurate to within anything from 20 to 100 ppm.
-
-The "corrected" figure is the rate at which the output device accepts data relative to the computer's network-time-disciplined clock (specifically the `CLOCK_MONOTONIC` clock). This clock is normally adjusted ("disciplined") to keep time with network time and should be accurate to with a few tens of milliseconds over a long period. So (1) if you could run a play session for a long period -- say a day -- and (2) if network time synchronisation is enabled and (3) if the network connection to the network time service is fast and stable, then you should get an accurate absolute measure of exact frame rate of the output device. If your internet connection is not good, the corrected figure will be very inaccurate indeed.
-
-Here is a brief description of the figures that might be provided.
-##### sync error ms
-Average playback synchronisation error in milliseconds in the last interval. By default, Shairport Sync will allow a sync error of ± 2.0 milliseconds without any interpolation. Positive means late, negative means early.
-##### net sync ppm
-This is the total amount of interpolation done by Shairport Sync to keep the audio stream in sync. The number represents is the total number of frames added and removed from the audio stream, expressed in parts per million (ppm) in the last interval. For reference, adding or removing one frame per second into a 44,100 frames per second stream is 22.68 ppm.
-##### all sync ppm
-This is the net amount of interpolation done by Shairport Sync to keep the audio stream in sync. The number represents is the number of frames added plus the number removed from the audio stream, expressed in parts per million (ppm) in the last interval. The magnitude of this should be the same as the `net sync ppm'. If it is much larger it means that Shairport Sync is overcorrecting for sync errors -- try increasing the drift tolerance to reduce it.
-##### packets
-This is the number of packets of audio frames received since the start of the session. A packet normally contains 352 ± 1 audio frames.
-##### missing
-This is the number of packets of audio frames that were not received in the last interval. It should be zero, and if not it can indicate a problem with the network. AirPlay 1 and AirPlay 2 Realtime Streams only.
-##### late
-This is the number of packets of audio frames that were received late -- but still in time to be used -- in the last interval. AirPlay 1 and AirPlay 2 Realtime Streams only.
-##### too late
-This is the number of packets of audio frames that were received too late to be used in the last interval. It is possible that these packets may already have been received, so those frames might not actually be missing when the time comes to play them. AirPlay 1 and AirPlay 2 Realtime Streams only.
-##### resend reqs
-This is the number of times Shairport Sync requests the resending of missing frames. Requests can be for one or more frames. AirPlay 1 and AirPlay 2 Realtime Streams only.
-##### min DAC queue
-The is the smallest number of frames of audio in the DAC's hardware queue. If it goes too low, the DAC may begin to underrun.
-##### min buffers
-The is the smallest number of packets of audio in the queue to be processed in the last interval. It is related to the overall latency in AirPlay 1 and AirPlay 2 Realtime Streams. If it comes close to zero it's often a sign that the network is poor.
-##### max buffers
-The is the largest number of packets of audio in the queue to be processed in the last interval.
-##### min buffer size
-The is smallest remaining number of bytes in the Buffered Audio buffer in the last interval. It can legitimately be zero when a track ends or begins. If it reaches zero while a track is playing, it means that audio data is not arriving at Shairport Sync quickly enough and may indicate network problems. AirPlay 2 Buffered Audio streams only.
-##### nominal fps
-This is the rate specified in the AirPlay stream itself. AirPlay 1 only.
-##### received fps
-This is the rate at which frames are received from the network averaged since the start of the play session. AirPlay 1 only.
-##### output fps (r)
-Output rate measured relative to the computer system's clock since the start of the play session. See above for a discussion.
-##### output fps (c)
-Output rate measured relative to the network-clock-disciplined computer system's clock since the start of the play session. See above for a discussion.
-##### source drift ppm
-This is a measure of the difference between the source clock and Shairport Sync's clock expressed in parts per million. Only valid when 10 or more drift samples have been received. AirPlay 1 only.
-##### drift samples
-This is the number drift samples have been accepted for calculating the source drift. AirPlay 1 only.
-#### Example
-The following example is of an AirPlay 2 Buffered Audio Stream from a HomePod mini to a WiFi-connected Raspberry Pi 3 equipped with a Pimoroni "Audio DAC SHIM (Line-Out)" with `log_verbosity` set to `1`.
-
-```
- sync error ms net sync ppm all sync ppm packets min DAC queue min buffers max buffers output fps (r) output fps (c)
- -1.88 8.5 8.5 526575 8455 62 63 44099.98 44099.92
- -1.92 31.2 31.2 527578 8460 62 63 44099.98 44099.92
- -1.87 2.8 2.8 528581 8467 62 63 44099.98 44099.93
- -1.98 22.7 22.7 529584 8466 62 63 44099.98 44099.93
- -2.01 73.6 73.6 530587 8468 62 63 44099.98 44099.93
- -1.99 93.5 93.5 531590 8463 62 62 44099.98 44099.94
- -1.77 5.7 5.7 532593 8466 62 63 44099.98 44099.94
- -1.84 2.8 2.8 533596 8456 62 62 44099.98 44099.95
- -1.54 0.0 0.0 534599 8477 62 63 44099.98 44099.95
- -1.19 0.0 0.0 535602 8501 62 62 44099.98 44099.95
- -1.03 0.0 0.0 536605 8505 62 62 44099.98 44099.96
- -1.10 0.0 0.0 537608 8497 62 63 44099.98 44099.96
- -1.39 0.0 0.0 538611 8485 62 63 44099.98 44099.97
- -1.43 0.0 0.0 539614 8485 62 63 44099.98 44099.97
- -1.75 0.0 0.0 540617 8481 62 62 44099.98 44099.97
- -1.52 0.0 0.0 541620 8474 62 63 44099.98 44099.98
- -1.37 0.0 0.0 542623 8488 62 62 44099.98 44099.98
- -1.63 0.0 0.0 543626 8481 62 62 44099.98 44099.98
- -2.01 102.0 102.0 544629 8465 62 62 44099.98 44099.99
- -1.88 14.2 14.2 545632 8474 62 62 44099.98 44099.99
- -1.42 0.0 0.0 546635 8486 62 63 44099.98 44099.99
- -1.92 17.0 17.0 547638 8435 62 63 44099.98 44100.00
- -1.27 0.0 0.0 548641 8479 62 62 44099.98 44100.00
- -0.64 0.0 0.0 549644 8528 62 62 44099.98 44100.00
- -1.12 0.0 0.0 550647 8476 62 62 44099.98 44100.01
- -1.88 25.5 25.5 551650 8471 62 62 44099.98 44100.01
- -1.79 0.0 0.0 552653 8477 62 62 44099.98 44100.01
- -1.79 0.0 0.0 553656 8477 62 63 44099.98 44100.02
- -1.81 19.8 19.8 554659 8467 62 62 44099.98 44100.02
- -2.04 110.5 110.5 555662 8468 62 63 44099.98 44100.02
- -1.64 2.8 2.8 556665 8476 62 62 44099.98 44100.02
- -1.29 0.0 0.0 557668 8496 62 63 44099.98 44100.03
- -1.20 0.0 0.0 558671 8500 62 63 44099.98 44100.03
- -1.33 0.0 0.0 559674 8483 62 63 44099.98 44100.03
- -1.43 0.0 0.0 560677 8468 62 63 44099.98 44100.03
- -1.47 0.0 0.0 561680 8484 62 62 44099.98 44100.04
- -0.88 0.0 0.0 562683 8512 62 62 44099.98 44100.04
- -1.16 0.0 0.0 563686 8500 62 63 44099.98 44100.04
- -1.42 0.0 0.0 564689 8488 62 62 44099.98 44100.05
- -1.58 0.0 0.0 565692 8476 62 63 44099.98 44100.05
- -1.50 0.0 0.0 566695 8488 62 63 44099.98 44100.05
- -1.79 0.0 0.0 567698 8471 62 63 44099.98 44100.05
- -1.82 8.5 8.5 568701 8473 62 62 44099.98 44100.06
- -1.87 19.8 19.8 569704 8468 62 63 44099.98 44100.06
- -1.96 85.0 85.0 570707 8456 62 63 44099.98 44100.06
- -1.80 2.8 2.8 571710 8452 62 63 44099.98 44100.06
- -1.66 0.0 0.0 572713 8477 62 62 44099.98 44100.07
-```
-For reference, a drift of one second per day is approximately 11.57 ppm. Left uncorrected, even a drift this small between two audio outputs will be audible after a short time.
-
-WiFi Issues
----------
-If you are using WiFi, you should ensure that WiFi power management is off. See [TROUBLESHOOTING](https://github.com/mikebrady/shairport-sync/blob/master/TROUBLESHOOTING.md) for more details.
-
-Troubleshooting
----------------
-Please refer to [TROUBLESHOOTING](https://github.com/mikebrady/shairport-sync/blob/master/TROUBLESHOOTING.md) for a few hints, contributed by users.
-
-MQTT
----------------
-Please refer to the [MQTT INFO](https://github.com/mikebrady/shairport-sync/blob/master/MQTT.md) page for additional info on building, configuring and using MQTT to interface shairport-sync with common home automation systems (contributed by users).
-
-Packaging status
-----------------
-
-[](https://repology.org/project/shairport-sync/versions)
+# More Information
+Information in this document has been updated and moved to [ADVANCED TOPICS](https://github.com/mikebrady/shairport-sync/blob/development/ADVANCED%20TOPICS/README.md).
+# Shairport Sync
+Shairport Sync is an [AirPlay](https://www.pocket-lint.com/speakers/news/apple/144646-apple-airplay-2-vs-airplay-what-s-the-difference) audio player for Linux and FreeBSD. It plays audio streamed from Apple devices and from AirPlay sources such as [OwnTone](https://github.com/owntone/owntone-server) (formerly `forked-daapd`).
+
+Shairport Sync can be built as an AirPlay 2 player (with [some limitations](https://github.com/mikebrady/shairport-sync/blob/development/AIRPLAY2.md#features-and-limitations)) or as "classic" Shairport Sync – a player for the older, but still supported, AirPlay (aka "AirPlay 1") protocol.
+
+Metadata such as artist information and cover art can be requested and provided to other applications. Shairport Sync can interface with other applications through MQTT, an MPRIS-like interface and D-Bus.
+
+Shairport Sync does not support AirPlay video or photo streaming.
+
+# Quick Start
+* A building guide is available [here](https://github.com/mikebrady/spsdoc/blob/main/BUILD.md).
+* A Docker image is available on the Docker Hub in [this repository](https://hub.docker.com/repository/docker/mikebrady/shairport-sync).
+* Next Steps and Advanced Topics are [here](ADVANCED%20TOPICS/README.md).
+* Build configuration options are detailed in [CONFIGURATION FLAGS.md](CONFIGURATION%20FLAGS.md).
+* Runtime settings are documented [here](https://github.com/mikebrady/shairport-sync/blob/development/scripts/shairport-sync.conf).
+
+# Features
+* Outputs AirPlay audio to [ALSA](https://www.alsa-project.org/wiki/Main_Page), [sndio](http://www.sndio.org), [PulseAudio](https://www.freedesktop.org/wiki/Software/PulseAudio/), [Jack Audio](http://jackaudio.org), to a unix pipe or to `STDOUT`. It also has experimental support for [PipeWire](https://pipewire.org) and limited support for [libao](https://xiph.org/ao/) and for [libsoundio](http://libsound.io).
+* Metadata — Shairport Sync can deliver metadata supplied by the source, such as Album Name, Artist Name, Cover Art, etc. through a pipe or UDP socket to a recipient application program — see https://github.com/mikebrady/shairport-sync-metadata-reader for a sample recipient. Sources that supply metadata include iTunes and the Music app in macOS and iOS.
+* An interface to [MQTT](https://en.wikipedia.org/wiki/MQTT), a popular protocol for Inter Process Communication, Machine-to-Machine, Internet of Things and Home Automation projects. The interface including access to metadata and artwork, and limited remote control.
+* Digital Signal Processing facilities – please see the [DSP Wiki Page Guide](https://github.com/mikebrady/shairport-sync/wiki/Digital-Signal-Processing-with-Shairport-Sync). (Thanks to [Yann Pomarède](https://github.com/yannpom) for the code and to [Paul Wieland](https://github.com/PaulWieland) for the guide.)
+* An [MPRIS](https://specifications.freedesktop.org/mpris-spec/2.2/)-like interface, partially complete and very functional, including access to metadata and artwork, and limited remote control.
+* A native D-Bus interface, including access to metadata and artwork, limited remote control and system settings.
+* Better Volume Control — Shairport Sync offers finer control at very top and very bottom of the volume range. See http://tangentsoft.net/audio/atten.html for a good discussion of audio "attenuators", upon which volume control in Shairport Sync is modelled. See also the diagram of the volume transfer function in the documents folder. In addition, Shairport Sync can offer an extended volume control range on devices with a restricted range.
+* Support for the [Apple ALAC decoder](https://macosforge.github.io/alac/) (library available [here](https://github.com/mikebrady/alac)).
+* Output bit depths of 8, 16, 24 and 32 bits, rather than the standard 16 bits.
+* Output frame rates of 44,100, 88,200, 176,000 or 352,000 frames per second.
+
+Some features require configuration at build time – see [CONFIGURATION FLAGS.md](CONFIGURATION%20FLAGS.md).
+
+# Status
+Shairport Sync was designed to [run best](ADVANCED%20TOPICS/GetTheBest.md) on stable, dedicated, stand-alone low-power "headless" systems with ALSA as the audio system and with a decent CD-quality Digital to Analog Converter (DAC).
+
+Shairport Sync runs on recent (2018 onwards) Linux systems and FreeBSD from 12.1 onwards. It requires a system with the power of a Raspberry Pi 2 or a Pi Zero 2 or better.
+
+Classic Shairport Sync runs on a wider variety of Linux sytems, including OpenWrt and Cygwin and it also runs on OpenBSD. Many embedded devices are powerful enough to power classic Shairport Sync.
+
+# Heritage and Acknowledgements
+The functionality offered by Shairport Sync is the result of study and analysis of the AirPlay and AirPlay 2 protocols by many people over the years. These protocols have not been officially published, and there is no assurance that Shairport Sync will continue to work in future.
+
+Shairport Sync is a substantial rewrite of the fantastic work done in Shairport 1.0 by James Wah (aka [abrasive](https://github.com/abrasive)), James Laird and others — please see [this list](https://github.com/abrasive/shairport/blob/master/README.md#contributors-to-version-1x) of the contributors to Shairport 1.x and Shairport 0.x. From a "heritage" point of view, Shairport Sync is a fork of Shairport 1.0.
-Shairport Sync
-=============
-* Shairport Sync is an AirPlay audio player – it plays audio streamed from Apple devices and from AirPlay sources such as [OwnTone](https://github.com/owntone/owntone-server) (formerly `forked-daapd`).
-* Shairport Sync can provide "classic" AirPlay 1 or limited Airplay 2 support. The AirPlay 2 build is much more demanding. It requires a faster system, more storage and more RAM both at build time and run time.
-* Shairport Sync does not support AirPlay video or photo streaming.
-
-AirPlay 2
----
-For the latest on AirPlay 2, please visit [AIRPLAY2.md](https://github.com/mikebrady/shairport-sync/blob/development/AIRPLAY2.md).
-
-Guides
----
-* A brief guide to building classic Shairport Sync (for AirPlay 1) is available at [BUILDFORAP1.md](https://github.com/mikebrady/shairport-sync/blob/development/BUILDFORAP1.md).
-* A guide to building Shairport Sync for AirPlay 2 on Linux is available at [BUILDFORAP2.md](https://github.com/mikebrady/shairport-sync/blob/development/BUILDFORAP2.md).
-* A guide to building for AirPlay 1 or AirPlay 2 on FreeBSD is available at [FREEBSD.md](https://github.com/mikebrady/shairport-sync/blob/development/FREEBSD.md).
-* Please note, a Docker image including Airplay 2 support is available under the docker folder of this repo.
-
-More Information
----
-For more information, please visit [MOREINFO.md](https://github.com/mikebrady/shairport-sync/blob/development/MOREINFO.md).
-
-Acknowledgements
----
For the development of AirPlay 2 support, special thanks are due to:
* [JD Smith](https://github.com/jdtsmith) for really thorough testing, support and encouragement.
* [ejurgensen](https://github.com/ejurgensen) for advice and [code to deal with pairing and encryption](https://github.com/ejurgensen/pair_ap).
* [invano](https://github.com/invano) for showing what might be possible and for initial Python development.
* [Charles Omer](https://github.com/charlesomer) for Docker automation, repository management automation, testing, encouragement, enthusiasm.
-And of course, thanks to everyone who has supported and improved Shairport Sync over the years.
+Much of Shairport Sync's AirPlay 2 functionality is based on ideas developed at the [openairplay airplay2-receiver]( https://github.com/openairplay/airplay2-receiver) repository. It is a pleasure to acknowledge the work of the contributors there.
+
+Thanks to everyone who has supported and improved Shairport Sync over the years.
+
+# More about Shairport Sync
+The audio that Shairport Sync receives is sent to the computer's sound system, to a named unix pipe or to `STDOUT`. By far the best sound system to use is ALSA. This is because ALSA can give direct access to the Digital to Analog Converter (DAC) hardware of the machine. Audio samples can be sent through ALSA directly to the DAC, maximising fidelity, and accurate timing information can be obtained from the DAC, maximising synchronisation. Direct access to hardware is given through ALSA devices with names beginning with `hw:`.
+
+## Synchronised Audio
+Shairport Sync offers *full audio synchronisation*. Full audio synchronisation means that audio is played on the output device at exactly the time specified by the audio source. To accomplish this, Shairport Sync needs access to audio systems – such as ALSA on Linux and `sndio` on FreeBSD – that provide very accurate timing information about audio being streamed to output devices. Ideally, Shairport Sync should have direct access to the output device used, which should be a real sound card capable of working with 44,100, 88,200 or 176,400 samples per second, interleaved PCM stereo of 8, 16, 24 or 32 bits. Using the ALSA sound system, Shairport Sync will choose the greatest bit depth available at 44,100 samples per second, resorting to multiples of 44,100 if it is not available. You'll get a message in the log if there's a problem. With all other sound systems, a sample rate of 44,100 is chosen with a bit depth of 16 bit.
+
+Shairport Sync works well with PulseAudio, a widely used sound server found on many desktop Linuxes. While the timing information is not as accurate as that of ALSA or `sndio`, it is often impractical to remove or disable PulseAudio.
+
+For other use cases, Shairport Sync can provide synchronised audio output to a unix pipe or to `STDOUT`, or to audio systems that do not provide timing information. This could perhaps be described as *partial audio synchronisation*, where synchronised audio is provided by Shairport Sync, but what happens to it in the subsequent processing chain, before it reaches the listener's ear, is outside the control of Shairport Sync.
+
+## Latency, "Stuffing", Timing
+AirPlay protocols use an agreed *latency* – a time lag or delay – between the time represented by a sound sample's `timestamp` and the time it is actually played by the audio output device, typically a Digital to Audio Converter (DAC). Latency gives players time to compensate for network delays, processing time variations and so on. The latency is specified by the audio source when it negotiates with Shairport Sync. AirPlay sources set a latency of around 2.0 to 2.25 seconds. AirPlay 2 can use shorter latencies, around half a second.
+
+As mentioned previously, Shairport Sync implements full audio synchronisation when used with ALSA, `sndio` or PulseAudio audio systems. This is done by monitoring the timestamps present in data coming from the audio source and the timing information coming back from the audio system itself. To maintain the latency required for exact synchronisation, if the output device is running slow relative to the source, Shairport Sync will delete frames of audio to allow the device to keep up. If the output device is running fast, Shairport Sync will insert ("stuff") extra frames to keep time. The number of frames inserted or deleted is so small as to be almost inaudible on normal audio material. Frames are inserted or deleted as necessary at pseudorandom intervals. Alternatively, with `libsoxr` support, Shairport Sync can resample the audio feed to ensure the output device can keep up. This is less obtrusive than insertion and deletion but requires a good deal of processing power — most embedded devices probably can't support it. If your computer is fast enough, Shairport Sync will, by default, automatically choose this method.
+
+Stuffing is not done for partial audio synchronisation – the audio samples are simply presented at exactly the right time to the next stage in the processing chain.
+
+Timestamps are referenced relative to the source computer's clock – the "source clock", but timing must be done relative to the clock of the computer running Shairport Sync – the "local clock". So, Shairport Sync synchronises the source clock and the local clock, usually to within a fraction of a millisecond. In AirPlay 2, this is done with the assistance of a companion application called [NQPTP](https://github.com/mikebrady/nqptp) using a [PTP](https://en.wikipedia.org/wiki/Precision_Time_Protocol)-based timing protocol. In classic AirPlay, a variant of [NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol) synchronisation protocols is used.
1. Before starting, ensure that your software is up-to-date. This document always refers to the most recent version of Shairport Sync -- see [here](https://github.com/mikebrady/shairport-sync/releases) for information about the most recent release.
2. If you have set `interpolation` in the `general` section of the configuration file to to `soxr`, comment it out or set it to `auto` or `basic` as the `soxr` setting can cause lower-powered devices to bog down at critical times, e.g. see [this report](https://github.com/mikebrady/shairport-sync/issues/631#issuecomment-366305203).
-3. Ensure the volume setting of your output device is set to some reasonable value and ensure it is not muted. For ALSA devices, the `alsamixer` command-line tool is very good for this. For other sound systems, please consult the relevant documentation.
+
+### No/Low Sound
+Let's say you've just installed or updated Shairport Sync and you are testing it for the first time after installing or updating.
+If you are using the default ALSA backend, don't forget to check two simple things:
+1. Check that the volume on the output device is turned up. If the output device has a "mixer" i.e. a volume control, Shairport Sync does not, by default, try to control it. Therefore, if it happens to be very low or even at zero, you might not hear audio that is actually coming through to the device. (You can get Shairport Sync to control a mixer -- see [here](https://github.com/mikebrady/spsdoc/blob/main/ADVANCED%20TOPICS/InitialConfiguration.md) for some hints.)
+2. Check that the output device is not muted. Some audio applications (including very old versions of Shairport Sync) leave the output device mixer in a muted state after use to minimise the possibility of noise. However, this is not generally compatible with other audio players using the same device, as they generally expect the device to be unmuted.
+
+You can use `alsamixer` for both of theses checks. A muted output has the letter(s) `M` as its value. Select it and type `M` again to unmute.
### WiFi adapter running in power-saving / low-power mode
You can play from other devices but not from your Windows PC.
-**Possible Solution**
+**Possible Issue -- AirPlay 2**
+iTunes on Windows is not compatible with Shairport Sync when it is built for AirPlay 2. This is unlikely to change, unfortunately. However, iTunes on Windows remains compatible with "classical" Shairport Sync.
+
+**Possible Issue -- AirPlay**
+The Windows Firewall is preventing access to Shairport Sync.
-Allow network discovery. This setting creates a private type network and enables Windows to access the ports and protocols necessary to use Shairport Sync.
+Solution: Allow network discovery. This setting creates a private type network and enables Windows to access the ports and protocols necessary to use Shairport Sync.
### UFW firewall blocking ports (commonly includes Raspberry Pi)
`sudo ufw disable`
-- Try to launch a song from your remote device on the Shairport-sync one, if this works, proceed to the next step and follow the ones described below, in the solution section.
+- Try to launch a song from your remote device on the Shairport Sync one. If this works, proceed to the next step and follow the ones described below, in the solution section.
- Enable UFW through the following command:
+### Updating Shairport Sync
-### Updating Shairport Sync [Needs updating for Airplay 2]
-This guide is for building and updating an installation of Shairport Sync.
-
-If you updated Shairport Sync from a package, most of these instructions don't apply – please go to the section at the end called "Post Update Tasks". If you wish to build an installation of Shairport Sync to replace an installation that came from a package, instructions don't apply either – instead, please follow the guide at [INSTALL.md](https://github.com/mikebrady/shairport-sync/blob/master/INSTALL.md).
-
-To do an update, you basically have to go through the whole process of building Shairport Sync again,
-but a few steps are shorter because you've done them before; you won't have to reinstall the build tools or libraries needed, and you won't have to define the user and group or reconfigure the settings in the configuration file.
-
-But before you begin, you should update and upgrade any packages.
-
-Note that in this guide, a `$` prefix means you should be in the normal user mode; a `#` prefix means you should be in the superuser or root mode.
-
-Here is the sequence for Raspberry Pi OS (Buster), which is based on Debian Buster. The same commands work for Ubuntu, and maybe more. Here, a non-`root` user with `sudo` privileges is assumed.
-
-```
-$ sudo apt-get update
-$ sudo apt-get upgrade
-```
-Next, stop playing music to your device.
-
-### Remove Old Copies
-It's a good idea to search for and 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:
-```
-$ which shairport-sync
-/usr/local/bin/shairport-sync
-```
-Remove it as follows:
-```
-# rm /usr/local/bin/shairport-sync
-```
-Do this until no more copies of `shairport-sync` are found. This is especially important if you are building Shairport Sync over an old version that was installed from packages, as the built application will be installed in a different directory to the packaged installation.
-
-### Remove Old Startup and Service Scripts
-You should also remove the startup script and service definition files `/etc/systemd/system/shairport-sync.service`, `/lib/systemd/system/shairport-sync.service`, `/etc/init.d/shairport-sync`, `/etc/dbus-1/system.d/shairport-sync-dbus.conf` and `/etc/dbus-1/system.d/shairport-sync-mpris.conf` if they exist – new ones will be installed if necessary. As with the previous section, this is especially important if you are building Shairport Sync over an old version that was installed from packages, as the scripts for the built application may be different to those of the packaged version. If they are left in place, bad things can happen.
-
-### Reboot after Cleaning Up
-If you removed any installations of Shairport Sync or any of its startup script files in the last two steps, you should reboot.
-
-### Building the Updated Shairport Sync
-Now, to build, update and install Shairport Sync, if you still have the directory in which you previously built Shairport Sync, it will contain the repository you originally downloaded. Navigate your way to it and 'pull' the changes from GitHub:
-
-```
-$ git pull
-```
-Otherwise – say if you deleted the repository – just pull Shairport Sync from GitHub again and move into the new directory:
-```
-$ git clone https://github.com/mikebrady/shairport-sync.git
-$ cd shairport-sync
-```
-(If you wish to use the `development` branch, you should enter the command `$ git checkout development` at this point. Everything else is the same.)
-
-Now, while in the `shairport-sync` directory, perform the following commands (note that there is a choice you must make in there):
-```
-$ autoreconf -fi
-```
-Please review the release notes to see if any configuration settings have been changed. For instance, in the transitions from version 2 to version 3, the `--with-ssl=polarssl` has been deprecated in favour of `--with-ssl=mbedtls`.
-```
-#The following is the standard configuration for a Linux that uses the alsa backend and systemd initialisation system:
-$ ./configure --with-alsa --with-avahi --with-ssl=openssl --with-metadata --with-soxr --with-systemd --sysconfdir=/etc
-#OR
-#The following is the standard configuration for a Linux that uses the alsa backend and the older System V initialisation system:
-$ ./configure --with-libdaemon --with-alsa --with-avahi --with-ssl=openssl --with-metadata --with-soxr --with-systemv --sysconfdir=/etc
-
-$ make
-$ sudo make install
-```
-At this point you have downloaded, compiled and installed the updated Shairport Sync. However, the older version is still running. So, you need to do a little more:
-
-If you are on a `systemd`-based system such as Raspbian Jessie or recent versions of Ubuntu and Debian, execute the following commands:
-```
-$ sudo systemctl daemon-reload
-$ sudo systemctl restart shairport-sync
-```
-Otherwise execute the following command:
-```
-$ sudo service shairport-sync restart
-```
-
-Your Shairport Sync should be upgraded now.
-
-### Post Update Tasks
-1 **Unmute the Output Device Mixer** (This applies only if you are using a hardware mixer for volume control.) Certain older versions of Shairport Sync could leave the output device mixer in a muted state after use to minimise the possibility of noise. However, this is not generally compatible with other audio players using the same device, as they would generally expect the device to be unmuted. Recent versions of Shairport Sync therefore do not use the mute facility by default. When you update Shairport Sync, the output device mixer might have been muted by the previous version, so you should unmute it, using, for instance, the following command:
-```
-$ sudo amixer sset <mixer_name> unmute
-```
-Alternatively you can use `alsamixer`. A muted output has the letter(s) `M` as its value. Select it and type `M` again to unmute.
-
+This guide has been superseded by the general building guide at [BUILD.md](https://github.com/mikebrady/shairport-sync/blob/development/BUILD.md).
projects / thirdparty / shairport-sync.git / commitdiff
