mikebrady/shairport-sync repository overview

⁠Shairport Sync

Shairport Sync is an AirPlay 2 audio player. The "Classic" version provides classic AirPlay (aka "AirPlay 1") capability, similar to previous versions of Shairport Sync. For more information, please visit its GitHub repository⁠.

Try it out!

Assuming you have Docker installed on your Linux system, you can try out Shairport Sync by entering the following in a terminal window (don't enter the $ – it's the command line prompt):

$ docker run --rm --cap-add=SYS_NICE --net host --device /dev/snd mikebrady/shairport-sync:latest

(To try out the development version, substitute development for latest above.)

The first time you run it, it will download the Docker image first, so you'll get something like this:

Unable to find image 'mikebrady/shairport-sync:latest' locally
latest: Pulling from mikebrady/shairport-sync:latest
d62bb7eb03b5: Pull complete 
870e870d46ff: Pull complete 
0c12ec19e4f3: Pull complete 
6df3ea12d3a5: Pull complete 
Digest: sha256:5a59bde7b859cdfbe70a1e8d746464c77a402ef88010146fe6aa189dc0f3f0da
Status: Downloaded newer image for mikebrady/shairport-sync:latest

Once downloaded, it will run until you stop it. The next time, it won't have to download the image so it'll just start running immediately.

While it's running, your AirPlay device (e.g. iPhone) should be able to find a new AirPlay destination – it'll have your system's hostname. Connect to it and play something. The audio should come out on the system's default audio device. You may have to adjust the volume on your AirPlay device and on your system.

If your system has a firewall (e.g. Fedora has a firewall by default), it may interfere with AirPlay. For testing purposes, consider temporarily turning it completely off. The list of ports needed for access is here⁠⁠, but it may be incomplete.

That's it!

Basic Usage

$ docker run --cap-add=SYS_NICE -d --restart unless-stopped --net host --device /dev/snd \
    mikebrady/shairport-sync

The above command will run the latest version of Shairport Sync as a daemon in a Docker container, accessing the computer's ALSA audio infrastructure. It will send audio to the default output device but without controlling any built-in hardware mixers (i.e. volume controls) the device might have. The AirPlay service name will be the host's hostname with the first letter capitalised, e.g. Ubuntu.

The command below will run the latest version of "classic" Shairport Sync, which uses to the older "classic" AirPlay (aka "AirPlay 1") protocol.

$ docker run --cap-add=SYS_NICE -d --restart unless-stopped --net host --device /dev/snd \
    mikebrady/shairport-sync:classic

Options

Any options you add to the command above will be passed to Shairport Sync -- please go to the GitHub repository⁠ for more details of the options. Here is an example:

$ docker run --cap-add=SYS_NICE -d --restart unless-stopped --net host --device /dev/snd \
    mikebrady/shairport-sync -a DenSystem -- -d hw:0 -c PCM

This will send audio to ALSA hardware device hw:0 and use the device's mixer control called PCM to control output volume. The service will be visible as DenSystem on the network.

Configuration File

Edit the configuration file /etc/shairport-sync.conf in the container (or use the -v option to mirror an external copy of shairport-sync.conf in to /etc/shairport-sync.conf) to get access to the full range of configuration options.

Tags

• latest and classic are the most recent releases of Shairport Sync and Shairport Sync (Classic) respectively.
• rolling and rolling-classic contain the latest updates to the master branch that may not yet have made their way into a release.
• development and development-classic are the most recent builds on the development branch and are likely to be less stable and updated frequently.
• Version Number tags (e.g. 4.1, 4.1-classic) for individual releases.

Please check the "Tags" tab for a full list of tags.

Host Firewall

If your host system runs a firewall (for example, desktop Fedora has a firewall running by default), be sure to permit ports needed by Shairport Sync. See here⁠ for a discussion aimed at the ufw firewall -- though the ports list is relevant to all firewalls.

Exploratory Tool

A tool called dacquery, available here⁠ as a Docker image, will list out audio devices that might be suitable for Shairport Sync.

Advanced Usage

Rather than run the Docker image as a daemon, it can be run on the command line. Remember also that trailing command line options are sent to the shairport-sync application.

For example, to get the help text:

$ docker run --rm --cap-add=SYS_NICE --net host --device /dev/snd mikebrady/shairport-sync:latest --help

That --help command is passed to shairport-sync and so you'll get Shairport Sync's help text (along with messages from parts of the Docker system). After emitting the help text, Shairport Sync -- and thus the entire image -- will shut down.

As another example, to run Shairport Sync and see some playback statistics on the command line as audio is played:

docker run --rm --cap-add=SYS_NICE --net host --device /dev/snd mikebrady/shairport-sync:latest --statistics

When play starts, you'll get playback statistics from Shairport Sync along with messages from parts of the Docker system. In this case, Shairport Sync will run indefinitely.

Wait, there's more...

Lots more information at the GitHub repository⁠.