473 lines
19 KiB
XML
473 lines
19 KiB
XML
<?xml version="1.0"?><!--*-nxml-*-->
|
|
<!DOCTYPE manpage SYSTEM "xmltoman.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="xmltoman.xsl" ?>
|
|
|
|
<!--
|
|
This man page source file is part of shairport-sync.
|
|
Copyright (c) Mike Brady 2014-2022
|
|
|
|
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="AirPlay and AirPlay 2 Audio Player">
|
|
|
|
<synopsis>
|
|
<!--
|
|
<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>
|
|
<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>[--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>-k</opt></cmd>
|
|
<cmd>shairport-sync <opt>-h</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.
|
|
|
|
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>The name of the Shairport Sync executable is <opt>shairport-sync</opt>.
|
|
Both names are used in these man pages.</p>
|
|
|
|
</description>
|
|
|
|
|
|
<section name="Configuration File Settings">
|
|
<p>You should use the configuration file for setting up Shairport Sync.
|
|
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.
|
|
You may need to have root privileges to modify it.</p>
|
|
|
|
<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>
|
|
|
|
<p>Within the configuration file, settings are organised into <i>groups</i>, for
|
|
example, there is a "general" 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><opt>general = {</opt></p>
|
|
<p><p><opt>name = "Mike's Boombox";</opt></p></p>
|
|
<p><opt>};</opt></p>
|
|
<p><opt></opt></p>
|
|
<p><opt>alsa = {</opt></p>
|
|
<p><p><opt>output_device = "hw:0";</opt></p></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
|
|
(2) the output device.
|
|
|
|
If the <opt>name</opt> setting is omitted, the service name is derived from the system's hostname.
|
|
|
|
By default, the <opt>ALSA</opt> 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.</p>
|
|
|
|
<p>A sample configuration file with all possible settings, but with all of them
|
|
commented out, is installed at <file>shairport-sync.conf.sample</file>, within the
|
|
System Configuration Directory -- <file>/etc</file> in Linux,
|
|
<file>/usr/local/etc</file> in BSD unixes.</p>
|
|
|
|
<p>The sample configuration file includes extensive documentation of the settings.
|
|
and is also available at
|
|
<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>
|
|
|
|
<section name="Program Options">
|
|
<p>Program 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.</p>
|
|
|
|
<p>The following substitutions are allowed:
|
|
<opt>%h</opt> for the computer's hostname,
|
|
<opt>%H</opt> for the computer's hostname with the first letter capitalised (ASCII
|
|
only),
|
|
<opt>%v</opt> for the shairport-sync version number, e.g. "3.0.1" and
|
|
<opt>%V</opt> for the shairport-sync version string, e.g.
|
|
"3.0.1-OpenSSL-Avahi-ALSA-soxr-metadata-sysconfdir:/etc".</p>
|
|
<p>The default is "%H", which is replaced by the hostname with the first letter
|
|
capitalised.</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 the appropriate shebang
|
|
(<file>#!/bin/sh</file>) 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>-c </opt><arg>filename</arg><opt> | --configfile=</opt><arg>filename</arg></p>
|
|
<optdesc><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"
|
|
section above.
|
|
</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/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
|
|
shairport-sync has been compiled with libdaemon support.
|
|
</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 the appropriate shebang
|
|
(<file>#!/bin/sh</file>) 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>--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>
|
|
</option>
|
|
|
|
<option>
|
|
<p><opt>-h | --help</opt></p>
|
|
<optdesc><p>
|
|
Print brief help message and exit.
|
|
</p></optdesc>
|
|
</option>
|
|
|
|
<option>
|
|
<p><opt>-j</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
|
|
itself. Only available if shairport-sync has been compiled with libdaemon support.
|
|
</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. Only available if
|
|
shairport-sync has been compiled with libdaemon support.)
|
|
</p></optdesc>
|
|
</option>
|
|
|
|
<option>
|
|
<p><opt>--logOutputLevel</opt></p>
|
|
<optdesc><p>
|
|
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.
|
|
</p>
|
|
</optdesc>
|
|
</option>
|
|
|
|
<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>
|
|
</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>
|
|
<p>Please note that this feature is deprecated and will be removed in a future version
|
|
of shairport-sync.</p>
|
|
</optdesc>
|
|
</option>
|
|
|
|
<option>
|
|
<p><opt>--meta-dir=</opt><arg>directory</arg></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
|
|
href="https://github.com/mikebrady/shairport-sync-metadata-reader"/>
|
|
for a sample metadata reader.
|
|
</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.
|
|
</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 for AirPlay and 7000 for AirPlay 2.
|
|
</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. (This only works for AirPlay and not for AirPlay 2.)
|
|
</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. This setting is
|
|
deprecated and will be removed in a future version of shairport-sync.
|
|
</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.
|
|
</p></optdesc>
|
|
</option>
|
|
|
|
<option>
|
|
<p><opt>-S </opt><arg>mode</arg><opt> | --stuffing=</opt><arg>mode</arg></p>
|
|
<optdesc><p>
|
|
Interpolate ("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 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
|
|
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, <opt>auto</opt>, allows Shairport Sync to choose
|
|
<opt>soxr</opt> mode if the system is powerful enough.
|
|
</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.
|
|
This setting is deprecated and will be removed in a future version of shairport-sync.
|
|
</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 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.
|
|
</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>Audio Backend Options are command-line options that are passed to the chosen audio backend.
|
|
They are always preceded by the <opt>--</opt> symbol to introduce them and to separate them from
|
|
any preceding program options. In this way, option letters can be used as program
|
|
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>
|
|
</options>
|
|
|
|
<section name="Examples">
|
|
<p>Here is a slightly contrived example:</p>
|
|
<cmd>shairport-sync
|
|
<opt>-a "Joe's Stereo"</opt>
|
|
<opt>--</opt>
|
|
<opt>-d hw:1,0</opt>
|
|
<opt>-m hw:1</opt>
|
|
<opt>-c PCM</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
|
|
( <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 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>-a "Joe's Stereo"</opt>
|
|
<opt>--</opt>
|
|
<opt>-d hw:1</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>
|