You should use the configuration file for setting up shairport-sync. This file is normally /etc/shairport-sync.conf. You may need to have root privileges to modify it.

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";

};

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 /etc/shairport-sync.conf.sample.

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 .

These are the settings available within the general group:

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:

mixer_type="mixer_type";

This setting is deprecated and is ignored. For your information, its functionality has been automatically incorporated in the mixer_control_name setting -- if you specify a mixer name with the mixer_control_name setting, it is assumed that the mixer is implemented in hardware.

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.

Use the name setting to set the name and location of the pipe.

There are two further settings affecting timing that might be useful if the pipe reader is, for example, a program to play an audio stream such as aplay. The audio_backend_latency_offset affects precisely when the first audio packet is sent and the audio_backend_buffer_desired_length setting affects the nominal output buffer size.

These are the settings available within the pipe group:

These settings are for the STDOUT backend, used to route audio to standard output ("stdout"). The audio is in raw CD audio format: PCM 16 bit little endian, 44,100 samples per second, interleaved stereo.

There are two settings affecting timing that might be useful if the stdout reader is, for example, a program to play an audio stream such as aplay. The audio_backend_latency_offset affects precisely when the first audio packet is sent and the audio_backend_buffer_desired_length setting affects the nominal output buffer size.

These are the settings available within the stdout group:

These settings are for the AO backend, used for the libao audio library.

There are two settings affecting timing. The audio_backend_latency_offset affects precisely when the first audio packet is sent and the audio_backend_buffer_desired_length setting affects the nominal output buffer size.

These are the settings available within the ao group:

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:

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.

The latencies settings are now deprecated. Do not use them for new installations. They will be removed from a future version of shairport-sync.

Latency is the exact time from a sound signal's original timestamp until that signal actually "appears" on the output of the audio output device, usually a Digital to Audio Converter (DAC), irrespective of any internal delays, processing times, etc. in the computer.

shairport-sync now sets latencies automatically using information supplied by the source, typically either 88,200 or 99,577 frames.

The following relates to the old scheme of using fixed latencies, which ignored the latency information supplied by the source. There are four default latency settings. One latency matches the latency used by recent versions of iTunes when playing audio and another matches the latency used by so-called "AirPlay" devices, including iOS devices and iTunes and Quicktime Player when they are playing video. A third latency is used when the audio source is forked-daapd. The fourth latency is the default if no other latency is chosen and is used for older versions of iTunes.

Note: If you are thinking of changing latencies to compensate for a delay in the audio output device, then instead of changing these individual latencies, use the audio_backend_latency_offset setting in the alsa group (or the appropriate other group if you're not outputing through the alsa backend).