Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
shairport-sync(7)      Miscellaneous Information Manual	     shairport-sync(7)

NAME
       shairport-sync -	Synchronised Audio Player for iTunes / AirPlay

SYNOPSIS
       shairport-sync  [-dvw] [-a name]	[-A latency] [-B command] [-c configu-
       rationfile] [-E command]	[--get-cover-art] [--logOutputLevel=] [-L  la-
       tency] [-m backend] [--meta-dir=directory] [-o backend] [--password=se-
       cret] [-r threshold] [--statistics] [-S mode]  [-t  timeout]  [--toler-
       ance=frames] [--	audio_backend_options]

       shairport-sync -D

       shairport-sync -k

       shairport-sync -h

       shairport-sync -R

       shairport-sync -V

DESCRIPTION
       shairport-sync  plays audio streamed from iTunes	or from	an AirPlay de-
       vice to an Advanced Linux Sound Architecture  (ALSA)  compatible	 audio
       output device.

       A  feature of shairport-sync is that the	audio is played	synchronously.
       This means that if many devices are playing the same stream at the same
       time,  all  the outputs will stay in step with one another. This	allows
       multiple	devices	to play	the same source	without	getting	out  of	 phase
       with one	another, enabling, for example,	simultaneous multi-room	opera-
       tion.

       shairport-sync can be compiled to stream	 audio,	 without  synchronisa-
       tion,  to  a  pipe,  to stdout or to a libao output device (an "AO" de-
       vice). It can also be compiled to stream	metadata to a pipe or socket.

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

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	direc-
       tory 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 config-
       uration 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.)

       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 con-
       figuration file:

       general = {

       name = "Mike's Boombox";

       interpolation = "soxr";

       password	= "secret";

       };

       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 num-
	      ber,  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.	Inter-
	      polation 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, "ba-
	      sic", is normally	almost completely inaudible.  The  alternative
	      mode, "soxr", is even less obtrusive but requires	much more pro-
	      cessing power. For this mode, support for	libsoxr, the  SoX  Re-
	      sampler  Library,	 must  be selected when	shairport-sync is com-
	      piled.

       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.

       mdns_backend="backend";
	      shairport-sync has a number of modules of	code ("backends")  for
	      interacting  with	 the  mDNS service to be used to advertise it-
	      self. 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.

       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. The default is "alsa". Perform the  com-
	      mand  shairport-sync  -h	to get a list of available audio back-
	      ends. Only the alsa backend supports synchronisation.

       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	prevous	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  synchroniza-
	      tion  before attempting to correct it. The default is 0.002 sec-
	      onds, 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 sta-
	      tistics 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 mil-
	      liseconds. Specify 0.0 to	disable	resynchronisation.  This  set-
	      ting replaces the	deprecated resync_threshold setting.

       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.

       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, inde-
	      pendently	of the setting at the source. The default is "no".

       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
	      speciies the maximum setting permissible in the software	mixer,
	      which has	an attenuation of from 0.0 dB down to -96.3 dB.

       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	 exam-
	      ple,  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.

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

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

       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  Ap-
	      ple.  Shairport Sync must	have been compiled with	the configura-
	      tion setting "--with-apple-alac" and the Apple ALAC decoder  li-
	      brary must be present for	this to	work.

       "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 de-
	      vices 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_type="mixer_type";  This setting is
	      deprecated and is	ignored. For your information, its functional-
	      ity  has	been  automatically  incorporated  in  the  mixer_con-
	      trol_name	setting	-- if  you  specify  a	mixer  name  with  the
	      mixer_control_name  setting, it is assumed that the mixer	is im-
	      plemented	in hardware.

       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.

       audio_backend_latency_offset_in_seconds=offset;
	      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;
	      Use  this	to set the desired length, in seconds, of the queue of
	      audio frames in the output device's hardware output buffer.  The
	      default  is 0.15 seconds.	If set too small, buffer underflow may
	      occur on low-powered machines. If	too large, the response	 times
	      when  using software volume control (i.e.	when not using a mixer
	      control to control volume) become	annoying, or it	may exceed the
	      hardware	buffer	size.  It may need to be larger	on low-powered
	      machines that are	also performing	other tasks, such as  process-
	      ing metadata.

       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),  endian-
	      ness 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 unmodifed except	for interpola-
	      tion. 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  experi-
	      ence 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".

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

	      Use the name setting to set the name and location	of the pipe.

	      There  are  two  further settings	affecting timing that might be
	      useful if	the pipe reader	is, for	example, a program to play  an
	      audio  stream  such  as  aplay.  The  audio_backend_latency_off-
	      set_in_seconds affects precisely when the	first audio packet  is
	      sent and the audio_backend_buffer_desired_length_in_seconds set-
	      ting affects the nominal output buffer size.

	      These are	the settings available within the pipe group:

       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.

       audio_backend_latency_offset_in_seconds=offset_in_seconds;
	      Packets of audio frames are written to the pipe synchronously --
	      that is, they are	written	at exactly the	time  they  should  be
	      played. You can offset the time of initial audio output relative
	      to its nominal time using	this setting. For example to  send  an
	      audio stream to the pipe 100 milliseconds	before it is due to be
	      played, set this to -0.1.	Default	setting	is 0.0.

       audio_backend_buffer_desired_length_in_seconds=buffer_length_in_sec-
       onds;
	      Use this setting,	in seconds, to set the size of the output buf-
	      fer. It works by determining how soon the	second and  subsequent
	      packets  of  audio  frames are sent to the pipe. For example, if
	      you send the first packet	of audio exactly when it is  due  and,
	      using  a	audio_backend_buffer_desired_length_in_seconds setting
	      of 1.0, send subsequent packets of audio a  second  before  they
	      are due to be played, they will be buffered in the pipe reader's
	      buffer, giving it	a nominal buffer size of 1 second.  Note  that
	      if  the pipe reader consumes audio packets faster	or slower than
	      they are supplied, the buffer will eventually empty or  overflow
	      --  shairport-sync  performs  no	stuffing or interpolation when
	      writing to a pipe. Default setting is 1.0	seconds.

       "STDOUT"	SETTINGS
	      These settings are for the STDOUT	backend, used to  route	 audio
	      to standard output ("stdout"). The audio is in raw CD audio for-
	      mat, usually PCM 16 bit little endian, 44,100 samples  per  sec-
	      ond, interleaved stereo.

	      There  are two settings affecting	timing that might be useful if
	      the stdout reader	is, for	example, a program to  play  an	 audio
	      stream  such  as aplay. The audio_backend_latency_offset_in_sec-
	      onds affects precisely when the first audio packet is  sent  and
	      the  audio_backend_buffer_desired_length_in_seconds  setting af-
	      fects the	nominal	output buffer size.

	      These are	the settings available within the stdout group:

       audio_backend_latency_offset_in_seconds=offset_in_seconds;
	      Packets of audio frames are written to stdout  synchronously  --
	      that  is,	 they  are  written at exactly the time	they should be
	      played. You can offset the time of initial audio output relative
	      to  its  nominal time using this setting.	For example to send an
	      audio stream to stdout 100 milliseconds before it	is due	to  be
	      played, set this to -0.1.	Default	setting	is 0.0.

       audio_backend_buffer_desired_length_in_seconds=buffer_length_in_sec-
       onds;
	      Use this setting,	in frames, to set the size of the output  buf-
	      fer.  It works by	determining how	soon the second	and subsequent
	      packets of audio frames are sent to stdout. For example, if  you
	      send the first packet of audio exactly when it is	due and, using
	      a	audio_backend_buffer_desired_length_in_seconds setting of 1.0,
	      send subsequent packets of audio a second	before they are	due to
	      be played, they will be buffered in the stdout reader's  buffer,
	      giving  it  a  nominal buffer size of 1 second. Note that	if the
	      stdout reader consumes audio packets faster or slower than  they
	      are  supplied,  the  buffer will eventually empty	or overflow --
	      shairport-sync performs no stuffing or interpolation when	 writ-
	      ing to stdout. Default setting is	1.0 seconds.

       "AO" SETTINGS
	      These  settings are for the AO backend, used for the libao audio
	      library.

	      There are	two settings affecting timing.	The  audio_backend_la-
	      tency_offset_in_seconds  affects	precisely when the first audio
	      packet	is    sent    and     the     audio_backend_buffer_de-
	      sired_length_in_seconds  setting affects the nominal output buf-
	      fer size.

	      These are	the settings available within the ao group:

       audio_backend_latency_offset_in_seconds=offset_in_seconds;
	      Packets of audio frames are written to  the  libao  system  syn-
	      chronously -- that is, they are written at exactly the time they
	      should be	played.	You can	offset the time	of initial audio  out-
	      put relative to its nominal time using this setting. For example
	      to send an audio stream to stdout	100 milliseconds before	it  is
	      due to be	played,	set this to -0.1. Default setting is 0.0.

       audio_backend_buffer_desired_length_in_seconds=buffer_length_in_sec-
       onds;
	      Use this setting,	in seconds, to set the size of the output buf-
	      fer.  It works by	determining how	soon the second	and subsequent
	      packets of audio frames are sent to the libao system. For	 exam-
	      ple,  if	you  send the first packet of audio exactly when it is
	      due and, using a	audio_backend_buffer_desired_length_in_seconds
	      setting of 1.0, send subsequent packets of audio a second	before
	      they are due to be played, they will be buffered in  the	stdout
	      reader's	buffer,	 giving	 it a nominal buffer size of 1 second.
	      Note that	if the libao system consumes audio packets  faster  or
	      slower  than they	are supplied, the buffer will eventually empty
	      or overflow -- shairport-sync performs no	stuffing or interpola-
	      tion when	writing	to libao. Default setting is 1.0 seconds.

       "METADATA" SETTINGS
	      shairport-sync can process metadata provided by the source, such
	      as Track Number, Album Name, cover art, etc. and can provide ad-
	      ditional	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 identifi-
	      cation 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 han-
	      dling 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	 meta-
	      data 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 be-
	      tween 500	or 65000. The default is 500.

       "SESSIONCONTROL"	SETTINGS
	      shairport-sync can run programs just before it starts to play an
	      audio  stream and	just after it finishes.	You specify them using
	      the sessioncontrol  group	 settings  run_this_before_play_begins
	      and run_this_after_play_ends.

       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	#!/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	#!/bin/... as appropriate.

       wait_for_completion="choice";
	      Set  choice  to "yes" to make shairport-sync wait	until the pro-
	      grams   specified	  in   the   run_this_before_play_begins   and
	      run_this_after_play_ends have completed execution	before contin-
	      uing. 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  net-
	      work)  then  wait	for seconds seconds before ending the session.
	      Once the session has terminated, other devices can use  it.  The
	      default is 120 seconds.

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 con-
       figuration file settings	described above. Most of the command-line  op-
       tions  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 nor-
       mally 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 num-
	      ber,  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	#!/bin/sh (or whatever
	      is appropriate) in the headline.

	      If you want shairport-sync to wait until the  command  has  com-
	      pleted 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  Configura-
	      tion  Directory  -- /etc in Linux, /usr/local/etc	in BSD unixes.
	      For information about configuration settings, see	the  "Configu-
	      ration File Settings" section above.

       -D | --disconnectFromOutput
	      Disconnect  the shairport-sync daemon from the output device and
	      exit. (Requires that the daemon has written its PID to an	agreed
	      file -- see the -d option).

	      Please  note that	this feature is	deprecated and will be removed
	      in a future version of shairport-sync.

       -d | --daemon
	      Instruct shairport-sync to demonise itself. It  will  write  its
	      Process  ID  (PID)  to  a	 file,	usually	at /var/run/shairport-
	      sync.pid,	which is used by the -k, -D and	-R options  to	locate
	      the daemon at a later time.

       -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	#!/bin/sh (or whatever is appropriate)
	      in the headline.

	      If you want shairport-sync to wait until the  command  has  com-
	      pleted before continuing,	select the -w option as	well.

       --get-coverart
	      This  option  requires  the --meta-dir option to be set, and en-
	      ables 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.

       -k | --kill
	      Kill the shairport-sync daemon and exit. (Requires that the dae-
	      mon has written its PID to an agreed file	-- see the -d option).

       --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 ear-
	      lier 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.  (This  is	 not  used  at
	      present.)

       -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 | --reconnectToOutput
	      Reconnect	 the  shairport-sync  daemon  to the output device and
	      exit. It may take	a few seconds to synchronise.  (Requires  that
	      the  daemon  has written its PID to an agreed file -- see	the -d
	      option).

	      Please note that this feature is deprecated and will be  removed
	      in a future version of shairport-sync.

       -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  mil-
	      liseconds.  Specify 0 to disable resynchronisation. This setting
	      is deprecated and	will be	removed	in a future version of	shair-
	      port-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 ses-
	      sion and will return a busy signal to any	other sources that at-
	      tempt 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  sec-
	      onds.

       --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  correc-
	      tions (insertions	and deletions) are made	than are strictly nec-
	      essary to	keep the stream	in sync. Use the  --statistics	option
	      to monitor correction levels. Corrections	should not greatly ex-
	      ceed net corrections. This setting is deprecated and will	be re-
	      moved in a future	version	of shairport-sync.

       -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	 with-
       out 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  con-
       trolled	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  de-
	      fault.

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

Manuals				     User		     shairport-sync(7)

NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION FILE SETTINGS | OPTIONS | PROGRAM OPTIONS | AUDIO BACKEND OPTIONS | EXAMPLES | CREDITS | COMMENTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=shairport-sync&sektion=7&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help