Ubuntu Manpage: shairport-sync - Synchronised Audio Player for iTunes / AirPlay

Provided by: shairport-sync_3.3.8-1build5_amd64

NAME

       shairport-sync - Synchronised Audio Player for iTunes / AirPlay

SYNOPSIS

       shairport-sync  [-djvuw]  [-a  name]  [-A latency] [-B command] [-c configurationfile] [-E
       command]  [--get-cover-art]  [--logOutputLevel]  [-L  latency]   [-m   backend]   [--meta-
       dir=directory]  [-o  backend]  [--password=secret] [-r threshold] [--statistics] [-S mode]
       [-t timeout] [--tolerance=frames] [-- audio_backend_options]

       shairport-sync -k

       shairport-sync -h

       shairport-sync -V

DESCRIPTION

Shairport Sync plays audio streamed from iTunes or from an AirPlay device to an ALSA-
compatible audio output device (available on Linux and FreeBSD), to a "sndio" output
device (available on OpenBSD, FreeBSD and Linux), to a PulseAudio output stream or to Jack
Audio.

Shairport Sync offers full audio synchronisation. Full audio synchronisation means that
audio is played on the output device at exactly the time specified by the audio source.
This means that if many devices are playing the same stream at the same time, all the
outputs will stay in synchrony with one another. This allows multiple devices to play the
same source without getting out of step with one another, enabling, for example,
simultaneous multi-room operation.

Shairport Sync can stream synchronised audio to a unix pipe or to standard output, or to
audio systems that do not provide timing information. This could perhaps be described as
partial audio synchronisation, where synchronised audio is provided by Shairport Sync, but
what happens to it in the subsequent processing chain, before it reaches the listener's
ear, is outside the control of shairport-sync.

Shairport Sync can be compiled to stream metadata, including cover art, to a pipe or
socket.

Shairport Sync can be compiled to offer a standard MPRIS interface, a "native" D-Bus
interface and an MQTT client interface. Through these interfaces, it can provide metadata,
including cover art, and can offer remote control of the audio source.

Settings can be made using the configuration file (recommended for all new installations)
or by using command-line options.

The name of the Shairport Sync executable is shairport-sync. Both names are used in these
man pages.

CONFIGURATION FILE SETTINGS

You should use the configuration file for setting up Shairport Sync. 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. One of the items 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";

password = "secret";

output_backend = "alsa";

};

alsa = {

output_device = "hw:0";

mixer_control_name = "PCM";

};

Most settings have sensible default values, so -- as in the example above -- users
generally only need to set (1) the service name, (2) a password (if desired) and (3) the
output device. If the output device has a mixer that can be used for volume control, then
(4) 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.

To retain backwards compatibility with previous versions of shairport-sync you can use
still use command line options, but any new features, etc. will be available only via
configuration file settings.

The configuration file is processed using the libconfig library -- see
http://www.hyperrealm.com/libconfig/libconfig_manual.html.

"GENERAL" SETTINGS
These are the settings available within the general group:

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.3.6" and %V for the shairport-sync version
string, e.g. "3.3.6-OpenSSL-Avahi-ALSA-soxr-metadata-sysconfdir:/etc".

The default is "%H", which is replaced by the hostname with the first letter
capitalised.

password="password";
Require the password password to connect to the service. If you leave this setting
commented out, no password is needed.

interpolation="mode";
Interpolate, or "stuff", the audio stream using the mode. Interpolation here refers
to the process of adding or removing frames of audio to or from the stream sent to
the output device to keep it exactly 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
compiled. The default setting is "auto", which will choose "soxr" if support for it
has been compiled into the build of Shairport Synce and if the CPU is fast enough.
Otherwise, "basic" stuffing will be chosen.

output_backend="backend";
shairport-sync has a number of modules of code ("backends") through which audio is
output. Normally, the first audio backend that works is selected. This setting
forces the selection of the specific audio backend. Perform the command shairport-
sync -h to get a list of available audio backends -- the default is the first on
this list. Only the "alsa", "sndio" and "pa" backends support synchronisation.

mdns_backend="backend";
shairport-sync has a number of modules of code ("backends") for interacting with
the mDNS service to be used to advertise itself. Normally, the first mDNS backend
that works is selected. This setting forces the selection of the specific mDNS
backend. The default is "avahi". Perform the command shairport-sync -h to get a
list of available mDNS modules.

port=portnumber;
Use this to specify the portnumber shairport-sync uses to listen for service
requests from iTunes, etc. The default is port 5000.

udp_port_base=portnumber;
When shairport-sync starts to play audio, it establises three UDP connections to
the audio source. Use this setting to specify the starting portnumber for these
three ports. It will pick the first three unused ports starting from portnumber.
The default is port 6001.

udp_port_range=range;
Use this in conjunction with the previous setting to specify the range of ports
that can be checked for availability. Only three ports are needed. The default is
100, thus 100 ports will be checked from port 6001 upwards until three are found.

drift_tolerance_in_seconds=seconds;
Allow playback to drift up to seconds out of exact synchronization before
attempting to correct it. The default is 0.002 seconds, i.e. 2 milliseconds. 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 setting to
monitor correction levels. Corrections should not greatly exceed net corrections.
This setting replaces the deprecated drift setting.

resync_threshold_in_seconds=threshold;
Resynchronise if timings differ by more than threshold seconds. 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 0.050
seconds, i.e. 50 milliseconds. Specify 0.0 to disable resynchronisation. This
setting replaces the deprecated resync_threshold setting.

ignore_volume_control="choice";
Set this choice to "yes" if you want the volume to be at 100% no matter what the
source's volume control is set to. This might be useful if you want to set the
volume on the output device, independently of the setting at the source. The
default is "no".

volume_range_db=dBvalue;
Use this dBvalue to reduce or increase the attenuation range, in decibels, between
the minimum and maximum volume.

For example, if a mixer has a minimum volume of -80 dB and a maximum of +20 dB, you
might wish to use only 60 dB of the 100 dB available. This might be because the
sound becomes inaudible at the lowest setting and unbearably loud at the highest
setting -- indeed, many domestic HiFi systems have a volume control range of just
60 to 80dB.

Another potential use might be where the range specified by the mixer does not
match the capabilities of the device. For example, the Raspberry Pi's DAC that
feeds the built-in audio jack claims a range of 106 dB but has a useful range of
only about 30 dB. The setting allows you to specify the maximum range from highest
to lowest. The range suggested for the Raspberry Pi's built-in audio DAC, which
feeds the headphone jack, is 30. Using it in this case gives the volume control a
much more useful range of settings.

As a third example, you can actually extend the range provided by a mixer. Many
cheaper DACs have hardware mixers that offer a restricted attenuation range. If you
specify a volume range greater than the range of the mixer, software attenuation
and hardware attenuation will be combined to give the specified range.

If you omit this setting, the native range of the mixer is used.

volume_max_db=dBvalue;
Specify the maximum output level to be used with the hardware mixer, if used. If no
hardware mixed is used, this setting specifies the maximum setting permissible in
the software mixer, which has an attenuation range from 0.0 dB down to -96.3 dB.

volume_control_profile="choice";
Use this advanced setting to specify how the airplay volume is transferred to the
mixer volume. The "standard" profile, which is the default, makes the volume change
more quickly at lower volumes and slower at higher volumes. Choose the "flat"
profile to makes the volume change at the same rate at all volume levels.

volume_range_combined_hardware_priority= "choice";
Use this advanced setting to specify how to combine the hardware attenuator with
software attenuation to provide a greater attenuation range than the hardware
attenuator alone can provide. Choosing "yes" means that when attenuation is
required, the hardware attenuator will be used in preference. If more attenuation
than it can provide is needed, the hardware attenuator is set to its greatest
attenuation and software attenuation is added.

For example, if 40 dB of attenuation is required and the hardware attenuator offers
a maximum of 30 dB, then the hardware attenuator will be set to give 30 dB
attenuation and 10 dB of software attenuation will be added.

Unfortunately, certain hardware attenuators will mute at their greatest
attenuation, so can't be combined with software attenuation in this way. Choosing
"no" means that software attenuation is used to bring the remaining attenuation
required into the range offered by the hardware attenuator. This is the default.

run_this_when_volume_is_set= "/full/path/to/application/and/args";
Here you can specify a program and its arguments that will be run when the volume
is set or changed. Be careful to include the full path to the application. The
application must be marked as executable and, if it is a script, its first line
must begin with the standard shebang #!/bin/... as appropriate.

The desired AirPlay volume is appended to the end of the command line -- leave a
space at the end of the command line you specify here if you want it treated as an
extra argument. AirPlay volume goes from 0.0 to -30.0 and -144.0 means "mute".

regtype="regTypeString";
Use this advanced setting to set the service type and transport to be advertised by
Zeroconf/Bonjour. Default is "_raop._tcp".

playback_mode="mode";
The mode can be "stereo", "mono", "reverse stereo", "both left" or "both right".
Default is "stereo". Note that dither will be added to the signal in the mono mode.

alac_decoder="decodername";
This can be "hammerton" or "apple". This advanced setting allows you to choose the
original Shairport decoder by David Hammerton or the Apple Lossless Audio Codec
(ALAC) decoder written by Apple. Shairport Sync must have been compiled with the
configuration setting "--with-apple-alac" and the Apple ALAC decoder library must
be present for this to work.

interface="name";
Use this advanced setting if you want to confine Shairport Sync to the named
interface. Leave it commented out to get the default behaviour.

audio_backend_latency_offset_in_seconds= offset_in_seconds;
Set this offset_in_seconds to compensate for a fixed delay in the audio back end.
For example, if the output device delays by 100 ms, set this to -0.1.

audio_backend_buffer_desired_length_in_seconds= length_in_seconds;
Use this length_in_seconds to set the desired length of the queue of audio frames
in the backend's output buffer.

The default is 0.15 seconds for the ALSA backend, 0.35 seconds for the PA backend
and one second for all other backends.

If this value is set too small, underflow may occur on low-powered machines. If set
too large, the response times to the volume control may become excessive, or it may
exceed the backend's buffer size. It may need to be larger on low-powered machines
that are also performing other tasks, such as processing metadata.

audio_backend_buffer_interpolation_threshold_in_seconds= time_in_seconds;
This is an advanced feature. If the length of the audio backend buffer size drops
below this, it's a sign that shairport sync can not process frames of audio quickly
enough. It this threshold is reached, shairport sync will stop using time-consuming
interpolation like soxr to avoid underruns.

audio_backend_silent_lead_in_time= lead_in_time_in_seconds;
This is an advanced setting. Use the lead_in_time_in_seconds to set the desired
length of the period of silence (a "silent lead-in") played before a play session
begins.

The purpose of this silent lead-in is to give the backend sufficient time to
prepare for operation and to make an estimate (and, importantly, to correct the
estimate) of the exact time at which to begin playing audio to achieve initial
synchronisation. The value can be from 0.0 up to a maximum of either 4.0 seconds.
The actual duration will be close to the setting but can not exceed the latency set
by the client, usually 2 seconds or a little more.

If the value chosen is too short for synchronised backends such as the ALSA, sndio
or PA backends, then audio will not be synchronised correctly at the start of play.
The default is to have a silent lead-in of approximately the same time as the
latency set by the client.

dbus_service_bus= "bus_name";
If shairport sync is compiled with the D-Bus interface, it can offer it on the
"system" or the "session" D-Bus "bus". Use this to specify which. The default is to
use the "system" bus.

mpris_service_bus= "bus_name";
If shairport sync is compiled with the MPRIS interface, it can offer the service on
the "system" or the "session" D-Bus "bus". Use this to specify which. The default
is to use the "system" bus.

"SESSIONCONTROL" SETTINGS

run_this_before_play_begins="/path/to/application and args";
Here you can specify a program and its arguments that will be run just before a
play session begins. Be careful to include the full path to the application. The
application must be marked as executable and, if it is a script, its first line
must begin with the standard shebang #!/bin/... as appropriate.

run_this_after_play_ends="/path/to/application and args";
Here you can specify a program and its arguments that will be run just after a play
session ends. Be careful to include the full path to the application. The
application must be marked as executable and, if it is a script, its first line
must begin with the standard shebang #!/bin/... as appropriate.

run_this_before_entering_active_state="/path/to/application and args";
Here you can specify a program and its arguments that will be run just before
shairport-sync goes active.

Shairport Sync goes "active" when a play session starts. When the play session
ends, the system will stay active until the time specified in the
active_state_timeout setting elapses. If a new play session starts before that, the
system will remain active. Otherwise, the system will go inactive.

Be careful to include the full path to the application. The application must be
marked as executable and, if it is a script, its first line must begin with the
standard shebang #!/bin/... as appropriate.

run_this_after_exiting_active_state="/path/to/application and args";
Here you can specify a program and its arguments that will be run just after
shairport-sync goes inactive (see the previous entry for an explanation of the
idea). Be careful to include the full path to the application. The application must
be marked as executable and, if it is a script, its first line must begin with the
standard shebang #!/bin/... as appropriate.

active_state_timeout=seconds;
After a play session has ended, the system will remain active for seconds seconds.
If a new play session starts before this time has elapsed, the system will remain
active. However, if no new session starts in the interval, the system will go
inactive at the end of it. The default is 10 seconds.

run_this_if_an_unfixable_error_is_detected="/path/to/application and args";
Here you can specify a program and its arguments that will be run if the system
detects an unfixable error. At present, there are two types of unfixable errors.
One is where a play session cannot be terminated. The second is if an output device
has "stalled" -- that is, if an output device refuses to accept any more output
frames.

Although the first problem could, in principle, be fixed by restarting Shairport
Sync, it is usually caused by a malfunctioning output device. Typically, the most
reliable way to recover from either of these errors is to reboot the entire
machine.

wait_for_completion="choice";
Set choice to "yes" to make shairport-sync wait until the programs specified in the
run_this_... settings have completed execution before continuing. The default is
"no".

allow_session_interruption="choice";
If choice is set to "yes", then another source will be able to interrupt an
existing play session and start a new one. When set to "no" (the default), other
devices attempting to interrupt a session will fail, receiving a busy signal.

session_timeout=seconds;
If a play session has been established and the source disappears without warning
(such as a device going out of range of a network) then wait for the number of
seconds specified before ending the session. Once the session has terminated, other
devices can use it. The default is 120 seconds.

"ALSA" SETTINGS
These settings are for the ALSA back end, used to communicate with audio output
devices in the ALSA system. (By the way, you can use tools such as alsamixer or
aplay to discover what devices are available.) Use these settings to select the
output device and the mixer control to be used to control the output volume. You
can additionally set the desired size of the output buffer and you can adjust
overall latency. Here are the alsa group settings:

output_device="output_device";
Use the output device called output_device. The default is the device called
"default".

mixer_control_name="name";
Specify the name of the mixer control to be used by shairport-sync to control the
volume. The mixer control must be on the mixer device, which by default is the
output device. If you do not specify a mixer control name, shairport-sync will
adjust the volume in software.

mixer_device="mixer_device";
By default, the mixer is assumed to be output_device. Use this setting to specify a
device other than the output device.

output_rate=frame rate;
Use this setting to specify the frame rate to output to the ALSA device. Allowable
values are "auto" (default), 44100, 88200, 176400 and 352800. The device must have
the capability to accept the rate you specify. There is no particular reason to use
anything other than 44100 if it is available, and if "auto" is selected, the lowest
of these rates available, starting at 44100, will be selected.

output_format="format";
Use this setting to specify the format that should be used to send data to the ALSA
device. Allowable values are "auto" (default), "U8", "S8", "S16", "S24", "S24_3LE",
"S24_3BE" or "S32". The device must have the capability to accept the format you
specify.

"S" means signed; "U" means unsigned; BE means big-endian and LE means little-
endian. Except where stated (using *LE or *BE), endianness matches that of the
processor. The default is "S16".

If you are using a hardware mixer, S16 is fine, as audio will pass through
Shairport Sync unmodified except for interpolation, but any of the higher-
resolution formats are okay too. If you are using the software mixer, use 32- or
24-bit, if your device is capable of it, in order to get the lowest possible levels
of dither. The "auto" setting will cause Shairport Sync to choose the highest
resolution available.

disable_synchronization="no";
This is an advanced setting and is for debugging only. Set to "yes" to disable
synchronization. Default is "no". If you use it to disable synchronisation, then
sooner or later you'll experience audio glitches due to audio buffer overflow or
underflow.

period_size=number;
Use this optional advanced setting to set the alsa period size near to this value.

buffer_size=number;
Use this optional advanced setting to set the alsa buffer size near to this value.

use_mmap_if_available="yes";
Use this optional advanced setting to control whether MMAP-based output is used to
communicate with the DAC. Default is "yes".

mute_using_playback_switch="no";
This is an advanced setting and the default is "no". If it is set to "yes",
hardware mute will be used where it is available. Set it to "no" to prevent the
hardware mute being used.

If Shairport Sync is sharing the output device with other applications, it is best
to leave this set to "no" for compatibility with those applications.

Another motivation for this is to allow the ALSA function call
"snd_mixer_selem_set_playback_switch_all" to be avoided. It is incorrectly
implemented on certain soundcards, including the emulated card in VMWare Fusion
8.5.

maximum_stall_time=seconds;
If an output device fails to accept any audio frames for more than the time, in
seconds, specified here (0.2 seconds by default), it is considered to have
malfunctioned. It will result in the run_this_if_an_unfixable_error_is_detected
program, if any, being called.

Implemented for the ALSA back end only.

disable_standby_mode="never";
Shairport Sync has a "Disable Standby" feature to eliminate certain faint-but-
annoying audible pops and clicks. When activsted, it prevents an output device from
entering standby mode and thus it minimises standby/busy transitions, which can
sometimes be heard. Use this setting to control when the Disable Standby feature is
active: "never" means it will never be activated, "always" means it will be active
as soon as shairport-sync starts running, and "auto" means it will be active while
shairport-sync is in the "active" state.

"SNDIO" SETTINGS
These settings are for the SNDIO back end, used to communicate with audio output
devices in the SNDIO system.

device="snd/0";
Use this optional setting to specify the name of the output device, e.g. "snd/0".
The default is to use the SNDIO system's default.

rate=44100;
Use this optional setting to specify the output rate in frames per second. Valid
rates are 44100, 88200, 176400 or 352800. The output device must have the
capability to accept data at the specified rate. The default is 44100.

format="S16";
Use this optional setting to specify the output format. Allowable values are "U8",
"S8", "S16", "S24", "S24_3LE", "S24_3BE" or "S32". The device must have the
capability to accept the format you specify.

"S" means signed; "U" means unsigned; BE means big-endian and LE means little-
endian. Except where stated (using *LE or *BE), endianness matches that of the
processor. The default is "S16".

Since the SNDIO backend does not use a hardware mixer for volume control, dither
will be introduced into the output if it is less than full volume. Thus, (unless
you are ignoring the volume control setting), consider using 32- or 24-bit output
if your device is capable of it, to get the lowest possible levels of dither.

Please note that 32- or 24-bit has not been extensively tested on SNDIO.

round=value;
Use this optional advanced setting to specify the period size of the SNDIO channel.
If omitted, a SNDIO system default value will be used.

bufsiz=value;
Use this optional advanced setting to specify the buffer size of the SNDIO channel.
If omitted, a SNDIO system default value will be used.

"PA" SETTINGS
These settings are for the new PulseAudio backend.

application_name="Shairport Sync";
Use this to set the name to appear in the Sounds "Applications" tab when Shairport
Sync is active. The default is the name "Shairport Sync".

"PIPE" SETTINGS
These settings are for the PIPE backend, used to route audio to a named unix pipe.
The audio is in raw CD audio format: PCM 16 bit little endian, 44,100 samples per
second, interleaved stereo.

name="/path/to/pipe";
Use this to specify the name and location of the pipe. The pipe will be created and
opened when shairport-sync starts up and will be closed upon shutdown. Frames of
audio will be sent to the pipe in packets of 352 frames and will be discarded if
the pipe has not have a reader attached. The sender will wait for up to five
seconds for a packet to be written before discarding it.

"STDOUT" SETTINGS
There are no settings for the STDOUT backend.

"AO" SETTINGS
There are no configuration file settings for the AO backend.

"METADATA" SETTINGS
shairport-sync can process metadata provided by the source, such as Track Number,
Album Name, cover art, etc. and can provide additional metadata such as volume
level, pause/resume, etc. It sends the metadata to a pipe, by default
/tmp/shairport-sync-metadata. To process metadata, shairport-sync must have been
compiled with metadata support included. You can check that this is so by running
the command $ shairport-sync -V; the identification string will contain the word
metadata.

Please note that different sources provide different levels of metadata. Some
provide a lot; some provide almost none.

The metadata group of settings allow you to enable metadata handling and to control
certain aspects of it:

enabled="choice";
Set the choice to "yes" to enable shairport-sync to look for metadata from the
audio source and to forward it, along with metadata generated by shairport-sync
itself, to the metadata pipe. The default is "no".

include_cover_art="choice";
Set the choice to "yes" to enable shairport-sync to look for cover art from the
audio source and to include it in the feed to the metadata pipe. You must also
enable metadata (see above). One reason for not including cover art is that the
images can sometimes be very large and may delay transmission of subsequent
metadata through the pipe. The default is "no".

pipe_name="filepathname";
Specify the absolute path name of the pipe through which metadata should be sent
The default is /tmp/shairport-sync-metadata.

socket_address="hostnameOrIP";
If hostnameOrIP is set to a host name or and IP address, UDP packets containing
metadata will be sent to this address. May be a multicast address. Additionally,
socket-port must be non-zero and enabled must be set to "yes".

socket_port=port;
If socket_address is set, use port to specify the port to send UDP packets to. Must
not be zero.

socket_msglength=65000;
The maximum packet size for any UDP metadata. This must be between 500 or 65000.
The default is 500.

"DIAGNOSTICS" SETTINGS

statistics="setting";
Use this setting to enable ("yes") or disable ("no") the output of some statistical
information to the system log (or to STDERR if the -u command line option is
chosen). The default is to disable statistics.

log_verbosity=0;
Use this to specify how much debugging information should sent to the system log
(or to STDERR if the -u command line option is chosen). The value 0 means no debug
information, 3 means most debug information. The default is 0.

OPTIONS

       This section is about the command-line options available in shairport-sync.

       Note: if you are setting up shairport-sync for the first time or are updating an  existing
       installation,  you  are encouraged to use the configuration file settings described above.
       Most of the command-line  options  described  below  simply  replicate  the  configuration
       settings  and  are  retained to provide backward compatibility with older installations of
       shairport-sync.

       Many command-line options take sensible default values, so you can normally ignore most of
       them. See the EXAMPLES section for typical usages.

       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.

PROGRAM OPTIONS

These command-line 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 shaiport-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.

--get-coverart
This option requires the --meta-dir option to be set, and enables shairport-sync to
request cover art from the source and to transmit it through the metadata pipe.

Please note that cover art data may be very large, and may place too great a burden
on your network.

-h | --help
Print brief help message and exit.

-j 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 shaiport-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 shaiport-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.

-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.

--meta-dir=directory
Listen for metadata coming from the source and send it, along with metadata from
shairport-sync itself, to a pipe called shairport-sync-metadata in the directory
you specify. If you add the --get-cover-art then cover art will be sent through the
pipe too. See https://github.com/mikebrady/shairport-sync-metadata-reader for a
sample metadata reader.

-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 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.

--password=secret
Require the password secret to be able to connect and stream to the service.

-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 statistics in the standard output, or in the logfile if in daemon mode.

-S mode | --stuffing=mode
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 to keep
it exactly in synchrony with the player. The default mode, basic, 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 compiled.

-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.

-u If you are running shairport-sync from the command line and want logs to appear
there, use this option. Otherwise, logs may go to the system log.

-V | --version
Print version information and exit.

-v | --verbose
Print debug information to the system log, or or to STDERR if the -u command line
option is also chosen. Repeat up to three times to get more detail.

-w | --wait-cmd
Wait for commands specified using -B or -E to complete before continuing execution.

AUDIO BACKEND OPTIONS

These command-line options are passed to the chosen audio backend. The audio backend
options are preceded by a -- symbol to introduce them and to separate them from any
program options. In this way, option letters can be used as program options and also as
audio backend options without ambiguity.

In the ALSA backend, audio is sent to an output device which you can specify using the -d
option. The output level (the "volume") is controlled using a level control associated
with a mixer. By default, the mixer is implemented in shairport-sync itself in software.
To use a hardware level control on a mixer on the sound card, specify the name of the
mixer control with the -c option. If the mixer is not associated with the output device,
then you need to specify where the mixer is to be found with the -m option.

-c controlname
Use the level control called controlname on the hardware mixer for controlling
volume. This is needed if the mixer type is specified, using the -t option, to be
hardware. There is no default.

-d device
Use the specified output device. You may specify a card, e.g. hw:0, in which case
the default output device on the card will be chosen. Alternatively, you can
specify a specific device on a card, e.g. hw:0,0. The default is the device named
default.

-m mixer
Use the specified hardware mixer for volume control. Use this to specify where the
mixer is to be found. For example, if the mixer is associated with a card, as is
often the case, specify the card, e.g. hw:0. If (unusually) the mixer is associated
with a specific device on a card, specify the device, e.g. hw:0,1. The default is
the device named in the -d option, if given, or the device named default.

-t devicetype
This option is deprecated and is ignored. For your information, its functionality
has been automatically incorporated in the -c option -- if you specify a mixer name
with the -c option, it is assumed that the mixer is implemented in hardware.

EXAMPLES

       Here is a slightly contrived example:

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

       The program will run in daemon mode ( -d ), will be visible as "Joe's Stereo" ( -a  "Joe's
       Stereo"  )  and  will  use the SoX Resampler Library-based stuffing ( -S soxr ). The audio
       backend options following the -- separator specify that the audio will be output on output
       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 in order  to  show  the  use  of  the  -m  option.
       Typically, output 0 is the default output of a card, so the output device could be written
       -d hw:1 and then the mixer option would be unnecessary,  giving  the  following,  simpler,
       command:

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

CREDITS

       Mike Brady developed shairport-sync from the original Shairport by James Laird.

       shairport-sync can be found at https://github.com/mikebrady/shairport-sync.

       Shairport can be found at https://github.com/abrasive/shairport.

COMMENTS

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