-Experimental Build Instructions for AirPlay 2
+Build Instructions for AirPlay 2
==
+* Build instructions are different from previous versions of Shairport Sync. Please read carefully.
* This code is experimental and much of the normal functionality of Shairport Sync is broken. Please do not use it in situations where reliable service is expected.
* Be especially careful with audio systems capable of very high volume output -- the volume control in this software may not be reliable!
-* Initially, at least, leave the settings in the configuration file at default except as noted below.
-* 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), Ubuntu 20.04 -- fully updated.
-* AirPlay 2 uses a timing system based on the [IEEE-1588 Precision Timing Protocol (PTP)](https://standards.ieee.org/standard/1588-2008.html). Shairport Sync relies on a program called [`nqptp`](https://github.com/mikebrady/nqptp) to monitor PTP signals. This program uses ports 319 and 320 and replaces any PTP service you have on the computer.
- In addition, `nqptp` must run with `root` privileges.
- (FYI, most computers do not have a PTP clock running. They often use a [Network Timing Protocol (NTP)](http://www.ntp.org) service to keep the system clock synchronised with world time.)
-* Shairport Sync has a build dependency on `nqptp`, so you should check and update `nqptp` *before* building or updating Shairport Sync.
-* The SMI Interface 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.
+* for the moment, leave the settings in the configuration file at default except as noted below.
+* 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), Ubuntu 20.04 -- fully updated.
+* Shairport Sync relies on a 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.
+ In addition, `nqptp` must run with `root` privileges.
+ (FYI, most computers do not have a PTP clock running. They often use a totally different [Network Timing Protocol (NTP)](http://www.ntp.org) service to keep the system clock synchronised with world time.)
+* Shairport Sync has a build dependency on `nqptp`, so you should build or update `nqptp` *before* building or updating Shairport Sync.
+* 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.
* Build instructions are likely to change.
Build and Install Instructions
The `nqptp` service monitors PTP clocks. It provides a [POSIX Shared Memory](https://man7.org/linux/man-pages/man7/shm_overview.7.html) Interface at `/nqptp`. A shared pthread mutex is contained within the interface, and to use it you need write access.
-Next, download Shairport Sync, check out the `development` branch and configure, compile and install it:
+### 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 us the `git` method. The reason it that when you use `git`, the build process can incorporate the `git` commit hash in the version information. 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 hash:
+4.0-dev-138-g2789572-AirPlay2-OpenSSL-Avahi-ALSA-soxr-metadata-dbus-sysconfdir:/etc
+
+Version without git hash:
+4.0-dev-AirPlay2-OpenSSL-Avahi-ALSA-soxr-metadata-dbus-sysconfdir:/etc
+```
+
+#### Build and Install
+Download Shairport Sync, check out the `development` branch and configure, compile and install it:
```
$ git clone git@github.com:aillwee/shairport-sync.git
$ cd shairport-sync
```
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:
```
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 ###
+#### Automatic Start
To enable Shairport Sync to start automatically on boot up:
```
# systemctl start shairport-sync
```
-### Running From the Command Line ###
+#### 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:
```
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 ###
+### 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...
-### Restart Your Mac! ###
+### Restart Your Mac!
-At the time of writing, there seems to be a bug in the Mac Music app. It appears that, when the Mac has been awoken after sleeping, the Music app may not fully reawaken, and it will be unable to drive AirPlay 2 devices for more than a few seconds. The only know solution is to reboot.
+At the time of writing, there seems to be a bug in the Mac Music app, particularly on Apple silicon Macs. It appears that, if the Mac has been sleeping, the AirPlay 2 infrastructure is not fully reenabled, and it will be unable to drive AirPlay 2 devices for more than a few seconds. The only know solution is to reboot.
projects / thirdparty / shairport-sync.git / commitdiff
