nils/shairport-sync
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

This squashed commit comprises a long series of improvements, bug fixes, optimizations, and new feature additions:

Browse Source 
- 48,000 frames per second operation,
 - 48k lossless stereo, 5.1 and 7.1 surround sound
 - Multichannel and multi rate operation on ALSA, PipeWire, PulseAudio, FreeBSD, stdout and unix pipe output backends.

Automatic, flexible and controllable output format (rate, sample format and channel count) selection.

Full FFmpeg integration to support transcoding, resampling, and new audio formats.

Better operation on lower powered devices down to e.g. Raspberry Pi B.

Reduced Docker image sizes with a slimmed-down FFmpeg library.

Enhanced timestamp handling for better synchronization.

Improved the sync error calculation.

A new "vernier" resampling and interpolation method for low-power CPUs.

Bug fixes and minor enhancements.

Note -- there are many breaking changes from previous versions of Shairport Sync!
This commit is contained in:
Mike Brady
2025-02-23 13:31:17 +00:00
parent 588e6a5b7b
commit 60143518c2
110 changed files with 12416 additions and 7759 deletions
Download Patch File Download Diff File Expand all files Collapse all files
BUILD.md
+91 -26
View File
@@ -1,7 +1,9 @@
# 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](AIRPLAY2.md#features-and-limitations)) or as "classic" Shairport Sync – a player for the older, but still supported, AirPlay (aka "AirPlay 1") protocol. Check ["What You Need"](AIRPLAY2.md#what-you-need) for some basic system requirements.
Shairport Sync can be built as an AirPlay 2 player (with [some limitations](AIRPLAY2.md#features-and-limitations)) or as classic Shairport Sync – a player for the older, but still supported, "classic" AirPlay (aka "AirPlay 1") protocol. Check ["What You Need"](AIRPLAY2.md#what-you-need) for some basic system requirements.
Note that Shairport Sync does not work well in virtual machines -- YMMV.
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.
@@ -26,8 +28,11 @@ You should also remove any of the following service files that may be present:
* `/lib/systemd/system/shairport-sync.service`
* `/lib/systemd/user/shairport-sync.service`
* `/etc/init.d/shairport-sync`
* `~/.config/systemd/user/shairport-sync.service`
New service files will be installed if necessary at the `# make install` stage.
(In FreeBSD, there is no need to remove the file at `/usr/local/etc/rc.d/shairport-sync` – it's always replaced in the `make install` step.)
#### 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.
@@ -40,15 +45,23 @@ Okay, now let's get the tools and libraries for building and installing Shairpor
# apt upgrade # this is optional but recommended
# apt install --no-install-recommends build-essential git 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
libplist-dev libsodium-dev uuid-dev libgcrypt-dev xxd libplist-utils \
libavutil-dev libavcodec-dev libavformat-dev
```
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 autoconf automake libtool \
libpopt-dev libconfig-dev libasound2-dev avahi-daemon libavahi-client-dev libssl-dev libsoxr-dev
libpopt-dev libconfig-dev libasound2-dev avahi-daemon libavahi-client-dev libssl-dev libsoxr-dev \
libavutil-dev libavcodec-dev libavformat-dev
```
Building on Ubuntu 24.10, and possibly other distributions, requires `systemd-dev`. It does no harm to attempt to install it -- it will simply fail if the package doesn't exist:
```
# apt install --no-install-recommends systemd-dev # it's okay if this fails because the package doesn't exist
```
### Fedora (Fedora 40)
For AirPlay 2 operation, _before you install the libraries_, please ensure the you have [enabled](https://docs.fedoraproject.org/en-US/quick-docs/rpmfusion-setup) RPM Fusion software repositories to the "Nonfree" level. If this is not done, the FFmpeg libraries will lack a suitable AAC decoder, preventing Shairport Sync from working in AirPlay 2 mode.
```
@@ -63,7 +76,7 @@ If you are building classic Shairport Sync, the list of packages is shorter:
# yum update
# yum install make automake gcc gcc-c++ \
git autoconf automake avahi-devel libconfig-devel openssl-devel popt-devel soxr-devel \
alsa-lib-devel
ffmpeg ffmpeg-devel alsa-lib-devel
```
### Arch Linux
After you have installed the libraries, note that you should enable and start the `avahi-daemon` service.
@@ -75,7 +88,7 @@ After you have installed the libraries, note that you should enable and start th
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
# pacman -Sy git base-devel alsa-lib popt libsoxr avahi libconfig ffmpeg
```
Enable and start the `avahi-daemon` service.
```
@@ -105,14 +118,17 @@ hosts: files dns mdns
```
Reboot for these changes to take effect.
Next, install the packages that are needed for Shairport Sync and NQPTP:
Next, install the packages that are needed for Shairport Sync and NQPTP. If you will be using using `--with-sndio` instead of `--with-alsa` -- see below -- you can omit the `alsa-utils` package.
If you are building Shairport Sync for AirPlay 2, install the following packages:
```
# pkg install git autotools pkgconf popt libconfig openssl alsa-utils libsoxr \
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 libsoxr
# pkg install git autotools pkgconf popt libconfig openssl alsa-utils ffmpeg
```
## 3. Build
### NQPTP
@@ -122,56 +138,101 @@ Download, install, enable and start NQPTP from [here](https://github.com/mikebra
### Shairport Sync
#### Build and Install
Download Shairport Sync, branch and configure, compile and install it. Before executing the commands, please note the following:
Download Shairport Sync 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](CONFIGURATION%20FLAGS.md). For this walkthrough, though, please do not remove the `--with-alsa` flag.
##### Build Options
* **FreeBSD:** For FreeBSD, replace `--with-systemd-startup` with `--with-os=freebsd --with-freebsd-startup`.
* Optionally, replace `--with-alsa` with the backend for FreeBSD's native audio system `--with-sndio`.
* If you omit the `--sysconfdir=/etc` entry, `/usr/local/etc` will be used as the `sysconfdir`, which is conventionally used in FreeBSD.
* **Classic Shairport Sync:** For classic Shairport Sync, replace `--with-airplay-2` with `--with-ffmpeg`.
* You can actually omit `--with-ffmpeg` when building classic Shairport Sync, but it is not recommended. While you'll save space (you can omit the FFMpeg libraries in the build and run-time environments), transcoding, e.g. from 44,100 to 48,000 frames per second, will not be available and less well-maintained and less secure decoders will be used.
* **Extra Features:** If you wish to add extra features, for example an extra audio backend, take a look at the [configuration flags](CONFIGURATION%20FLAGS.md). For this walkthrough, though, please do not change too much!
```
$ git clone https://github.com/mikebrady/shairport-sync.git
$ cd shairport-sync
$ git checkout development
$ autoreconf -fi
$ autoreconf -fi # about 1.5 minutes on a Raspberry Pi B
$ ./configure --sysconfdir=/etc --with-alsa \
--with-soxr --with-avahi --with-ssl=openssl --with-systemd --with-airplay-2
$ make
--with-soxr --with-avahi --with-ssl=openssl --with-systemd-startup --with-airplay-2
$ make # just over 7 minutes on a Raspberry Pi B
# 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:
At this point, Shairport Sync should be built and installed but not running. Now you can test it out from the command line. Before you start testing, though, if you have built Shairport Sync for AirPlay 2 operation, ensure `NQPTP` is running.
To check the installation, enter:
```
$ 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 below, or in the [TROUBLESHOOTING.md](TROUBLESHOOTING.md) guide.
The AirPlay service should appear on the network and the audio you play should come through to the default audio output device. You can use the AirPlay volume control or the system's volume controls or a command-line tool like `alsamixer` to adjust levels.
Note: Shairport Sync will run indefinitely -- use Control-C it to stop it.
If you have problems, please check the hints in Final Notes below, or in the [TROUBLESHOOTING.md](TROUBLESHOOTING.md) guide.
When you are finished running Shairport Sync, use Control-C it to stop it.
## 5. Enable and Start Service
If your system has a Graphical User Interface (GUI) it probably uses PulseAudio or PipeWire for audio services. If that is the case, please review [Working with PulseAudio or PipeWire](https://github.com/mikebrady/shairport-sync/blob/master/ADVANCED%20TOPICS/PulseAudioAndPipeWire.md).
Otherwise, once you are happy that Shairport Sync runs from the command line, you should enable and start the `shairport-sync` service. This will launch Shairport Sync automatically as a background "daemon" service when the system powers up:
### Linux
If your system uses either PipeWire or PulseAudio as sound servers (most "desktop" Linuxes use one or the other), Shairport Sync must be started as a user service. This is because the PipeWire or PulseAudio services -- needed by Shairport Sync -- are user services themselves, and they must be running before Shairport Sync starts. That implies that Shairport Sync must be started as a user service.
#### Checking for PipeWire or PulseAudio
If PipeWire is installed and running, the following command should return status information, as follows:
```
$ systemctl --user status pipewire
● pipewire.service - PipeWire Multimedia Service
Loaded: loaded (/usr/lib/systemd/user/pipewire.service; enabled; preset: enabled)
...
```
If not, it will return something like this:
```
$ systemctl --user status pipewire
Unit pipewire.service could not be found.
```
Similarly, if PulseAudio is installed, the following command return status information:
```
$ systemctl --user status pulseaudio
```
If PipeWire or PulseAudio is installed, you must enable Shairport Sync as a _user service_ only.
#### Enable Shairport Sync as a User Service
To enable Shairport Sync as a user service that starts automatically when the user logs in, ensure you are logged in as that user and enter:
```
$ systemctl --user enable shairport-sync
```
#### Enable Shairport Sync as a System Service
To enable Shairport Sync as a system service that starts automatically when the system starts up, enter:
```
# systemctl enable shairport-sync
```
#### User Service Limitations.
1. If Shairport Sync is installed as a user service, it is activated when that user logs in and deactivated when the user logs out.
On an unattended system, this difficulty can be overcome by using automatic user login.
2. If your system has a GUI (that is, if it's a "desktop Linux"), then audio will only be routed to the speakers when the user is logged in through the GUI.
### 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.
Reboot the machine. The AirPlay service should once again be visible on the network and audio will be sent to the default audio output.
## 7. Final Notes
A number of system settings can affect Shairport Sync. Please review them as follows:
### ALSA Output Devices
If your system is _not_ using PipeWire or PulseAudio (see [above](#checking-for-pipewire-or-pulseaudio)), it probably uses ALSA directly. The following hints might be useful:
1. To access ALSA output devices, a user must be in the `audio` group. To add the current user to the `audio` group, enter:
```
$ sudo usermod -aG audio $USER
```
2. Ensure that the ALSA default output device is not muted and has the volume turned up -- `alsamixer` is very useful for this.
3. To explore the ALSA output devices on your system, consider using the [dacquery](https://github.com/mikebrady/dacquery) tool.
### 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.
@@ -194,6 +255,10 @@ If a firewall is running (some systems, e.g. Fedora, run a firewall by default),
### Add to Home
With AirPlay 2, you can follow the steps in [ADDINGTOHOME.md](ADDINGTOHOME.md) to add your device to the Apple Home system.
### Wait, there's more...
Instead of using default values for everything, you can use the configuration file to get finer control over the setup, particularly the output device and mixer control -- see [Finish Setting Up](ADVANCED%20TOPICS/InitialConfiguration.md).
At this point, you should have a basic functioning Shairport Sync installation. If you want more control – for example, using the ALSA backend, if you want to use a specific DAC, or if you want AirPlay to control the DAC's volume control – you can use settings in the configuration file or you can use command-line options.
#### Configuration File
When you run `# make install`, a configuration file is installed if one doesn't already exist. Additionally, a sample configuration file called `shairport-sync.conf.sample` is _always_ installed. This contains all the setting groups and all the settings available, commented out so that default values are used. The file contains explanations of the settings, useful hints and suggestions. The configuration file and the sample configuration file are installed in the `sysconfdir` you specified at the `./configure...` step above.
Please take a look at [Advanced Topics](ADVANCED%20TOPICS/README.md) for some ideas about what else you can do to enhance the operation of Shairport Sync. For example, you can adjust synchronisation to compensate for delays in your system.