bionic (7) shairport-sync.7.gz
NAME
shairport-sync - Synchronised Audio Player for iTunes / AirPlay
SYNOPSIS
shairport-sync [-djvw] [-a name] [-A latency] [-B command] [-c configurationfile] [-E command] [--get-
cover-art] [--logOutputLevel] [-L latency] [-m backend] [--meta-dir=directory] [-o backend]
[--password=secret] [-r threshold] [--statistics] [-S mode] [-t timeout] [--tolerance=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 device to an ALSA compatible audio
output device (available on Linux and FreeBSD) , to a "sndio" output device (available on OpenBSD,
FreeBSD and Linux) or to a PulseAudio output stream (available on Linux).
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 operation.
shairport-sync can be compiled to stream audio, without synchronisation, to a pipe, to stdout or to a
libao output device (an "AO" device). 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
directory 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 configuration 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.)
Within the configuration file, 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 configuration file:
general = {
name = "Mike's Boombox";
interpolation = "soxr";
password = "secret";
output_backend = "alsa";
};
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 number,
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. Interpolation 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, "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.
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 itself. 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. Perform the command shairport-sync -h to get a list of available audio
backends -- the default is the first on this list. Only the "alsa", "sndio" and "pa" backends
support 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 previous 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 synchronization before attempting to correct
it. The default is 0.002 seconds, 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 statistics
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 milliseconds. Specify 0.0 to disable
resynchronisation. This setting 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,
independently 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 example, 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 default 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
Apple. Shairport Sync must have been compiled with the configuration setting "--with-apple-alac"
and the Apple ALAC decoder library must be present for this to work.
audio_backend_latency_offset_in_seconds=offset_in_seconds;
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_in_seconds;
Use this length_in_seconds to set the desired length of the queue of audio frames in the backend's
output buffer.
The default is 0.15 seconds for the ALSA backend, 0.35 seconds for the PA backend and one second
for all other backends.
If this value is set too small, underflow may occur on low-powered machines. If set too large, the
response times to the volume control may become excessive, or it may exceed the backend's buffer
size. It may need to be larger on low-powered machines that are also performing other tasks, such
as processing metadata.
audio_backend_silent_lead_in_time=lead_in_time_in_seconds;
This is an advanced setting. Use the lead_in_time_in_seconds to set the desired length of the
period of silence (a "silent lead-in") played before a play session begins.
The purpose of this silent lead-in is to give the backend sufficient time to prepare for operation
and to make an estimate (and, importantly, to correct the estimate) of the exact time at which to
begin playing audio to achieve initial synchronisation. The value can be from 0.0 up to a maximum
of either 4.0 seconds. The actual duration will be close to the setting but can not exceed the
latency set by the client, usually 2 seconds or a little more.
If the value chosen is too short for synchronised backends such as the ALSA, sndio or PA backends,
then audio will not be synchronised correctly at the start of play. The default is to have a
silent lead-in of approximately the same time as the latency set by the client.
run_this_when_volume_is_set="/full/path/to/application/and/args";
Here you can specify a program and its arguments that will be run when the volume is set or
changed. 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.
The desired AirPlay volume is appended to the end of the command line – leave a space if you want
it treated as an extra argument. AirPlay volume goes from 0.0 to -30.0 and -144.0 means "mute".
"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 devices
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_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.
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), endianness 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 interpolation. 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 experience
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".
mute_using_playback_switch="yes";
This is an advanced setting and the default is "yes", which means that hardware mute will be
implemented using a feature called a 'playback switch', where one is available; set it to "no" to
prevent the playback switch being used.
The motivation for this is to avoid using the alsa function call
"snd_mixer_selem_set_playback_switch_all", which is incorrectly implemented on certain soundcards,
including the emulated card in VMWare Fusion 8.5.
"SNDIO" SETTINGS
These settings are for the SNDIO back end, used to communicate with audio output devices in the
SNDIO system.
device="snd/0";
Use this optional setting to specify the name of the output device, e.g. "snd/0". The default is
to use the SNDIO system's default.
rate=44100;
Use this optional setting to specify the output rate in frames per second. Valid rates are 44100,
88200, 176400 or 352800. The output device must have the capability to accept data at the
specified rate. The default is 44100.
format="S16";
Use this optional setting to specify the output format. 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), endianness matches that of the processor. The default is "S16".
Since the SNDIO backend does not use a hardware mixer for volume control, dither will be
introduced into the output if it is less than full volume. Thus, (unless you are ignoring the
volume control setting), consider using 32- or 24-bit output if your device is capable of it, to
get the lowest possible levels of dither.
Please note that 32- or 24-bit has not been extensively tested on SNDIO.
round=value;
Use this optional advanced setting to specify the period size of the SNDIO channel. If omitted, a
SNDIO system default value will be used.
bufsiz=value;
Use this optional advanced setting to specify the buffer size of the SNDIO channel. If omitted, a
SNDIO system default value will be used.
"PA" SETTINGS
These settings are for the new PulseAudio backend.
application_name="Shairport Sync";
Use this to set the name to appear in the Sounds "Applications" tab when Shairport Sync is active.
The default is the name "Shairport Sync".
"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.
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.
"STDOUT" SETTINGS
There are no settings for the STDOUT backend.
"AO" SETTINGS
There are no configuration file settings for the AO backend.
"METADATA" SETTINGS
shairport-sync can process metadata provided by the source, such as Track Number, Album Name,
cover art, etc. and can provide additional 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 identification 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 handling 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 metadata 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 between 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 programs specified in the
run_this_before_play_begins, run_this_after_play_ends and run_this_when_volume_is_set have
completed execution before continuing. 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 network) 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 configuration file settings described above. Most of the command-line
options 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 normally 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 number,
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 completed 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 Configuration Directory -- /etc in Linux, /usr/local/etc in BSD unixes.
For information about configuration settings, see the "Configuration 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/shairport-sync.pid, which is used by the -k, -D and -R options to
locate the daemon at a later time. See also the -j option.
-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.
--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.
-h | --help
Print brief help message and exit.
-j Instruct shairport-sync to demonise itself. Unlike the -d option, it will not write a Process ID
(PID) to a file -- it will just (hence the "j") demonise itself.
-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).
--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 earlier 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.
-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 milliseconds. Specify 0 to disable
resynchronisation. This setting is deprecated and will be removed in a future version of
shairport-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 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. This setting is
deprecated and will be removed 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 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 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 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
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 soundcard 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.