.SH NAME
shairport-sync \- AirPlay and AirPlay 2 Audio Player
.SH SYNOPSIS
-\fBshairport-sync [-djvw]\fB [-a \fB\fIname\fB]\fB [-A \fB\fIlatency\fB]\fB [-B \fB\fIcommand\fB]\fB [-c \fB\fIconfigurationfile\fB]\fB [-E \fB\fIcommand\fB]\fB [--get-cover-art]\fB [--logOutputLevel]\fB [--log-to-syslog]\fB [-L \fB\fIlatency\fB]\fB [-m \fB\fIbackend\fB]\fB [--meta-dir=\fB\fIdirectory\fB]\fB [-o \fB\fIbackend\fB]\fB [--password=\fB\fIsecret\fB]\fB [-r \fB\fIthreshold\fB]\fB [--statistics]\fB [-S \fB\fImode\fB]\fB [-t \fB\fItimeout\fB]\fB [--tolerance=\fB\fIframes\fB]\fB [-- \fB\fIaudio_backend_options\fB]\fB
+\fBshairport-sync [-djvw]\fB [-a \fB\fIservice-name\fB | --name=\fB\fIservice-name\fB]\fB [-B \fB\fIcommand\fB | --onstart=\fB\fIcommand\fB]\fB [-c \fB\fIconfigurationfile\fB | --configfile=\fB\fIconfigurationfile\fB]\fB [-d | --daemon]\fB [-E \fB\fIcommand\fB | --onstop=\fB\fIcommand\fB]\fB [-g | --get-cover-art]\fB [-j | --justDaemoniseNoPIDFile]\fB [--logOutputLevel]\fB [--log-to-syslog]\fB [-L \fB\fIlatency\fB | --latency=\fB\fIlatency\fB]\fB [-m \fB\fIbackend\fB | --mdns=\fB\fIbackend\fB]\fB [-M | --metadata-enable]\fB [-o \fB\fIbackend\fB | --output=\fB\fIbackend\fB]\fB [-p \fB\fIport\fB | --port=\fB\fIport\fB]\fB [--password=\fB\fIsecret\fB]\fB [-r \fB\fIthreshold\fB | --resync=\fB\fIthreshold\fB]\fB [--statistics]\fB [-S \fB\fImode\fB | --stuffing=\fB\fImode\fB]\fB [-t \fB\fItimeout\fB | --timeout=\fB\fItimeout\fB]\fB [--tolerance=\fB\fIframes\fB]\fB [-v | --verbose]\fB [-w | --wait-cmd]\fB [-- \fB\fIaudio_backend_options\fB]\fB
-shairport-sync -k\fB
+shairport-sync --displayConfig\fB
shairport-sync -h\fB
+shairport-sync -k\fB
+
shairport-sync -V\fB
\f1
.SH DESCRIPTION
-Shairport Sync plays audio streamed from an AirPlay or an AirPlay 2 device. AirPlay 2 support is limited, and AirPlay 2 from iTunes for Windows is not supported. Please see \fBhttps://github.com/mikebrady/shairport-sync\f1 for details.
+Shairport Sync plays AirPlay audio. It can be built to stream either from "classic" AirPlay (aka "AirPlay 1") or from AirPlay 2 devices.
+
+AirPlay 2 support is limited, and AirPlay 2 from iTunes for Windows is not supported. For AirPlay 2 operation, a companion program called \fBnqptp\f1 must be installed.
-Settings can be made using the configuration file (recommended for all new installations) or by using command-line options.
+Please see \fBhttps://github.com/mikebrady/shairport-sync\f1 for details.
-The name of the Shairport Sync executable is \fBshairport-sync\f1. Both names are used in these man pages.
+The name of the Shairport Sync executable is \fBshairport-sync\f1.
.SH CONFIGURATION FILE SETTINGS
-You should use the configuration file for setting up Shairport Sync. This file is usually \fIshairport-sync.conf\f1 and is generally located in the System Configuration Directory, which is normally the \fI/etc\f1 directory in Linux or the \fI/usr/local/etc\f1 directory in BSD unixes. You may need to have root privileges to modify it.
+You should use the configuration file for setting up Shairport Sync because -- apart from a few special-purpose commands -- it has a much richer set of options than are available on the command line. This file is usually \fIshairport-sync.conf\f1 and is generally located in the System Configuration Directory, which is normally the \fI/etc\f1 directory in Linux or the \fI/usr/local/etc\f1 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 \fI$ shairport-sync -V\f1. One of the items in the output string is the value of the \fBsysconfdir\f1, i.e. the System Configuration Directory.)
+(Note: Shairport Sync may have been compiled to use a different configuration directory. You can determine which by performing the command \fI$ shairport-sync -V\f1. The last item in the output string is the value of the \fBsysconfdir\f1, 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 \fBalsa\f1 group with settings that pertain to the \fBALSA\f1 back end. Here is an example of a typical configuration file:
+Within the configuration file, settings are organised into groups, for example, there is a \fBgeneral\f1 group of standard settings, and there is an \fBalsa\f1 group with settings that pertain to the \fBALSA\f1 back end. Here is an example of a typical configuration file:
\fBgeneral = {\f1
\fB};\f1
-Most settings have sensible default values, so -- as in the example above -- users generally only need to set (1) the service name and (2) the output device. If the \fBname\f1 setting is omitted, the service name is derived from the system's hostname. By default, the \fBALSA\f1 backend will be chosen if included in the build. If the (alsa) output device has a mixer that can be used for volume control, then (3) the mixer name should be specified. It is important to do this if the mixer exists. Otherwise, the maximum output from the output device will be whatever setting the mixer happens to have, which will be a matter of chance and which could be very low or even silent.
+Users generally only need to set (1) the service name and (2) the output device. If the \fBname\f1 setting is omitted, the service name is derived from the system's hostname. By default, the \fBALSA\f1 backend will be chosen if included in the build. If the (alsa) output device has a mixer that can be used for volume control, then (3) the mixer name should be specified. It is important to do this if the mixer exists. Otherwise, the maximum output from the output device will be whatever setting the mixer happens to have, which will be a matter of chance and which could be very low or even silent.
A sample configuration file with all possible settings, but with all of them commented out, is installed at \fIshairport-sync.conf.sample\f1, within the System Configuration Directory -- \fI/etc\f1 in Linux, \fI/usr/local/etc\f1 in BSD unixes.
The sample configuration file includes extensive documentation of the settings. and is also available at \fBhttps://github.com/mikebrady/shairport-sync/blob/master/scripts/shairport-sync.conf\f1. Please refer to it for the most up-to-date information on configuration file settings.
-
-New features, etc. will generally be available only via configuration file settings.
.SH OPTIONS
-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 \fBprogram options\f1 and \fBaudio backend options\f1. Program options are always listed first, followed by any audio backend options, preceded by a \fB--\f1 symbol.
+
+See the EXAMPLES section for sample usages.
.SH PROGRAM OPTIONS
Program Options are used by shairport-sync itself.
.TP
\fB-d | --daemon\f1
Instruct shairport-sync to demonise itself. It will write its Process ID (PID) to a file, usually at \fI/var/run/shairport-sync/shairport-sync.pid\f1, which is used by the \fB-k\f1, \fB-D\f1 and \fB-R\f1 options to locate the daemon at a later time. See also the \fB-j\f1 option. Only available if shairport-sync has been compiled with libdaemon support.
.TP
+\fB--displayConfig\f1
+This will display information relating to the configuration of Shairport Sync. It can be very useful for debugging. The information displayed is the version string (which indicates the build options used when \fBshairport-sync\f1 was built), the contents of the command line that invoked Shairport Sync, the name of the configuration file and the active settings therein.
+
+If this is the only option on the command line, \fBshairport-sync\f1 will terminate after displaying the information.
+
+Due to a limitation, \fB--displayConfig\f1 always outputs to \fISTDERR\f1, irrespective of the setting of \fB--log-to-syslog\f1.
+.TP
\fB-E \f1\fIprogram\f1\fB | --on-stop=\f1\fIprogram\f1
Execute \fIprogram\f1 when playback has ended. Specify the full path to the program, e.g. \fI/usr/bin/logger\f1. Executable scripts can be used, but they must have the appropriate shebang (\fI#!/bin/sh\f1) in the headline.
If you want shairport-sync to wait until the command has completed before continuing, select the \fB-w\f1 option as well.
.TP
-\fB--get-coverart\f1
-This option requires the \fB--meta-dir\f1 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.
+\fB-g | --get-coverart\f1
+This option requires the \fB-M | --metadata-enable\f1 option to be set, and enables shairport-sync to request cover art from the source and to process it as metadata.
.TP
\fB-h | --help\f1
Print brief help message and exit.
.TP
-\fB-j\f1
+\fB-j | justDaemoniseNoPIDFile\f1
Instruct shairport-sync to demonise itself. Unlike the \fB-d\f1 option, it will not write a Process ID (PID) to a file -- it will just (hence the "j") demonise itself. Only available if shairport-sync has been compiled with libdaemon support.
.TP
\fB-k | --kill\f1
.TP
\fB--log-to-syslog\f1
Warnings, error messages and messages are sent, by default, to \fISTDERR\f1. Use this option to route these messages to the \fBsyslog\f1 instead. This is intended for use when Shairport Sync is operating as a daemon.
+
+See also \fB--displayConfig\f1.
.TP
\fB-L | --latency=\f1\fIlatency\f1
Use this to set the \fIdefault latency\f1, in frames, for audio coming from an unidentified source or from an iTunes Version 9 or earlier source. The standard value for the \fIdefault latency\f1 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.
.TP
-\fB--meta-dir=\f1\fIdirectory\f1
-Listen for metadata coming from the source and send it, along with metadata from shairport-sync itself, to a pipe called \fIshairport-sync-metadata\f1 in the \fIdirectory\f1 you specify. If you add the \fB--get-cover-art\f1 then cover art will be sent through the pipe too. See \fBhttps://github.com/mikebrady/shairport-sync-metadata-reader\f1 for a sample metadata reader.
+\fB-M | --metadata-enable\f1
+Ask the client to send metadata. It will be sent, along with metadata generated by shairport-sync itself, to a pipe and will also be sent as UDP packets. If you add the \fB-g | --get-cover-art\f1 then cover art included, where available. See \fBhttps://github.com/mikebrady/shairport-sync-metadata-reader\f1 for a sample metadata reader.
+.TP
+\fB--metadata-pipename=\f1\fIpathname\f1
+Specify the path name for the metadata pipe. Note that \fBshairport-sync\f1 will need write permission on that directory and pipe. The default is \fI/tmp/shairport-sync-metadata\f1. If you rename the \fBshairport-sync\f1 executable, the default pipe name will change accordingly.
.TP
\fB-m \f1\fImdnsbackend\f1\fB | --mdns=\f1\fImdnsbackend\f1
-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.
+Force the use of the specified mDNS backend to advertise the player on the network. The default is to try all mDNS backends in order until one works.
.TP
\fB-o \f1\fIoutputbackend\f1\fB | --output=\f1\fIoutputbackend\f1
Force the use of the specified output backend to play the audio. The default is to try the first one.
Resynchronise if timings differ by more than \fIthreshold\f1 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 \fB0\f1 to disable resynchronisation. This setting is deprecated and will be removed in a future version of shairport-sync.
.TP
\fB--statistics\f1
-Print some performance information \fISTDERR\f1, or to \fBsyslog\f1 if the \fB-log-to-syslog\f1 command line option is also chosen.
+Print some performance information to \fISTDERR\f1, or to \fBsyslog\f1 if the \fB-log-to-syslog\f1 command line option is also chosen.
.TP
\fB-S \f1\fImode\f1\fB | --stuffing=\f1\fImode\f1
-Interpolate ("stuff") the audio stream using the \fImode\f1. "Stuffing" refers to the process of adding or removing frames of audio to or from the stream sent to the output device in order to keep it synchronised with the player. The \fBbasic\f1 mode is normally almost completely inaudible. The alternative mode, \fBsoxr\f1, is even less obtrusive but requires much more processing power. For this mode, support for libsoxr, the SoX Resampler Library, must be selected when shairport-sync is compiled. The default setting, \fBauto\f1, allows Shairport Sync to choose \fBsoxr\f1 mode if the system is powerful enough.
+Interpolate ("stuff") the audio stream using the \fImode\f1. "Stuffing" refers to the process of adding or removing frames of audio to or from the stream sent to the output device in order to keep it synchronised with the player. The \fBbasic\f1 mode is normally almost completely inaudible. The alternative mode, \fBsoxr\f1, is even less obtrusive but requires much more processing power. For this mode, support for \fBlibsoxr\f1, the SoX Resampler Library, must be selected when \fBshairport-sync\f1 is built. The default setting, \fBauto\f1, allows Shairport Sync to choose \fBsoxr\f1 mode if the system is powerful enough.
.TP
\fB-t \f1\fItimeout\f1\fB | --timeout=\f1\fItimeout\f1
Exit play mode if the stream disappears for more than \fItimeout\f1 seconds.
Print version information and exit.
.TP
\fB-v | --verbose\f1
-Print debug information to the \fISTDERR\f1, or to \fBsyslog\f1 if the \fB-log-to-syslog\f1 command line option is also chosen. Repeat up to three times (i.e. \fB-vv\f1 or \fB-vvv\f1) for more detail.
+Print debug information to the \fISTDERR\f1, or to \fBsyslog\f1 if the \fB-log-to-syslog\f1 command line option is also chosen. Repeat up to three times (i.e. \fB-vv\f1 or \fB-vvv\f1) for more detail. You should use \fB-vvv\f1 very sparingly -- it is really noisy.
.TP
\fB-w | --wait-cmd\f1
Wait for commands specified using \fB-B\f1 or \fB-E\f1 to complete before continuing execution.
.SH EXAMPLES
Here is a slightly contrived example:
-shairport-sync \fB-a "Joe's Stereo"\f1 \fB--\f1 \fB-d hw:1,0\f1 \fB-m hw:1\f1 \fB-c PCM\f1
+shairport-sync \fB-a "Joe's Stereo"\f1 \fB-o alsa\f1 \fB--\f1 \fB-d hw:1,0\f1 \fB-m hw:1\f1 \fB-c PCM\f1
-The program will be visible as "Joe's Stereo" ( \fB-a "Joe's Stereo"\f1 ). The audio backend options following the \fB--\f1 separator specify that the audio will be output on output 0 of soundcard 1 ( \fB-d hw:1,0\f1 ) and will take advantage of the same sound card's mixer ( \fB-m hw:1\f1 ) using the level control named "PCM" ( \fB-c "PCM"\f1 ).
+The program will be visible as "Joe's Stereo" ( \fB-a "Joe's Stereo"\f1 ). The program option \fB-o alsa\f1 specifies that the \fBalsa\f1 backend be used, thus that audio should be output into the \fBALSA\f1 audio subsystem. The audio backend options following the \fB--\f1 separator are passed to the \fBalsa\f1 backend and specify that the audio will be output on subdevice 0 of soundcard 1 ( \fB-d hw:1,0\f1 ) and will take advantage of the same sound card's mixer ( \fB-m hw:1\f1 ) using the level control named "PCM" ( \fB-c "PCM"\f1 ).
-The example above is slightly contrived: Firstly, output 0 is the default output of a card, so the output device could be written \fB-d hw:1\f1. Secondly, when a mixer name is given ( \fB-c "PCM"\f1 ), the default is that the mixer is on the output device, so the \fB-m hw:1\f1 is unnecessary here. These simplifications give the following command:
+The example above is slightly contrived: Firstly, if the \fBalsa\f1 backend has been included in the build, it will be the default, so it doesn't need to be specified and the \fB-o alsa\f1 option could be omitted. Secondly, subdevice 0 is the default for a soundcard, so the output device could simply be written \fB-d hw:1\f1. Thirdly, when a mixer name is given ( \fB-c "PCM"\f1 ), the default is that the mixer is on the output device, so the \fB-m hw:1\f1 is unnecessary here. Using these defaults and simplifications gives the following command:
shairport-sync \fB-a "Joe's Stereo"\f1 \fB--\f1 \fB-d hw:1\f1 \fB-c PCM\f1
.SH CREDITS
-Mike Brady (\fBhttps://github.com/mikebrady\f1) developed shairport-sync from Shairport by James Wah (\fBhttps://github.com/abrasive\f1).
-
-shairport-sync can be found at \fBhttps://github.com/mikebrady/shairport-sync.\f1
-
-Shairport can be found at \fBhttps://github.com/abrasive/shairport\f1
+Mike Brady (\fBhttps://github.com/mikebrady\f1) developed Shairport Sync from Shairport by James Wah (\fBhttps://github.com/abrasive\f1).
.SH COMMENTS
This man page was written using \fBxml2man(1)\f1 by Oliver Kurth.
<!--
<cmd>shairport-sync <opt>-D</opt> <arg>interface</arg></cmd>
-->
- <cmd>shairport-sync <opt>[-djvw]</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>[-c </opt><arg>configurationfile</arg><opt>]</opt>
- <opt>[-E </opt><arg>command</arg><opt>]</opt>
- <opt>[--get-cover-art]</opt>
+ <cmd>shairport-sync <opt>[-djvw]</opt>
+ <opt>[-a </opt><arg>service-name</arg><opt> | --name=</opt><arg>service-name</arg><opt>]</opt>
+ <opt>[-B </opt><arg>command</arg><opt> | --onstart=</opt><arg>command</arg><opt>]</opt>
+ <opt>[-c </opt><arg>configurationfile</arg><opt> | --configfile=</opt><arg>configurationfile</arg><opt>]</opt>
+ <opt>[-d | --daemon]</opt>
+ <opt>[-E </opt><arg>command</arg><opt> | --onstop=</opt><arg>command</arg><opt>]</opt>
+ <opt>[-g | --get-cover-art]</opt>
+ <opt>[-j | --justDaemoniseNoPIDFile]</opt>
<opt>[--logOutputLevel]</opt>
<opt>[--log-to-syslog]</opt>
- <opt>[-L </opt><arg>latency</arg><opt>]</opt>
- <opt>[-m </opt><arg>backend</arg><opt>]</opt>
- <opt>[--meta-dir=</opt><arg>directory</arg><opt>]</opt>
- <opt>[-o </opt><arg>backend</arg><opt>]</opt>
+ <opt>[-L </opt><arg>latency</arg><opt> | --latency=</opt><arg>latency</arg><opt>]</opt>
+ <opt>[-m </opt><arg>backend</arg><opt> | --mdns=</opt><arg>backend</arg><opt>]</opt>
+ <opt>[-M | --metadata-enable]</opt>
+ <opt>[-o </opt><arg>backend</arg><opt> | --output=</opt><arg>backend</arg><opt>]</opt>
+ <opt>[-p </opt><arg>port</arg><opt> | --port=</opt><arg>port</arg><opt>]</opt>
<opt>[--password=</opt><arg>secret</arg><opt>]</opt>
- <opt>[-r </opt><arg>threshold</arg><opt>]</opt>
+ <opt>[-r </opt><arg>threshold</arg><opt> | --resync=</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>[-S </opt><arg>mode</arg><opt> | --stuffing=</opt><arg>mode</arg><opt>]</opt>
+ <opt>[-t </opt><arg>timeout</arg><opt> | --timeout=</opt><arg>timeout</arg><opt>]</opt>
<opt>[--tolerance=</opt><arg>frames</arg><opt>]</opt>
+ <opt>[-v | --verbose]</opt>
+ <opt>[-w | --wait-cmd]</opt>
<opt>[-- </opt><arg>audio_backend_options</arg><opt>]</opt>
</cmd>
- <cmd>shairport-sync <opt>-k</opt></cmd>
+ <cmd>shairport-sync <opt>--displayConfig</opt></cmd>
<cmd>shairport-sync <opt>-h</opt></cmd>
+ <cmd>shairport-sync <opt>-k</opt></cmd>
<cmd>shairport-sync <opt>-V</opt></cmd>
</synopsis>
<description>
- <p>Shairport Sync plays audio streamed from an AirPlay or an AirPlay 2 device.
- AirPlay 2 support is limited, and AirPlay 2 from iTunes for Windows is not supported.
+ <p>Shairport Sync plays AirPlay audio.
+ It can be built to stream either from "classic" AirPlay (aka "AirPlay 1")
+ or from AirPlay 2 devices.</p>
- Please see <url href="https://github.com/mikebrady/shairport-sync"/> for details.</p>
-
- <p>Settings can be made using the configuration file (recommended for all new
- installations) or by using command-line options.</p>
+ <p>AirPlay 2 support is limited, and AirPlay 2 from iTunes for Windows is not supported.
+ For AirPlay 2 operation, a companion program called <opt>nqptp</opt> must be installed.</p>
- <p>The name of the Shairport Sync executable is <opt>shairport-sync</opt>.
- Both names are used in these man pages.</p>
+ <p>Please see <url href="https://github.com/mikebrady/shairport-sync"/> for details.</p>
+ <p>The name of the Shairport Sync executable is <opt>shairport-sync</opt>.</p>
+
</description>
<section name="Configuration File Settings">
- <p>You should use the configuration file for setting up Shairport Sync.
+ <p>You should use the configuration file for setting up Shairport Sync because --
+ apart from a few special-purpose commands -- it has a much richer set of options
+ than are available on the command line.
This file is usually <file>shairport-sync.conf</file> and is generally located in the
System Configuration Directory, which is normally the <file>/etc</file> directory in
Linux or the <file>/usr/local/etc</file> directory in BSD unixes.
<p>(Note: Shairport Sync may have been compiled to use a different configuration
directory. You can determine which by performing the command <file>$ shairport-sync
- -V</file>. One of the items in the output string is the value of the
- <opt>sysconfdir</opt>,
- i.e. the System Configuration Directory.)</p>
+ -V</file>. The last item in the output string is the value of the
+ <opt>sysconfdir</opt>, i.e. the System Configuration Directory.)</p>
<p>Within the configuration file, settings are organised into <i>groups</i>, for
- example, there is a "general" group of
+ example, there is a <opt>general</opt> group of
standard settings, and there is an <opt>alsa</opt> group with settings
that pertain to the <opt>ALSA</opt> back end.
Here is an example of a typical configuration file:</p>
<p><p><opt>mixer_control_name = "PCM";</opt></p></p>
<p><opt>};</opt></p>
- <p>Most settings have sensible default values, so -- as in the example above -- users
- generally only need to set (1) the service name and
+ <p>Users generally only need to set (1) the service name and
(2) the output device.
If the <opt>name</opt> setting is omitted, the service name is derived from the system's hostname.
<url href="https://github.com/mikebrady/shairport-sync/blob/master/scripts/shairport-sync.conf"/>.
Please refer to it for the most up-to-date information on configuration file settings.</p>
- <p>New features, etc. will generally be available only via configuration file settings.</p>
-
-
</section>
<options>
- <p>Many command-line options take sensible default values, so you can normally
- ignore most of them. See the EXAMPLES section for typical usages.</p>
-
<p>There are two kinds of command-line options for shairport-sync:
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>
+
+ <p>See the EXAMPLES section for sample usages.</p>
<section name="Program Options">
<p>Program Options are used by shairport-sync itself.</p>
Read configuration settings from <arg>filename</arg>. The default is to read them from
the <file>shairport-sync.conf</file> in the System Configuration Directory --
<file>/etc</file> in Linux, <file>/usr/local/etc</file> in BSD unixes.
- For information about configuration settings, see the "Configuration File Settings"
+ For information about configuration settings, see the "Configuration File Settings"
section above.
</p></optdesc>
</option>
Process ID (PID) to a file, usually at
<file>/var/run/shairport-sync/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. See also the <opt>-j</opt> option. Only available if
+ the daemon at a later time. See also the <opt>-j</opt> option. Only available if
shairport-sync has been compiled with libdaemon support.
</p></optdesc>
</option>
+ <option>
+ <p><opt>--displayConfig</opt></p>
+ <optdesc><p>
+ This will display information relating to the configuration of Shairport Sync.
+ It can be very useful for debugging. The information displayed is the version string
+ (which indicates the build options used when <opt>shairport-sync</opt> was built),
+ the contents of the command line that invoked Shairport Sync,
+ the name of the configuration file and the active settings therein.</p>
+ <p>If this is the only option on the command line, <opt>shairport-sync</opt> will
+ terminate after displaying the information.</p>
+ <p>Due to a limitation, <opt>--displayConfig</opt> always outputs to <file>STDERR</file>,
+ irrespective of the setting of <opt>--log-to-syslog</opt>.</p>
+ </optdesc>
+ </option>
+
<option>
<p><opt>-E </opt><arg>program</arg><opt> | --on-stop=</opt><arg>program</arg></p>
<optdesc><p>
</option>
<option>
- <p><opt>--get-coverart</opt></p>
+ <p><opt>-g | --get-coverart</opt></p>
<optdesc><p>
- This option requires the <opt>--meta-dir</opt> option to be set, and enables
- shairport-sync to request cover art from the source and to transmit it through
- the metadata pipe.</p>
- <p>Please note that cover art data may be very large, and may place too great a
- burden on your network.
- </p></optdesc>
+ This option requires the <opt>-M | --metadata-enable</opt> option to be set, and enables
+ shairport-sync to request cover art from the source and to process it as metadata.</p>
+ </optdesc>
</option>
<option>
</option>
<option>
- <p><opt>-j</opt></p>
+ <p><opt>-j | justDaemoniseNoPIDFile</opt></p>
<optdesc><p>
Instruct shairport-sync to demonise itself. Unlike the <opt>-d</opt> option, it will
not write a Process ID (PID) to a file -- it will just (hence the "j") demonise
<option>
<p><opt>--log-to-syslog</opt></p>
<optdesc><p>
- Warnings, error messages and messages are sent, by default, to <file>STDERR</file>. Use this option to route these messages to the <opt>syslog</opt> instead. This is intended for use when Shairport Sync is operating as a daemon.
- </p>
+ Warnings, error messages and messages are sent, by default, to <file>STDERR</file>.
+ Use this option to route these messages to the <opt>syslog</opt> instead.
+ This is intended for use when Shairport Sync is operating as a daemon.
+ </p><p>See also <opt>--displayConfig</opt>.</p>
</optdesc>
</option>
</option>
<option>
- <p><opt>--meta-dir=</opt><arg>directory</arg></p>
+ <p><opt>-M | --metadata-enable</opt></p>
<optdesc><p>
- Listen for metadata coming from the source and send it, along with metadata from
- shairport-sync itself, to a pipe called <arg>shairport-sync-metadata</arg>
- in the <arg>directory</arg> you specify. If you add the <opt>--get-cover-art</opt>
- then cover art will be sent through the pipe too. See <url
+ Ask the client to send metadata. It will be sent, along with metadata generated
+ by shairport-sync itself, to a pipe and will also be
+ sent as UDP packets.
+ If you add the <opt>-g | --get-cover-art</opt>
+ then cover art included, where available. See <url
href="https://github.com/mikebrady/shairport-sync-metadata-reader"/>
for a sample metadata reader.
</p></optdesc>
</option>
+ <option>
+ <p><opt>--metadata-pipename=</opt><arg>pathname</arg></p>
+ <optdesc><p>
+ Specify the path name for the metadata pipe.
+ Note that <opt>shairport-sync</opt> will need write permission on that directory and pipe.
+ The default is <file>/tmp/shairport-sync-metadata</file>.
+ If you rename the <opt>shairport-sync</opt> executable, the default pipe name will change accordingly.
+ </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
+ player on the network. The default is to try all mDNS backends in order until one
works.
</p></optdesc>
</option>
<option>
<p><opt>--statistics</opt></p>
<optdesc><p>
- Print some performance information <file>STDERR</file>, or to <opt>syslog</opt> if the <opt>-log-to-syslog</opt> command line option is also chosen.
+ Print some performance information to <file>STDERR</file>, or to <opt>syslog</opt> if the <opt>-log-to-syslog</opt> command line option is also chosen.
</p></optdesc>
</option>
stream sent to the output device in order to keep it synchronised
with the player.
The <opt>basic</opt> mode is normally almost completely inaudible.
- The alternative mode, <opt>soxr</opt>, is even less obtrusive but
+ 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.
+ <opt>libsoxr</opt>, the SoX Resampler Library, must be selected when
+ <opt>shairport-sync</opt> is built.
The default setting, <opt>auto</opt>, allows Shairport Sync to choose
<opt>soxr</opt> mode if the system is powerful enough.
<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>
+ 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>,
+ 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><opt>-v | --verbose</opt></p>
<optdesc><p>
Print debug information to the <file>STDERR</file>, or to <opt>syslog</opt> if the <opt>-log-to-syslog</opt> command line option is also chosen.
- Repeat up to three times (i.e. <opt>-vv</opt> or <opt>-vvv</opt>) for more detail.
+ Repeat up to three times (i.e. <opt>-vv</opt> or <opt>-vvv</opt>) for more detail. You should use <opt>-vvv</opt> very sparingly -- it is really noisy.
</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
+ Wait for commands specified using <opt>-B</opt> or <opt>-E</opt> to complete before
continuing execution.
</p></optdesc>
</option>
options and reused as audio backend options without ambiguity.</p>
<p>Audio backends are listed with their corresponding Audio Backend Options in the help text provided by the help (<opt>-h</opt> or <opt>--help</opt>) option.</p>
- </section>
+ </section>
</options>
<section name="Examples">
<p>Here is a slightly contrived example:</p>
<cmd>shairport-sync
<opt>-a "Joe's Stereo"</opt>
+ <opt>-o alsa</opt>
<opt>--</opt>
<opt>-d hw:1,0</opt>
<opt>-m hw:1</opt>
</cmd>
<p>The program will be visible as
"Joe's Stereo" ( <opt>-a "Joe's Stereo"</opt> ).
- The audio backend options following the <opt>--</opt> separator specify
- that the audio will be output on output 0 of soundcard 1
+ The program option <opt>-o alsa</opt> specifies that the <opt>alsa</opt> backend be used, thus that audio should be output into the <opt>ALSA</opt> audio subsystem.
+ The audio backend options following the <opt>--</opt> separator are passed to the <opt>alsa</opt> backend and specify
+ that the audio will be output on subdevice 0 of soundcard 1
( <opt>-d hw:1,0</opt> ) and will take advantage of the same sound card's mixer
( <opt>-m hw:1</opt> ) using the level control named "PCM" ( <opt>-c "PCM"</opt> ).
</p>
- <p>The example above is slightly contrived: Firstly, output 0 is the default output of a card,
- so the output device could be written <opt>-d hw:1</opt>.
- Secondly, when a mixer name is given ( <opt>-c "PCM"</opt> ),
- the default is that the mixer is on the output device, so the <opt>-m hw:1</opt> is unnecessary here.
- These simplifications give the following command:</p>
+ <p>The example above is slightly contrived:
+ Firstly, if the <opt>alsa</opt> backend has been included in the build, it will be the default, so it doesn't need to be specified and the <opt>-o alsa</opt> option could be omitted.
+ Secondly, subdevice 0 is the default for a soundcard, so the output device could simply be written <opt>-d hw:1</opt>.
+ Thirdly, when a mixer name is given ( <opt>-c "PCM"</opt> ), the default is that the mixer is on the output device, so the <opt>-m hw:1</opt> is unnecessary here.
+ Using these defaults and simplifications gives the following command:</p>
<cmd>shairport-sync
<opt>-a "Joe's Stereo"</opt>
<opt>--</opt>
</section>
<section name="Credits">
- <p>Mike Brady (<url href="https://github.com/mikebrady"/>) developed shairport-sync from Shairport by James Wah (<url href="https://github.com/abrasive"/>).</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>
+ <p>Mike Brady (<url href="https://github.com/mikebrady"/>) developed Shairport Sync from Shairport by James Wah (<url href="https://github.com/abrasive"/>).</p>
</section>
<section name="Comments">
projects / thirdparty / shairport-sync.git / commitdiff
