+ 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.
+
+ 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.
+
+
+
+
+
+
+ Many of the options take sensible default values, so you can normally
+ ignore most of them. See the EXAMPLES section for typical usages.
+
+ The command line for shairport-sync can take two kinds of options:
+ regular program options and audio backend options .
+ Program options are
+ always listed first, followed by any audio backend options, preceded by
+ a -- symbol.
+
+
+ These 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 default name is "Shairport Sync on <hostname>".
+
+
+
+ -A | --AirPlayLatency= latency
+
+ Use this latency , in frames, for audio streamed from an AirPlay
+ device. The default is 88,200 frames, where there are 44,100
+ frames to the second.
+
+
+
+ -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
+ completed before starting to play, select the -w option as well.
+
+
+
+ -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).
+
+
+
+ -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
+ completed before continuing, select the -w option as well.
+
+
+
+ --forkedDaapdLatency= latency
+
+ Use this latency , 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.
+
+
+
+ --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. Also, at the time of writing, there appears to be a
+ serious bug in iTunes which stalls transmission of large cover art items,
+ stalling and potentially crashing shairport-sync.
+
+
+
+ -h | --help
+
+ Print brief help message and exit.
+
+
+
+ -i | --iTunesLatency= latency
+
+ Use this latency , 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 default latency is used (see the -L option). Some third party programs masquerade as older versions of iTunes.
+
+
+
+ -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).
+
+
+
+ -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.
+
+
+
+ --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).
+
+
+
+ -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.
+
+
+
+ --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.
+
+
+
+ -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.
+
+
+
+ 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 -- 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, 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 -t option;
+ (b) you must specify where the mixer is to be found using the -m option
+ and finally (c) you must specify the name of the level control you are using
+ with the -c 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
+
+
+ The type of the output device is devicetype which must be
+ hardware or software . The default is software .
+ If you specify hardware you must also specify the output device using the
+ -d option and the name of the volume control using the -c option.
+ You may also need to specify the mixer using the -m option.
+
+
+
+
+
+ Here is a slightly contrived but typical example:
+ shairport-sync -d
+ -a "Joe's Stereo"
+ -S soxr
+ --
+ -d hw:1,0
+ -m hw:1
+ -t hardware
+ -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 hardware
+ (-t hardware ) 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
+ -t hardware
+ -c PCM
+
+
+
+
+