Provided by: shairport-sync_4.3.7-1_amd64 
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] [-E command | --onstop=command] [-g |
--get-cover-art] [-j | --justDaemoniseNoPIDFile] [--logOutputLevel] [--log-to-syslog] [-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] [--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.
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.)
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.
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.
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
Program Options are used by shairport-sync itself.
-a service name | --name=service name
Use this service name to identify this player in iTunes, etc.
The following substitutions are allowed: %h for the computer's hostname, %H for the computer's
hostname with the first letter capitalised (ASCII only), %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 is replaced by the hostname with the first letter capitalised.
-B program | --on-start=program
Execute program when playback is about to begin. Specify the full path to the program, e.g.
/usr/bin/logger. Executable scripts can be used, but they must have the appropriate shebang
(#!/bin/sh) in the headline.
If you want shairport-sync to wait until the command has completed before starting to play, select
the -w option as well.
-c filename | --configfile=filename
Read configuration settings from filename. The default is to read them from the shairport-
sync.conf in the System Configuration Directory -- /etc in Linux, /usr/local/etc in BSD unixes.
For information about configuration settings, see the "Configuration File Settings" section above.
-d | --daemon
Instruct shairport-sync to demonise itself. It will write its Process ID (PID) to a file, usually
at /var/run/shairport-sync/shairport-sync.pid, which is used by the -k, -D and -R options to
locate the daemon at a later time. See also the -j option. Only available if shairport-sync has
been compiled with libdaemon support.
-E program | --on-stop=program
Execute program when playback has ended. Specify the full path to the program, e.g.
/usr/bin/logger. Executable scripts can be used, but 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 option requires the -M | --metadata-enable option to be set, and enables shairport-sync to
request cover art from the source and to process it as metadata.
-h | --help
Print brief help message and exit.
-j | justDaemoniseNoPIDFile
Instruct shairport-sync to demonise itself. Unlike the -d option, it will not write a Process ID
(PID) to a file -- it will just (hence the "j") demonise itself. Only available if shairport-sync
has been compiled with libdaemon support.
-k | --kill
Kill the shairport-sync daemon and exit. (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.)
--logOutputLevel
Use this to log the volume level when the volume is changed. It may be useful if you are trying to
determine a suitable value for the maximum volume level. Not available as a configuration file
setting.
--log-to-syslog
Warnings, error messages and messages are sent, by default, to STDERR. Use this option to route
these messages to the syslog instead. This is intended for use when Shairport Sync is operating as
a daemon.
See also --displayConfig.
-L | --latency=latency
Use this to set 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.
-M | --metadata-enable
Ask the client to send metadata. It will be 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 included, where available. See https://github.com/mikebrady/shairport-sync-metadata-
reader for a sample metadata reader.
--metadata-pipename=pathname
Specify the path name for the metadata pipe. Note that shairport-sync will need write permission
on that directory and pipe. The default is /tmp/shairport-sync-metadata. If you rename the
shairport-sync executable, the default pipe name will change accordingly.
-m mdnsbackend | --mdns=mdnsbackend
Force 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.
-o outputbackend | --output=outputbackend
Force the use of the specified output backend to play the audio. The default is to try the first
one.
-p port | --port=port
Listen for play requests on port. The default is to use port 5000 for AirPlay and 7000 for AirPlay
2.
--password=secret
Require the password secret to be able to connect and stream to the service. (This only works for
AirPlay and not for AirPlay 2.)
-r threshold | --resync=threshold
Resynchronise if timings differ by more than threshold frames. If the output timing differs from
the source timing by more than the threshold, output will be muted and a full resynchronisation
will occur. 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.
--statistics
Print some performance information to STDERR, or to syslog if the -log-to-syslog command line
option is also chosen.
-S mode | --stuffing=mode
Interpolate ("stuff") the audio stream using the mode. "Stuffing" refers to the process of adding
or removing frames of audio to or from the stream sent to the output device in order to keep it
synchronised with the player. The basic mode is normally almost completely inaudible. The
alternative mode, soxr, is even 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 default setting, auto, allows Shairport Sync to choose soxr mode if the system is
powerful enough.
-t timeout | --timeout=timeout
Exit 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 will be terminated. If you specify a timeout time of 0,
shairport-sync will never signal that it is busy and will not prevent other sources from "barging
in" on an existing play session. The default value is 120 seconds.
--tolerance=frames
Allow 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
Print version information and exit.
-v | --verbose
Print debug information to the STDERR, or to syslog if the -log-to-syslog command line option is
also chosen. Repeat up to three times (i.e. -vv or -vvv) for more detail. You should use -vvv very
sparingly -- it is really noisy.
-w | --wait-cmd
Wait for commands specified using -B or -E to complete before continuing execution.
-X | --displayConfig
This logs information relating to the configuration of Shairport Sync. It can be very useful for
debugging. The information logged is some host OS information, the Shairport Sync version string
(which indicates 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 the
information.
AUDIO BACKEND OPTIONS
Audio Backend Options are command-line options that are passed to the chosen audio backend. They are
always preceded by the -- symbol to introduce them and to separate them from any preceding program
options. In this way, option letters can be used as program options and reused as audio backend options
without ambiguity.
Audio backends are listed with their corresponding Audio Backend Options in the help text provided by the
help (-h or --help) option.
EXAMPLES
Here is a slightly contrived example:
shairport-sync -a "Joe's Stereo" -o alsa -- -d hw:1,0 -m hw:1 -c PCM
The program will be visible as "Joe's Stereo" ( -a "Joe's Stereo" ). The program option -o alsa specifies
that the alsa backend be used, thus that audio should be output into the ALSA audio subsystem. The audio
backend options following the -- separator are passed to the alsa backend and specify that the audio will
be output on subdevice 0 of soundcard 1 ( -d hw:1,0 ) and will take advantage of the same sound card's
mixer ( -m hw:1 ) using the level control named "PCM" ( -c "PCM" ).
The example above is slightly contrived: Firstly, if the alsa backend has been included in the build, it
will be the default, so it doesn't need to be specified and the -o alsa option could be omitted.
Secondly, subdevice 0 is the default for a soundcard, so the output device could simply be written -d
hw:1. Thirdly, 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. Using these defaults and simplifications gives the following
command:
shairport-sync -a "Joe's Stereo" -- -d hw:1 -c PCM
CREDITS
Mike Brady (https://github.com/mikebrady) developed Shairport Sync from Shairport by James Wah
(https://github.com/abrasive).
COMMENTS
This man page was written using xml2man(1) by Oliver Kurth.
Manuals User shairport-sync(1)