shairport-sync(1)

📦
version 5.5.1 · 4 versions
, in alpine 3.24

shairport-sync 🎶💖

okay so bestie, welcome to the shairport-sync(1) manual page — General Commands Manual energy, but make it cute ✨. We're talking AirPlay and AirPlay 2 audio player realness, and every technical detail is staying exactly where it belongs. no cap 💅

🌸 NAME 🌸

shairport-sync — AirPlay and AirPlay 2 Audio Player 🎵

✨ SYNOPSIS ✨

       shairport-sync [-djvw] [-a service-name | --name=service-name] [-B
       command | --onstart=command] [-c configurationfile |
       --configfile=configurationfile] [-d | --daemon] [--dbus-default-message-
       bus=bus] [-E command | --onstop=command] [-g | --get-cover-art] [-j |
       --justDaemoniseNoPIDFile] [--logOutputLevel] [-L latency |
       --latency=latency] [-m backend | --mdns=backend] [-M | --metadata-
       enable] [-o backend | --output=backend] [-p port | --port=port]
       [--password=secret] [-r threshold | --resync=threshold] [--service-
       type=type] [--statistics] [-S mode | --stuffing=mode] [-t timeout |
       --timeout=timeout] [--tolerance=frames] [-v | --verbose] [-w | --wait-
       cmd] [-- audio_backend_options]

       shairport-sync -X | --displayConfig

       shairport-sync -h

       shairport-sync -k

       shairport-sync -V

🦋 DESCRIPTION 🦋

Shairport Sync plays AirPlay audio. It can be built to stream either from "classic" AirPlay (aka "AirPlay 1") or from AirPlay 2 devices 🎧✨

AirPlay 2 support is limited, and AirPlay 2 from iTunes for Windows is not supported. For AirPlay 2 operation, a companion program called nqptp must be installed. Important bestie detail: that's non-negotiable for AirPlay 2 💅

Please see https://github.com/mikebrady/shairport-sync for details.

The name of the Shairport Sync executable is shairport-sync.

🛠️ CONFIGURATION FILE SETTINGS 🛠️

You should use the configuration file for setting up Shairport Sync because -- apart from a few special-purpose commands -- it has a much richer set of options than are available on the command line. This file is usually shairport-sync.conf and is generally located in the System Configuration Directory, which is normally the /etc directory in Linux or the /usr/local/etc directory in BSD unixes. You may need to have root privileges to modify it 🔐

Note: Shairport Sync may have been compiled to use a different configuration directory. You can determine which by performing the command $ shairport-sync -V. The last item in the output string is the value of the sysconfdir, i.e. the System Configuration Directory. iykyk 👑

Within the configuration file, settings are organised into groups, for example, there is a general group of standard settings, and there is an alsa group with settings that pertain to the ALSA back end. Here is an example of a typical configuration file:

general = {

name = "Mike's Boombox";

};

alsa = {

output_device = "hw:0";

mixer_control_name = "PCM";

};

Users generally only need to set (1) the service name and (2) the output device. If the name setting is omitted, the service name is derived from the system's hostname. By default, the ALSA backend will be chosen if included in the build. If the (alsa) output device has a mixer that can be used for volume control, then (3) the mixer name should be specified.

It is important to do this if the mixer exists. Otherwise, the maximum output from the output device will be whatever setting the mixer happens to have, which will be a matter of chance and which could be very low or even silent. Like, don't skip this one, fr fr. 😭

A sample configuration file with all possible settings, but with all of them commented out, is installed at shairport-sync.conf.sample, within the System Configuration Directory -- /etc in Linux, /usr/local/etc in BSD unixes.

The sample configuration file includes extensive documentation of the settings. and is also available at https://github.com/mikebrady/shairport-sync/blob/master/scripts/shairport-sync.conf. Please refer to it for the most up-to-date information on configuration file settings. That's the glow-up source of truth ✨

💅 OPTIONS 💅

There are two kinds of command-line options for shairport-sync: regular program options and audio backend options. Program options are always listed first, followed by any audio backend options, preceded by a -- symbol.

See the EXAMPLES section for sample usages. 🫶

✨ PROGRAM OPTIONS ✨

Okay bestie, these ones are for shairport-sync itself — like, the actual program, not the audio bits. Let's go 💅

  • -a service name, --name=service name — uses this service name to identify this player in iTunes and friends. The following substitutions are allowed: %h for the computer's hostname, %H for the computer's hostname with the first letter capitalised (ASCII only, so don't come at it with the fancy stuff), %v for the shairport-sync version number, e.g. "3.0.1", and %V for the shairport-sync version string, e.g. "3.0.1-OpenSSL-Avahi-ALSA-soxr-metadata-sysconfdir:/etc". The default is "%H", which gets replaced by the hostname with the first letter capitalised. Iconic default behaviour, honestly 🎀
  • -B program, --on-start=program — runs program when playback is about to begin. Give it the full path, like /usr/bin/logger. Executable scripts work too, but they must have the appropriate shebang (#!/bin/sh) in the headline — no shebang, no slay. If you want shairport-sync to wait until the command has completed before starting to play, pick the -w option as well, okay? 🫶
  • -c filename, --configfile=filename — reads configuration settings from filename. The default is to read them from shairport-sync.conf in the System Configuration Directory — that's /etc on Linux and /usr/local/etc on BSD unixes. For info about the settings themselves, peep the "Configuration File Settings" section above ⭐
  • -d, --daemon — tells shairport-sync to demonise itself 💀 It writes its Process ID (PID) to a file, usually at /var/run/shairport-sync/shairport-sync.pid, which the -k, -D and -R options then use to locate the daemon later. See also the -j option. Heads up: only available if shairport-sync has been compiled with libdaemon support.
  • --dbus-default-message-bus=bus — use the bus specified for the native D-Bus and MPRIS interfaces. The bus has to be system or session. This option is only available if Shairport Sync is built with the D-Bus or MPRIS interface.
  • -E program, --on-stop=program — runs program when playback has ended. Full path please, e.g. /usr/bin/logger. Executable scripts are fine, but again they must have the appropriate shebang (#!/bin/sh) in the headline. If you want shairport-sync to wait until the command has completed before continuing, select the -w option as well 💖
  • -g, --get-coverart — this one requires the -M | --metadata-enable option to be set, and it lets shairport-sync request cover art from the source and process it as metadata. Cover art, bestie 🎨✨
  • -h, --help — prints a brief help message and exits. The classic.
  • -j | justDaemoniseNoPIDFile — tells shairport-sync to demonise itself. Unlike the -d option, it will not write a Process ID (PID) to a file — it just (hence the "j", get it?) demonises itself. Only available if shairport-sync has been compiled with libdaemon support.
  • -k | --kill — kills the shairport-sync daemon and exits. This requires that the daemon has written its PID to an agreed file — see the -d option. Only available if shairport-sync has been compiled with libdaemon support. Bye bestie 💀👋
  • --logOutputLevel — use this to log the volume level whenever the volume is changed. It's lowkey useful if you're trying to figure out a suitable value for the maximum volume level. Note: not available as a configuration file setting.
  • -L | --latency=latency — sets the default latency, in frames, for audio coming from an unidentified source or from an iTunes Version 9 or earlier source. The standard value for the default latency is 88,200 frames, where there are 44,100 frames to the second. 🫧
⚠️ Please note that this feature is deprecated and will be removed in a future version of shairport-sync. So don't get too attached, babe.
  • -M | --metadata-enable — asks the client to send metadata. It gets sent, along with metadata generated by shairport-sync itself, to a pipe and will also be sent as UDP packets. If you add the -g | --get-cover-art then cover art is included, where available. For a sample metadata reader, see https://github.com/mikebrady/shairport-sync-metadata-reader 👀
  • --metadata-pipename=pathname — specifies the path name for the metadata pipe. Important: shairport-sync will need write permission on that directory and the pipe. The default is /tmp/shairport-sync-metadata. Fun fact: if you rename the shairport-sync executable, the default pipe name will change accordingly 🌀
  • -m mdnsbackend, --mdns=mdnsbackend — forces the use of the specified mDNS backend to advertise the player on the network. The default is to try all mDNS backends in order until one works. Persistence, honestly 💪
  • -o outputbackend, --output=outputbackend — forces the use of the specified output backend to play the audio. The default is to try the first one.
  • -p port, --port=port — listens for play requests on port. The default is to use port 5000 for AirPlay and 7000 for AirPlay 2.
  • --password=secret — requires the password secret to be able to connect and stream to the service. Small catch: this only works for AirPlay and not for AirPlay 2 🙈
  • -r threshold, --resync=threshold — resynchronises if timings differ by more than threshold frames. If the output timing differs from the source timing by more than the threshold, output gets muted and a full resynchronisation happens. The default threshold is 2,205 frames, i.e. 50 milliseconds. Specify 0 to disable resynchronisation.
⚠️ This setting is deprecated and will be removed in a future version of shairport-sync.
  • --service-type=type — on an AirPlay-2-capable Shairport Sync, if you need to offer only the older "classic" AirPlay service (sometimes called AirPlay 1), set --service-type=classic. A potential use of this would be Apple Music on Windows, which is not compatible with the AirPlay 2 service offered by Shairport Sync, but which is compatible with the classic-only service. To offer AirPlay 2 service only, set --service-type=airplay2 (note that this requires NQPTP). Set --service-type=auto to let Shairport Sync choose AirPlay 2 service if NQPTP is present, or classic AirPlay service if not, with "(Classic)" appended to the default service name. Choose your fighter ✨
  • --statistics — prints some performance information to STDERR. Numbers! Metrics! We love a data moment 📊
  • -S mode, --stuffing=mode — interpolates ("stuffs") the audio stream using mode. "Stuffing" is the whole process of adding or removing frames of audio to or from the stream sent to the output device to keep it synchronised with the player. The vernier mode is normally almost completely inaudible and suitable for low-powered devices. An alternative mode, soxr, is less obtrusive but requires much more processing power — for this mode, support for libsoxr, the SoX Resampler Library, must be selected when shairport-sync is built. The basic mode is also suitable for low-powered devices, but vernier is better. The default setting, auto, lets Shairport Sync choose soxr mode if the system is powerful enough. She's adaptive, she's flexible 💅
  • -t timeout, --timeout=timeout — exits play mode if the stream disappears for more than timeout seconds. When shairport-sync plays an audio stream it starts a play session and will return a busy signal to any other sources that attempt to use it. If the audio stream disappears for longer than timeout seconds, the play session gets terminated. If you specify a timeout of 0, shairport-sync will never signal that it's busy and will not prevent other sources from "barging in" on an existing play session — chaotic, but okay. The default value is 120 seconds.
  • --tolerance=frames — allows playback to be up to frames out of exact synchronization before attempting to correct it. The default is 88 frames, 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 option to monitor correction levels — corrections should not greatly exceed net corrections.
⚠️ This setting is deprecated and will be removed in a future version of shairport-sync.
  • -V, --version — prints version information and exits 🎀
  • -v, --verbose — prints debug information to STDERR. Repeat up to three times (i.e. -vv or -vvv) for more detail. But bestie, use -vvv very sparingly — it is really noisy 😭🔊
  • -w, --wait-cmd — waits for commands specified using -B or -E to complete before continuing execution. Patience is a virtue, periodt.
  • -X, --displayConfig — this logs information relating to the configuration of Shairport Sync. Genuinely can be very useful for debugging. What gets logged: some host OS info, the Shairport Sync version string (which tells you the build options used when shairport-sync was built), the contents of the command line that invoked Shairport Sync, the name of the configuration file, and the active settings therein. If this is the only option on the command line, shairport-sync will terminate after displaying all that info. Show and tell 🔍✨

🎧 AUDIO BACKEND OPTIONS 🎧

So, Audio Backend Options are command-line options that get passed to the chosen audio backend. They're always preceded by the -- symbol, which introduces them and separates them from any preceding program options. Why? Because that way, option letters can be used as program options and reused as audio backend options without any ambiguity — clever, right? No cap, that's a serve 🧠💅

Audio backends get listed with their corresponding Audio Backend Options in the help text provided by the help (-h or --help) option, so go check there if you wanna see the full menu 🌈

🎀 EXAMPLES 🎀

Okay so here’s a slightly contrived example — the manpage literally calls it that, we’re not being shady:

shairport-sync -a "Joe's Stereo" -o alsa -- -d hw:1,0 -m hw:1 -c PCM

Break it down bestie: the program will be visible as "Joe's Stereo" because of -a "Joe's Stereo". The program option -o alsa says the alsa backend should be used, so audio goes out into the ALSA audio subsystem. The audio backend options after the -- separator get passed to the alsa backend, and they say the audio will be output on subdevice 0 of soundcard 1 (-d hw:1,0) and will use that same soundcard’s mixer (-m hw:1) with the level control named "PCM" (-c "PCM").

But wait — this example is slightly contrived. Their words, not mine. Here’s why:

  • If the alsa backend was included in the build, it’s the default, so it doesn’t need to be specified and the -o alsa option could be omitted.
  • Subdevice 0 is the default for a soundcard, so the output device could simply be written -d hw:1.
  • When a mixer name is given (-c "PCM"), the default is that the mixer is on the output device, so the -m hw:1 is unnecessary here.

Use those defaults and simplifications and you get this command:

shairport-sync -a "Joe's Stereo" -- -d hw:1 -c PCM

🌈 NOTE 🌈

The dacquery utility (https://github.com/mikebrady/dacquery) might be useful for discovering the properties of your system’s DACs. Go peek — it’s giving helpful.

👑 CREDITS 👑

Mike Brady (https://github.com/mikebrady) developed Shairport Sync from Shairport by James Wah (https://github.com/abrasive). Respect the lineage, periodt.

💅 COMMENTS 💅

This man page was written using xml2man(1) by Oliver Kurth.

And that’s a wrap on the whole page, bestie! Footer vibes: Manuals source, User section, shairport-sync(1) page — consider that your cute sign-off instead of the copied footer line. Mwah 💋

📦 where this page comes from