Provided by: shairport-sync_3.3.2-1_amd64 bug

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";

       interpolation = "soxr";

       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 volume control's name should be specified. It  is  highly  desirable  to  use  the
       output device's mixer for volume control, if available -- response time is reduced to zero
       and the processor load is reduced. In the example above,  "soxr"  interpolation  was  also
       enabled.

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

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

       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.

              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.

       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 44100 (default), 88200, 176400 and 352800.  The  device  must  have  the
              capability  to  accept the format you specify. There is no particular reason to use
              anything other than 44100 if it is available.

       output_format="format";
              Use this setting to specify the format that should be used to send data to the ALSA
              device.  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".

              If you are using a hardware mixer, the best setting is  S16,  as  audio  will  pass
              through  Shairport  Sync  unmodified except for interpolation. If you are using the
              software mixer, use 32- or 24-bit, if your device is capable  of  it,  to  get  the
              lowest possible levels of dither.

       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.

              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.

       "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 on the console or in the log. The default is to disable statistics.

       log_verbosity=0;
              Use  this to specify how much debugging information should be output or logged. 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. 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.