shairport-sync.7.xml

<?xml version="1.0"?><!--*-nxml-*-->
<!DOCTYPE manpage SYSTEM "xmltoman.dtd">
<?xml-stylesheet type="text/xsl" href="xmltoman.xsl" ?>

<!--
  This man pager source file is part of shairport-sync.
  Copyright (c) Mike Brady 2014-2015

  All rights reserved.
 
  Permission is hereby granted, free of charge, to any person
  obtaining a copy of this software and associated documentation
  files (the "Software"), to deal in the Software without
  restriction, including without limitation the rights to use,
  copy, modify, merge, publish, distribute, sublicense, and/or
  sell copies of the Software, and to permit persons to whom the
  Software is furnished to do so, subject to the following conditions:
 
  The above copyright notice and this permission notice shall be
  included in all copies or substantial portions of the Software.
 
  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  OTHER DEALINGS IN THE SOFTWARE.
-->

  <manpage name="shairport-sync" section="7" desc="Synchronised Audio Player for iTunes / AirPlay">

	<synopsis>
	<!--
      <cmd>shairport-sync <opt>-D</opt> <arg>interface</arg></cmd>
  -->
      <cmd>shairport-sync  <opt>[-dvw]</opt>
      <opt>[-a </opt><arg>name</arg><opt>]</opt>
      <opt>[-A </opt><arg>latency</arg><opt>]</opt>
      <opt>[-B </opt><arg>command</arg><opt>]</opt>
      <opt>[-E </opt><arg>command</arg><opt>]</opt>
      <opt>[--forkedDaapdLatency=</opt><arg>latency</arg><opt>]</opt>
      <opt>[-i </opt><arg>latency</arg><opt>]</opt>
      <opt>[-L </opt><arg>latency</arg><opt>]</opt>
      <opt>[-m </opt><arg>backend</arg><opt>]</opt>
      <opt>[-o </opt><arg>backend</arg><opt>]</opt>
      <opt>[--password=</opt><arg>secret</arg><opt>]</opt>
      <opt>[-r </opt><arg>threshold</arg><opt>]</opt>
      <opt>[--statistics]</opt>
      <opt>[-S </opt><arg>mode</arg><opt>]</opt>
      <opt>[-t </opt><arg>timeout</arg><opt>]</opt>
      <opt>[--tolerance=</opt><arg>frames</arg><opt>]</opt>
      <opt>[-- </opt><arg>audio_backend_options</arg><opt>]</opt>
      </cmd>
      <cmd>shairport-sync <opt>-D</opt></cmd>
      <cmd>shairport-sync <opt>-h</opt></cmd>
      <cmd>shairport-sync <opt>-k</opt></cmd>
      <cmd>shairport-sync <opt>-h</opt></cmd>
      <cmd>shairport-sync <opt>-R</opt></cmd>
      <cmd>shairport-sync <opt>-V</opt></cmd>
	</synopsis>

  <description>
    <p>shairport-sync  plays  audio  streamed  from  iTunes or from an AirPlay
    device to an audio device connected via an audio back end. At present,
    the only fully-implemented back end is for ALSA.</p>

    <p> 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 play the same source without getting out of phase with one another,
    enabling, for example, simultaneous multi-room operation.
    </p>

	</description>

	<options>

    <p>Many  of  the options take sensible default values, so you can normally
    ignore most of them. See the EXAMPLES section for typical usages.</p>

    <p>The command line for shairport-sync can take two kinds of options:
    regular <opt>program options</opt> and <opt>audio backend options</opt>.
    Program options are
    always listed first, followed by any audio backend options, preceded by
    a <opt>--</opt> symbol.</p>
    
  <section name="Program Options">
  <p>These options are used by shairport-sync itself.</p>
  </section>
  
	  <option>
		<p><opt>-a </opt><arg>service name</arg><opt> | --name=</opt><arg>service name</arg></p>
		<optdesc><p>
		Use this <arg>service name</arg> to identify this player in iTunes, etc.
    The default name is "Shairport Sync on &lt;hostname&gt;".
    </p></optdesc>
	  </option>

	  <option>
		<p><opt>-A | --AirPlayLatency=</opt><arg>latency</arg></p>
		<optdesc><p>
		Use this <arg>latency</arg>, in frames, for audio streamed from an AirPlay
    device. The default is 88,200 frames, where there are 44,100
    frames to the second.
    </p></optdesc>
	  </option>

	  <option>
		<p><opt>-B </opt><arg>program</arg><opt> | --on-start=</opt><arg>program</arg></p>
		<optdesc><p>
		Execute <arg>program</arg> when playback is about to begin. Specify the 
		full path to the program, e.g. <file>/usr/bin/logger</file>.
		Executable scripts can be used, but they must have <file>#!/bin/sh</file> (or
		whatever is appropriate) in the headline.</p>
		
		<p>If you want shairport-sync to wait until the command has
		completed before starting to play, select the <opt>-w</opt> option as well.
		</p></optdesc>
	  </option>

	  <option>
		<p><opt>-D | --disconnectFromOutput</opt></p>
		<optdesc><p>
		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 <opt>-d</opt> option).
		</p></optdesc>
	  </option>

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

	  <option>
		<p><opt>-E </opt><arg>program</arg><opt> | --on-stop=</opt><arg>program</arg></p>
		<optdesc><p>
		Execute <arg>program</arg> when playback has ended. Specify the 
		full path to the program, e.g. <file>/usr/bin/logger</file>.
		Executable scripts can be used, but they must have <file>#!/bin/sh</file> (or
		whatever is appropriate) in the headline.</p>		
		<p>If you want shairport-sync to wait until the command has
		completed before continuing, select the <opt>-w</opt> option as well.
		</p></optdesc>
	  </option>

	  <option>
		<p><opt>--forkedDaapdLatency=</opt><arg>latency</arg></p>
		<optdesc><p>
		Use this <arg>latency</arg>, in frames, for audio streamed from a forked-daapd based
    source. The default is 99,400 frames, where there are 44,100
    frames to the second.
    </p></optdesc>
	  </option>

	  <option>
		<p><opt>-h | --help</opt></p>
		<optdesc><p>
		Print brief help message and exit.
		</p></optdesc>
	  </option>

	  <option>
		<p><opt>-i | --iTunesLatency=</opt><arg>latency</arg></p>
		<optdesc><p>
		Use this <arg>latency</arg>, in frames, for audio streamed from an iTunes
    source, where iTunes is Version 10 or later. The default is 99,400 frames, where there are 44,100
    frames to the second. If the source is iTunes but is earler than Version 10, the <arg>default latency</arg> is used (see the <opt>-L</opt> option). Some third party programs masquerade as older versions of iTunes.
    </p></optdesc>
	  </option>

	  <option>
		<p><opt>-k | --kill</opt></p>
		<optdesc><p>
		Kill the shairport-sync daemon and exit. (Requires that the daemon has
		written its PID to an agreed file -- see the <opt>-d</opt> option).
		</p></optdesc>
	  </option>

	  <option>
		<p><opt>-L | --latency=</opt><arg>latency</arg></p>
		<optdesc><p>
		Use this to set the <arg>default latency</arg>, in frames, for audio coming from an unidentified source or from an iTunes Version 9 or earlier source. The standard value for the <arg>default latency</arg> is 88,200 frames, where there are 44,100
    frames to the second.
    </p></optdesc>
	  </option>

	  <option>
		<p><opt>-m </opt><arg>mdnsbackend</arg><opt> | --mdns=</opt><arg>mdnsbackend</arg></p>
		<optdesc><p>
		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.
		</p></optdesc>
	  </option>

	  <option>
		<p><opt>-o </opt><arg>outputbackend</arg><opt> | --output=</opt><arg>outputbackend</arg></p>
		<optdesc><p>
		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></optdesc>
	  </option>

	  <option>
		<p><opt>-p </opt><arg>port</arg><opt> | --port=</opt><arg>port</arg></p>
		<optdesc><p>
		Listen for play requests on <arg>port</arg>. The default is to use port
    5000.
		</p></optdesc>
	  </option>

	  <option>
		<p><opt>--password=</opt><arg>secret</arg></p>
		<optdesc><p>
		Require the password <arg>secret</arg> to be able to connect and stream to the service.
		</p></optdesc>
	  </option>

	  <option>
		<p><opt>-R | --reconnectToOutput</opt></p>
		<optdesc><p>
		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 <opt>-d</opt>
    option).
		</p></optdesc>
	  </option>

	  <option>
		<p><opt>-r </opt><arg>threshold</arg><opt> | --resync=</opt><arg>threshold</arg></p>
		<optdesc><p>
		Resynchronise if timings differ by more than <arg>threshold</arg> 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 <opt>0</opt> to disable resynchronisation.
		</p></optdesc>
	  </option>

	  <option>
		<p><opt>--statistics</opt></p>
		<optdesc><p>
		Print some statistics in the standard output, or in the logfile if in daemon mode.
		</p></optdesc>
	  </option>

	  <option>
		<p><opt>-S </opt><arg>mode</arg><opt> | --stuffing=</opt><arg>mode</arg></p>
		<optdesc><p>
		Stuff the audio stream using the <arg>mode</arg>.  "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, <opt>basic</opt>, is normally almost  completely  inaudible.
    The  alternative mode, <opt>soxr</opt>, 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.
		</p></optdesc>
	  </option>

	  <option>
		<p><opt>-t </opt><arg>timeout</arg><opt> | --timeout=</opt><arg>timeout</arg></p>
		<optdesc><p>
		Exit play mode if the stream disappears for  more  than  <arg>timeout</arg>
    seconds.</p>
    <p>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 <arg>timeout</arg> seconds, the play session will be terminated.
    If you  specify a timeout time of <opt>0</opt>,
    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.
		</p></optdesc>
	  </option>

	  <option>
		<p><opt>--tolerance=</opt><arg>frames</arg></p>
		<optdesc><p>
		Allow playback to be up to <arg>frames</arg> 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 <opt>--statistics</opt> option to
		monitor correction levels. Corrections should not greatly exceed net corrections.
		</p></optdesc>
	  </option>

	  <option>
		<p><opt>-V | --version</opt></p>
		<optdesc><p>
		Print version information and exit.
		</p></optdesc>
	  </option>

	  <option>
		<p><opt>-v | --verbose</opt></p>
		<optdesc><p>
		Print debug information. Repeat up to three times to get more detail.
		</p></optdesc>
	  </option>

	  <option>
		<p><opt>-w | --wait-cmd</opt></p>
		<optdesc><p>
		Wait for commands specified using <opt>-B</opt> or <opt>-E</opt>  to  complete  before
    continuing execution.
		</p></optdesc>
	  </option>

  <section name="Audio Backend Options">
  <p>These  options are passed to the chosen audio backend. (At present, the
  only backend implemented is for ALSA.) The audio  backend  options  are
  preceded by a <opt>--</opt> 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.</p>
  <p>In the ALSA backend, audio is sent to an output device
  which you can specify using the <opt>-d</opt> 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, i.e. the type of
  the mixer is "software".
  To use a level control on a mixer on the sound card, you must (a)
  specify that the mixer's type is "hardware" with the <opt>-t</opt> option;
  (b) you must specify where the mixer is to be found using the <opt>-m</opt> option
  and finally (c) you must specify the name of the level control you are using
  with the <opt>-c</opt> option.</p>
  </section>
  
  <option>
  <p><opt>-c </opt><arg>controlname</arg></p>
  <optdesc><p>
  Use the level control called <arg>controlname</arg> on the hardware mixer for
  controlling volume.
  This is needed if the mixer type is specified, using the <opt>-t</opt> option,
  to be <opt>hardware</opt>. There is no default.
  </p></optdesc>
  </option>

  <option>
  <p><opt>-d </opt><arg>device</arg></p>
  <optdesc><p>
  Use the specified output <arg>device</arg>. You may specify a card, e.g. <opt>hw:0</opt>, 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. <opt>hw:0,0</opt>.
  The default is the device named <opt>default</opt>.
  </p></optdesc>
  </option>

  <option>
  <p><opt>-m </opt><arg>mixer</arg></p>
  <optdesc><p>
  Use the specified hardware <arg>mixer</arg> 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. <opt>hw:0</opt>.
  If (unusually) the mixer is associated with a specific device on a card,
  specify the device, e.g. <opt>hw:0,1</opt>.
  The default is the device named in the <opt>-d</opt> option,
  if given, or the device named <opt>default</opt>.
  </p></optdesc>
  </option>

  <option>
  <p><opt>-t </opt><arg>devicetype</arg></p>
  <optdesc>
  <p>
  The type of the output device is <arg>devicetype</arg> which must be
  <opt>hardware</opt> or <opt>software</opt>. The default is <opt>software</opt>.
  If you specify <opt>hardware</opt> you must also specify the output device using the
  <opt>-d</opt> option and the name of the volume control using the <opt>-c</opt> option.
  You may also need to specify the mixer using the <opt>-m</opt> option.
  </p></optdesc>
  </option>
	</options>

  <section name="Examples">
  <p>Here is a slightly contrived but typical example:</p>
      <cmd>shairport-sync  <opt>-d</opt>
      <opt>-a "Joe's Stereo"</opt>
      <opt>-S soxr</opt>
      <opt>--</opt>
      <opt>-d hw:1,0</opt>
      <opt>-m hw:1</opt>
      <opt>-t hardware</opt>
      <opt>-c PCM</opt>      
      </cmd>
  <p>The program will run in daemon mode ( <opt>-d</opt> ), will be  visible  as
  "Joe's Stereo" ( <opt>-a "Joe's Stereo"</opt> ) and will use the SoX Resampler
  Library-based stuffing ( <opt>-S soxr</opt> ).
  The audio backend options following the <opt>--</opt> separator specify
  that  the  audio will be output on output 0 of soundcard 1 (
  <opt>-d hw:1,0</opt> ) and will take advantage of the same sound card's hardware
  (<opt>-t hardware</opt>) mixer ( <opt>-m hw:1</opt> )
  using the level control named "PCM" ( <opt>-c "PCM"</opt> ).
  </p>
  <p>The example above is slightly contrived in order to show the use of the <opt>-m</opt> option.
  Typically, output 0 is the default output of a card,
  so the output device could be written <opt>-d hw:1</opt> and
  then the mixer option would be unnecessary, giving the following, simpler, command:</p>
       <cmd>shairport-sync  <opt>-d</opt>
      <opt>-a "Joe's Stereo"</opt>
      <opt>-S soxr</opt>
      <opt>--</opt>
      <opt>-d hw:1</opt>
      <opt>-t hardware</opt>
      <opt>-c PCM</opt>      
      </cmd>
 
  </section>

	<section name="Credits">
	<p>Mike Brady developed shairport-sync from the original shairport by James Laird.</p>
	<p>shairport-sync can be found at  <url href="https://github.com/mikebrady/shairport-sync."/></p>
  <p>shairport can be found at <url href="https://github.com/abrasive/shairport."/></p>
	</section>

	<section name="Comments">
	  <p>This man page was written using <manref name="xml2man" section="1"
		  href="http://masqmail.cx/xml2man/"/> by Oliver Kurth.</p>
	</section>

  </manpage>