**New Feature**
* Set Volume Range. This is a new setting that allows you to use just a portion of the full range of attenuation offered by a mixer. 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. Or it might be because 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 35dB. The new `volume_range_db` setting in the `general` stanza allows you to specify the maximum range from highest to lowest. Many domestic Hi Fi systems have a range of 60 to 80 dB. The range suggested for the Raspberry Pi's built-in audio DAC, which feeds the headphone jack, is 35. Using it in this case gives the volume control a much more useful range of settings.
+**Other Changes**
+* Initial timing accuracy improved. The estimate of when to play the starting frame of the audio sequence has improved significantly.
+
Version 2.5.0.8
----
**Bug fix**
\fBignore_volume_control=\f1\fI"choice"\f1\fB;\f1
Set this \fIchoice\f1 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".
.TP
-\fB"LATENCIES" SETTINGS\f1
-There are four default latency settings, chosen automatically. 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.
-
-If you want to change latencies to compensate for a delay in the audio output device (which will have the same effect on all sources), instead of changing these individual latencies, consider using the \fBaudio_backend_latency_offset\f1 setting in the \fBalsa\f1 group (or the appropriate other group if you're not outputing through the alsa backend).
-.TP
-\fBitunes=\f1\fIlatency\f1\fB;\f1
-This is the \fIlatency\f1, in frames, used for iTunes 10 or later. Default is 99,400.
-.TP
-\fBairplay=\f1\fIlatency\f1\fB;\f1
-This is the \fIlatency\f1, in frames, used for AirPlay devices, including iOS devices and iTunes and Quicktime Player when they are playing video. Default is 88,200.
-.TP
-\fBforkedDaapd=\f1\fIlatency\f1\fB;\f1
-This is the \fIlatency\f1, in frames, used for forkedDaapd sources. Default is 99,400.
-.TP
-\fBdefault=\f1\fIlatency\f1\fB;\f1
-This is the \fIlatency\f1, in frames, used when the source is unrecognised. Default is 88,200.
-.TP
-\fB"METADATA" SETTINGS\f1
-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 provides the metadata to a pipe, by default \fI/tmp/shairport-sync-metadata\f1. To process metadata, shairport-sync must have been compiled with metadata support included. You can check that this is so by running \fBshairport-sync -V\f1; the identification string will contain the word \fBmetadata\f1.
-
-The \fBmetadata\f1 group of settings allow you to enable metadata handling and to control certain aspects of it:
-.TP
-\fBenabled=\f1\fI"choice"\f1\fB;\f1
-Set the \fIchoice\f1 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".
-.TP
-\fBinclude_cover_art=\f1\fI"choice"\f1\fB;\f1
-Set the \fIchoice\f1 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".
-.TP
-\fBpipe_name=\f1\fI"filepathname"\f1\fB;\f1
-Specify the absolute path name of the pipe through which metadata should be sent The default is \fI/tmp/shairport-sync-metadata\f1".
-.TP
-\fB"SESSIONCONTROL" SETTINGS\f1
-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.
-.TP
-\fBrun_this_before_play_begins=\f1\fI"/path/to/application and args"\f1\fB;\f1
-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 \fI#!/bin/...\f1 as appropriate.
-.TP
-\fBrun_this_after_play_ends=\f1\fI"/path/to/application and args"\f1\fB;\f1
-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 \fI#!/bin/...\f1 as appropriate.
-.TP
-\fBwait_for_completion=\f1\fI"choice"\f1\fB;\f1
-Set \fIchoice\f1 to "yes" to make shairport-sync wait until the programs specified in the \fBrun_this_before_play_begins\f1 and \fBrun_this_after_play_ends\f1 have completed execution before continuing. The default is "no".
-.TP
-\fBallow_session_interruption=\f1\fI"choice"\f1\fB;\f1
-If \fBchoice\f1 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.
-.TP
-\fBsession_timeout=\f1\fIseconds\f1\fB;\f1
-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 \fIseconds\f1 seconds before ending the session. Once the session has terminated, other devices can use it. The default is 120 seconds.
+\fBvolume_range_db=\f1\fIdBvalue\f1\fB;\f1
+Set this \fIdBvalue\f1 to use just a portion of the full range of attenuation offered by a mixer. 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. Or it might be because 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 35dB. The setting allows you to specify the maximum range from highest to lowest. Many domestic HiFi systems have a range of 60 to 80 dB. The range suggested for the Raspberry Pi's built-in audio DAC, which feeds the headphone jack, is 35. Using it in this case gives the volume control a much more useful range of settings. If you omit this setting, the full "native" range of the output device is used.
.TP
\fB"ALSA" SETTINGS\f1
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 \fBalsamixer\f1 or \fBaplay\f1 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 \fBalsa\f1 group settings:
.TP
\fBmixer_control_name=\f1\fI"name"\f1\fB;\f1
Specify the \fIname\f1 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. \fBmixer_type=\f1\fI"mixer_type"\f1\fB;\f1
-This setting is deprecated and will be removed soon. If you wish to use a mixer control to control the volume, then set \fImixer_type\f1 to "hardware". The default is "software".
+This setting is deprecated and ignored and will be removed soon.
.TP
\fBmixer_device=\f1\fI"mixer_device"\f1\fB;\f1
By default, the mixer is assumed to be output_device. Use this setting to specify a device other than the output device.
.TP
\fBaudio_backend_buffer_desired_length=\f1\fIbuffer_length_in_frames\f1\fB;\f1
Use this setting, in frames, to set the size of the output buffer. It works by determining how soon the second and subsequent packets of audio frames are sent to stdout. For example, if you send the first packet of audio exactly when it is due and, using a \fIaudio_backend_buffer_desired_length\f1 setting of 44100, send subsequent packets of audio a second before they are due to be played, they will be buffered in the stdout reader's buffer, giving it a nominal buffer size of 44,100 frames. Note that if the stdout reader consumes audio packets faster or slower than they are supplied, the buffer will eventually empty or overflow -- shairport-sync performs no stuffing or interpolation when writing to stdout. Default setting is 44,100 frames.
+.TP
+\fB"METADATA" SETTINGS\f1
+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 \fI/tmp/shairport-sync-metadata\f1. To process metadata, shairport-sync must have been compiled with metadata support included. You can check that this is so by running \fBshairport-sync -V\f1; the identification string will contain the word \fBmetadata\f1.
+
+Please note that different sources provide different levels of metadata. Some provide a lot; some provide almost none.
+
+The \fBmetadata\f1 group of settings allow you to enable metadata handling and to control certain aspects of it:
+.TP
+\fBenabled=\f1\fI"choice"\f1\fB;\f1
+Set the \fIchoice\f1 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".
+.TP
+\fBinclude_cover_art=\f1\fI"choice"\f1\fB;\f1
+Set the \fIchoice\f1 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".
+.TP
+\fBpipe_name=\f1\fI"filepathname"\f1\fB;\f1
+Specify the absolute path name of the pipe through which metadata should be sent The default is \fI/tmp/shairport-sync-metadata\f1".
+.TP
+\fB"SESSIONCONTROL" SETTINGS\f1
+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.
+.TP
+\fBrun_this_before_play_begins=\f1\fI"/path/to/application and args"\f1\fB;\f1
+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 \fI#!/bin/...\f1 as appropriate.
+.TP
+\fBrun_this_after_play_ends=\f1\fI"/path/to/application and args"\f1\fB;\f1
+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 \fI#!/bin/...\f1 as appropriate.
+.TP
+\fBwait_for_completion=\f1\fI"choice"\f1\fB;\f1
+Set \fIchoice\f1 to "yes" to make shairport-sync wait until the programs specified in the \fBrun_this_before_play_begins\f1 and \fBrun_this_after_play_ends\f1 have completed execution before continuing. The default is "no".
+.TP
+\fBallow_session_interruption=\f1\fI"choice"\f1\fB;\f1
+If \fBchoice\f1 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.
+.TP
+\fBsession_timeout=\f1\fIseconds\f1\fB;\f1
+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 \fIseconds\f1 seconds before ending the session. Once the session has terminated, other devices can use it. The default is 120 seconds.
+.TP
+\fB"LATENCIES" SETTINGS\f1
+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 ignores 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, consider using the \fBaudio_backend_latency_offset\f1 setting in the \fBalsa\f1 group (or the appropriate other group if you're not outputing through the alsa backend).
+.TP
+\fBitunes=\f1\fIlatency\f1\fB;\f1
+This is the \fIlatency\f1, in frames, used for iTunes 10 or later. Default is 99,400.
+.TP
+\fBairplay=\f1\fIlatency\f1\fB;\f1
+This is the \fIlatency\f1, in frames, used for AirPlay devices, including iOS devices and iTunes and Quicktime Player when they are playing video. Default is 88,200.
+.TP
+\fBforkedDaapd=\f1\fIlatency\f1\fB;\f1
+This is the \fIlatency\f1, in frames, used for forkedDaapd sources. Default is 99,400.
+.TP
+\fBdefault=\f1\fIlatency\f1\fB;\f1
+This is the \fIlatency\f1, in frames, used when the source is unrecognised. Default is 88,200.
.SH OPTIONS
-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 options described below simply replicate the configuration settings and are retained to provide backward compatability with older installations of 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 options described below simply replicate the configuration settings and are retained to provide backward compatability with older installations of Shairport Sync.
Many of the options take sensible default values, so you can normally ignore most of them. See the EXAMPLES section for typical usages.
shairport-sync \fB-d\f1 \fB-a "Joe's Stereo"\f1 \fB-S soxr\f1 \fB--\f1 \fB-d hw:1\f1 \fB-c PCM\f1
.SH CREDITS
-Mike Brady developed shairport-sync from the original shairport by James Laird.
+Mike Brady developed Shairport Sync from the original Shairport by James Laird.
-shairport-sync can be found at \fBhttps://github.com/mikebrady/shairport-sync.\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
+Shairport can be found at \fBhttps://github.com/abrasive/shairport.\f1
.SH COMMENTS
This man page was written using \fBxml2man(1)\f1 by Oliver Kurth.
<optdesc>Set this <arg>choice</arg> 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".</optdesc>
</option>
- <option><p><opt>"LATENCIES" SETTINGS</opt></p></option>
- <p>There are four default latency settings, chosen automatically. 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.</p>
- <p>If you want to change latencies to compensate for a delay in the audio output device (which will have the same effect on all sources), instead of changing these individual latencies, consider using the <opt>audio_backend_latency_offset</opt> setting in the <opt>alsa</opt> group (or the appropriate other group if you're not outputing through the alsa backend).</p>
-
-
- <option>
- <p><opt>itunes=</opt><arg>latency</arg><opt>;</opt></p>
- <optdesc>This is the <arg>latency</arg>, in frames, used for iTunes 10 or later. Default is 99,400.</optdesc>
- </option>
- <option>
- <p><opt>airplay=</opt><arg>latency</arg><opt>;</opt></p>
- <optdesc>This is the <arg>latency</arg>, in frames, used for AirPlay devices, including iOS devices and iTunes and Quicktime Player when they are playing video. Default is 88,200.</optdesc>
- </option>
- <option>
- <p><opt>forkedDaapd=</opt><arg>latency</arg><opt>;</opt></p>
- <optdesc>This is the <arg>latency</arg>, in frames, used for forkedDaapd sources. Default is 99,400.</optdesc>
- </option>
- <option>
- <p><opt>default=</opt><arg>latency</arg><opt>;</opt></p>
- <optdesc>This is the <arg>latency</arg>, in frames, used when the source is unrecognised. Default is 88,200.</optdesc>
- </option>
-
- <option><p><opt>"METADATA" SETTINGS</opt></p></option>
- <p>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 provides the metadata to a pipe, by default <file>/tmp/shairport-sync-metadata</file>.
- To process metadata, shairport-sync must have been compiled with metadata support included.
- You can check that this is so by running <opt>shairport-sync -V</opt>; the identification string will contain the word <opt>metadata</opt>.</p>
- <p>The <opt>metadata</opt> group of settings allow you to enable metadata handling and to control certain aspects of it:</p>
-
-
- <option>
- <p><opt>enabled=</opt><arg>"choice"</arg><opt>;</opt></p>
- <optdesc>Set the <arg>choice</arg> 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".</optdesc>
- </option>
- <option>
- <p><opt>include_cover_art=</opt><arg>"choice"</arg><opt>;</opt></p>
- <optdesc>Set the <arg>choice</arg> 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".</optdesc>
- </option>
<option>
- <p><opt>pipe_name=</opt><arg>"filepathname"</arg><opt>;</opt></p>
- <optdesc>Specify the absolute path name of the pipe through which metadata should be sent The default is <file>/tmp/shairport-sync-metadata</file>".</optdesc>
+ <p><opt>volume_range_db=</opt><arg>dBvalue</arg><opt>;</opt></p>
+ <optdesc>Set this <arg>dBvalue</arg> to use just a portion of the full range of attenuation offered by a mixer. 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. Or it might be because 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 35dB. The setting allows you to specify the maximum range from highest to lowest. Many domestic HiFi systems have a range of 60 to 80 dB. The range suggested for the Raspberry Pi's built-in audio DAC, which feeds the headphone jack, is 35. Using it in this case gives the volume control a much more useful range of settings. If you omit this setting, the full "native" range of the output device is used.</optdesc>
</option>
-
- <option><p><opt>"SESSIONCONTROL" SETTINGS</opt></p></option>
- <p>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. </p>
- <option>
- <p><opt>run_this_before_play_begins=</opt><arg>"/path/to/application and args"</arg><opt>;</opt></p>
- <optdesc>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 <file>#!/bin/...</file> as appropriate.</optdesc>
- </option>
- <option>
- <p><opt>run_this_after_play_ends=</opt><arg>"/path/to/application and args"</arg><opt>;</opt></p>
- <optdesc>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 <file>#!/bin/...</file> as appropriate.</optdesc>
- </option>
- <option>
- <p><opt>wait_for_completion=</opt><arg>"choice"</arg><opt>;</opt></p>
- <optdesc>Set <arg>choice</arg> to "yes" to make shairport-sync wait until the programs specified in the <opt>run_this_before_play_begins</opt>
- and <opt>run_this_after_play_ends</opt> have completed execution before continuing. The default is "no".</optdesc>
- </option>
- <option>
- <p><opt>allow_session_interruption=</opt><arg>"choice"</arg><opt>;</opt></p>
- <optdesc>If <opt>choice</opt> 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.</optdesc>
- </option>
- <option>
- <p><opt>session_timeout=</opt><arg>seconds</arg><opt>;</opt></p>
- <optdesc>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 <arg>seconds</arg> seconds before ending the session. Once the session has terminated, other devices can use it.
- The default is 120 seconds.</optdesc>
- </option>
<option><p><opt>"ALSA" SETTINGS</opt></p></option>
<p>These settings are for the ALSA back end, used to communicate with audio output devices in the ALSA system.
If you do not specify a mixer control name, shairport-sync will adjust the volume in software.</optdesc>
</option>
<p><opt>mixer_type=</opt><arg>"mixer_type"</arg><opt>;</opt></p>
- <optdesc>This setting is deprecated and will be removed soon. If you wish to use a mixer control to control the volume, then set <arg>mixer_type</arg> to "hardware".
- The default is "software".</optdesc>
+ <optdesc>This setting is deprecated and ignored and will be removed soon.</optdesc>
</option>
<option>
<p><opt>mixer_device=</opt><arg>"mixer_device"</arg><opt>;</opt></p>
shairport-sync performs no stuffing or interpolation when writing to stdout. Default setting is 44,100 frames.
</optdesc>
</option>
+
+ <option><p><opt>"METADATA" SETTINGS</opt></p></option>
+ <p>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 <file>/tmp/shairport-sync-metadata</file>.
+ To process metadata, shairport-sync must have been compiled with metadata support included.
+ You can check that this is so by running <opt>shairport-sync -V</opt>; the identification string will contain the word <opt>metadata</opt>.</p>
+ <p>Please note that different sources provide different levels of metadata. Some provide a lot; some provide almost none.</p>
+ <p>The <opt>metadata</opt> group of settings allow you to enable metadata handling and to control certain aspects of it:</p>
+
+
+ <option>
+ <p><opt>enabled=</opt><arg>"choice"</arg><opt>;</opt></p>
+ <optdesc>Set the <arg>choice</arg> 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".</optdesc>
+ </option>
+ <option>
+ <p><opt>include_cover_art=</opt><arg>"choice"</arg><opt>;</opt></p>
+ <optdesc>Set the <arg>choice</arg> 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".</optdesc>
+ </option>
+ <option>
+ <p><opt>pipe_name=</opt><arg>"filepathname"</arg><opt>;</opt></p>
+ <optdesc>Specify the absolute path name of the pipe through which metadata should be sent The default is <file>/tmp/shairport-sync-metadata</file>".</optdesc>
+ </option>
+
+ <option><p><opt>"SESSIONCONTROL" SETTINGS</opt></p></option>
+ <p>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. </p>
+
+
+ <option>
+ <p><opt>run_this_before_play_begins=</opt><arg>"/path/to/application and args"</arg><opt>;</opt></p>
+ <optdesc>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 <file>#!/bin/...</file> as appropriate.</optdesc>
+ </option>
+ <option>
+ <p><opt>run_this_after_play_ends=</opt><arg>"/path/to/application and args"</arg><opt>;</opt></p>
+ <optdesc>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 <file>#!/bin/...</file> as appropriate.</optdesc>
+ </option>
+ <option>
+ <p><opt>wait_for_completion=</opt><arg>"choice"</arg><opt>;</opt></p>
+ <optdesc>Set <arg>choice</arg> to "yes" to make shairport-sync wait until the programs specified in the <opt>run_this_before_play_begins</opt>
+ and <opt>run_this_after_play_ends</opt> have completed execution before continuing. The default is "no".</optdesc>
+ </option>
+ <option>
+ <p><opt>allow_session_interruption=</opt><arg>"choice"</arg><opt>;</opt></p>
+ <optdesc>If <opt>choice</opt> 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.</optdesc>
+ </option>
+ <option>
+ <p><opt>session_timeout=</opt><arg>seconds</arg><opt>;</opt></p>
+ <optdesc>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 <arg>seconds</arg> seconds before ending the session. Once the session has terminated, other devices can use it.
+ The default is 120 seconds.</optdesc>
+ </option>
+
+ <option><p><opt>"LATENCIES" SETTINGS</opt></p></option>
+ <p>The latencies settings are now deprecated. Do not use them for new installations. They will be removed from a future version of Shairport Sync.</p>
+ <p>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.</p>
+
+ <p>Shairport Sync now sets latencies automatically using information supplied by the source, typically either 88,200 or 99,577 frames.</p>
+
+ <p>The following relates to the old scheme of using fixed latencies, which ignores 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.</p>
+ <p>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, consider using the <opt>audio_backend_latency_offset</opt> setting in the <opt>alsa</opt> group
+ (or the appropriate other group if you're not outputing through the alsa backend).</p>
+
+
+ <option>
+ <p><opt>itunes=</opt><arg>latency</arg><opt>;</opt></p>
+ <optdesc>This is the <arg>latency</arg>, in frames, used for iTunes 10 or later. Default is 99,400.</optdesc>
+ </option>
+ <option>
+ <p><opt>airplay=</opt><arg>latency</arg><opt>;</opt></p>
+ <optdesc>This is the <arg>latency</arg>, in frames, used for AirPlay devices, including iOS devices and iTunes and Quicktime Player when they are playing video. Default is 88,200.</optdesc>
+ </option>
+ <option>
+ <p><opt>forkedDaapd=</opt><arg>latency</arg><opt>;</opt></p>
+ <optdesc>This is the <arg>latency</arg>, in frames, used for forkedDaapd sources. Default is 99,400.</optdesc>
+ </option>
+ <option>
+ <p><opt>default=</opt><arg>latency</arg><opt>;</opt></p>
+ <optdesc>This is the <arg>latency</arg>, in frames, used when the source is unrecognised. Default is 88,200.</optdesc>
+ </option>
+
</section>
<options>
- <p>Note: if you are setting up shairport-sync for the first time or are updating an existing installation,
+ <p>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 options described below
- simply replicate the configuration settings and are retained to provide backward compatability with older installations of shairport-sync.</p>
+ simply replicate the configuration settings and are retained to provide backward compatability with older installations of Shairport Sync.</p>
<p>Many of the options take sensible default values, so you can normally
ignore most of them. See the EXAMPLES section for typical usages.</p>
</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>
+ <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">
Set this <em>choice</em> 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".
- <p><b>"LATENCIES" SETTINGS</b></p>
- <p>There are four default latency settings, chosen automatically. 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.</p>
- <p>If you want to change latencies to compensate for a delay in the audio output device (which will have the same effect on all sources), instead of changing these individual latencies, consider using the <b>audio_backend_latency_offset</b> setting in the <b>alsa</b> group (or the appropriate other group if you're not outputing through the alsa backend).</p>
-
-
-
- <p><b>itunes=</b><em>latency</em><b>;</b></p>
- This is the <em>latency</em>, in frames, used for iTunes 10 or later. Default is 99,400.
-
-
- <p><b>airplay=</b><em>latency</em><b>;</b></p>
- This is the <em>latency</em>, in frames, used for AirPlay devices, including iOS devices and iTunes and Quicktime Player when they are playing video. Default is 88,200.
-
-
- <p><b>forkedDaapd=</b><em>latency</em><b>;</b></p>
- This is the <em>latency</em>, in frames, used for forkedDaapd sources. Default is 99,400.
-
-
- <p><b>default=</b><em>latency</em><b>;</b></p>
- This is the <em>latency</em>, in frames, used when the source is unrecognised. Default is 88,200.
-
-
- <p><b>"METADATA" SETTINGS</b></p>
- <p>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 provides the metadata to a pipe, by default <em>/tmp/shairport-sync-metadata</em>.
- To process metadata, shairport-sync must have been compiled with metadata support included.
- You can check that this is so by running <b>shairport-sync -V</b>; the identification string will contain the word <b>metadata</b>.</p>
- <p>The <b>metadata</b> group of settings allow you to enable metadata handling and to control certain aspects of it:</p>
-
-
-
- <p><b>enabled=</b><em>"choice"</em><b>;</b></p>
- Set the <em>choice</em> 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".
-
-
- <p><b>include_cover_art=</b><em>"choice"</em><b>;</b></p>
- Set the <em>choice</em> 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".
+ <p><b>volume_range_db=</b><em>dBvalue</em><b>;</b></p>
+ Set this <em>dBvalue</em> to use just a portion of the full range of attenuation offered by a mixer. 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. Or it might be because 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 35dB. The setting allows you to specify the maximum range from highest to lowest. Many domestic HiFi systems have a range of 60 to 80 dB. The range suggested for the Raspberry Pi's built-in audio DAC, which feeds the headphone jack, is 35. Using it in this case gives the volume control a much more useful range of settings. If you omit this setting, the full "native" range of the output device is used.
- <p><b>pipe_name=</b><em>"filepathname"</em><b>;</b></p>
- Specify the absolute path name of the pipe through which metadata should be sent The default is <em>/tmp/shairport-sync-metadata</em>".
-
-
- <p><b>"SESSIONCONTROL" SETTINGS</b></p>
- <p>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. </p>
- <p><b>run_this_before_play_begins=</b><em>"/path/to/application and args"</em><b>;</b></p>
- 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 <em>#!/bin/...</em> as appropriate.
-
-
- <p><b>run_this_after_play_ends=</b><em>"/path/to/application and args"</em><b>;</b></p>
- 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 <em>#!/bin/...</em> as appropriate.
-
-
- <p><b>wait_for_completion=</b><em>"choice"</em><b>;</b></p>
- Set <em>choice</em> to "yes" to make shairport-sync wait until the programs specified in the <b>run_this_before_play_begins</b>
- and <b>run_this_after_play_ends</b> have completed execution before continuing. The default is "no".
-
-
- <p><b>allow_session_interruption=</b><em>"choice"</em><b>;</b></p>
- If <b>choice</b> 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.
-
-
- <p><b>session_timeout=</b><em>seconds</em><b>;</b></p>
- 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 <em>seconds</em> seconds before ending the session. Once the session has terminated, other devices can use it.
- The default is 120 seconds.
-
-
<p><b>"ALSA" SETTINGS</b></p>
<p>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 <b>alsamixer</b> or <b>aplay</b> to discover what devices are available.)
If you do not specify a mixer control name, shairport-sync will adjust the volume in software.
<p><b>mixer_type=</b><em>"mixer_type"</em><b>;</b></p>
- This setting is deprecated and will be removed soon. If you wish to use a mixer control to control the volume, then set <em>mixer_type</em> to "hardware".
- The default is "software".
+ This setting is deprecated and ignored and will be removed soon.
<p><b>mixer_device=</b><em>"mixer_device"</em><b>;</b></p>
shairport-sync performs no stuffing or interpolation when writing to stdout. Default setting is 44,100 frames.
+
+ <p><b>"METADATA" SETTINGS</b></p>
+ <p>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 <em>/tmp/shairport-sync-metadata</em>.
+ To process metadata, shairport-sync must have been compiled with metadata support included.
+ You can check that this is so by running <b>shairport-sync -V</b>; the identification string will contain the word <b>metadata</b>.</p>
+ <p>Please note that different sources provide different levels of metadata. Some provide a lot; some provide almost none.</p>
+ <p>The <b>metadata</b> group of settings allow you to enable metadata handling and to control certain aspects of it:</p>
+
+
+
+ <p><b>enabled=</b><em>"choice"</em><b>;</b></p>
+ Set the <em>choice</em> 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".
+
+
+ <p><b>include_cover_art=</b><em>"choice"</em><b>;</b></p>
+ Set the <em>choice</em> 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".
+
+
+ <p><b>pipe_name=</b><em>"filepathname"</em><b>;</b></p>
+ Specify the absolute path name of the pipe through which metadata should be sent The default is <em>/tmp/shairport-sync-metadata</em>".
+
+
+ <p><b>"SESSIONCONTROL" SETTINGS</b></p>
+ <p>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. </p>
+
+
+
+ <p><b>run_this_before_play_begins=</b><em>"/path/to/application and args"</em><b>;</b></p>
+ 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 <em>#!/bin/...</em> as appropriate.
+
+
+ <p><b>run_this_after_play_ends=</b><em>"/path/to/application and args"</em><b>;</b></p>
+ 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 <em>#!/bin/...</em> as appropriate.
+
+
+ <p><b>wait_for_completion=</b><em>"choice"</em><b>;</b></p>
+ Set <em>choice</em> to "yes" to make shairport-sync wait until the programs specified in the <b>run_this_before_play_begins</b>
+ and <b>run_this_after_play_ends</b> have completed execution before continuing. The default is "no".
+
+
+ <p><b>allow_session_interruption=</b><em>"choice"</em><b>;</b></p>
+ If <b>choice</b> 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.
+
+
+ <p><b>session_timeout=</b><em>seconds</em><b>;</b></p>
+ 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 <em>seconds</em> seconds before ending the session. Once the session has terminated, other devices can use it.
+ The default is 120 seconds.
+
+
+ <p><b>"LATENCIES" SETTINGS</b></p>
+ <p>The latencies settings are now deprecated. Do not use them for new installations. They will be removed from a future version of Shairport Sync.</p>
+ <p>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.</p>
+
+ <p>Shairport Sync now sets latencies automatically using information supplied by the source, typically either 88,200 or 99,577 frames.</p>
+
+ <p>The following relates to the old scheme of using fixed latencies, which ignores 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.</p>
+ <p>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, consider using the <b>audio_backend_latency_offset</b> setting in the <b>alsa</b> group
+ (or the appropriate other group if you're not outputing through the alsa backend).</p>
+
+
+
+ <p><b>itunes=</b><em>latency</em><b>;</b></p>
+ This is the <em>latency</em>, in frames, used for iTunes 10 or later. Default is 99,400.
+
+
+ <p><b>airplay=</b><em>latency</em><b>;</b></p>
+ This is the <em>latency</em>, in frames, used for AirPlay devices, including iOS devices and iTunes and Quicktime Player when they are playing video. Default is 88,200.
+
+
+ <p><b>forkedDaapd=</b><em>latency</em><b>;</b></p>
+ This is the <em>latency</em>, in frames, used for forkedDaapd sources. Default is 99,400.
+
+
+ <p><b>default=</b><em>latency</em><b>;</b></p>
+ This is the <em>latency</em>, in frames, used when the source is unrecognised. Default is 88,200.
+
+
<h2>Options</h2>
- <p>Note: if you are setting up shairport-sync for the first time or are updating an existing installation,
+ <p>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 options described below
- simply replicate the configuration settings and are retained to provide backward compatability with older installations of shairport-sync.</p>
+ simply replicate the configuration settings and are retained to provide backward compatability with older installations of Shairport Sync.</p>
<p>Many of the options take sensible default values, so you can normally
ignore most of them. See the EXAMPLES section for typical usages.</p>
<h2>Credits</h2>
- <p>Mike Brady developed shairport-sync from the original shairport by James Laird.</p>
- <p>
shairport-sync can be found at <a href = "https://github.com/mikebrady/shairport-sync.">https://github.com/mikebrady/shairport-sync.</a></p>
- <p>
shairport can be found at <a href = "https://github.com/abrasive/shairport.">https://github.com/abrasive/shairport.</a></p>
+ <p>Mike Brady developed Shairport Sync from the original Shairport by James Laird.</p>
+ <p>
Shairport Sync can be found at <a href = "https://github.com/mikebrady/shairport-sync.">https://github.com/mikebrady/shairport-sync.</a></p>
+ <p>
Shairport can be found at <a href = "https://github.com/abrasive/shairport.">https://github.com/abrasive/shairport.</a></p>
general =
{
// name = "Shairport Sync Player"; // This is the name the service will advertise to iTunes. The default is "Shairport Sync on <hostname>"
-// password = "secret"; // comment out this line if you want to have no password
+// password = "secret"; // leave this commented out if you don't want to require a password
// interpolation = "basic"; // aka "stuffing". Default is "basic", alternative is "soxr". Use "soxr" only if you have a reasonably fast processor.
// output_backend = "alsa"; // Run "shairport-sync -h" to get a list of all output_backends, e.g. "alsa", "pipe", "stdout". The default is the first one.
// mdns_backend = "avahi"; // Run "shairport-sync -h" to get a list of all mdns_backends. The default is the first one.
// resync_threshold = 2205; // a synchronisation error greater than this will cause resynchronisation; 0 disables it
// log_verbosity = 0; // "0" means no debug verbosity, "3" is most verbose.
// ignore_volume_control = "no"; // set this to "yes" if you want the volume to be at 100% no matter what the source's volume control is set to.
-// volume_range_db = 60 ; // use this to set the range, in dB, you want between the maximum volume and the minimum volume. Range is 30 to 150 dB. Omit to use mixer's native range.
+// volume_range_db = 60 ; // use this to set the range, in dB, you want between the maximum volume and the minimum volume. Range is 30 to 150 dB. Leave it commented out to use mixer's native range.
};
// How to deal with metadata, including artwork
// session_timeout = 120; // wait for this number of seconds after a source disappears before terminating the session and becoming available again.
};
-//
// Back End Settings
-//
// These are parameters for the "alsa" audio back end, the only back end that supports synchronised audio.
alsa =
};
// The following static latency settings are deprecated -- do not use them for new installations. Shairport Sync now sets latencies automatically.
-// To compensate for a delay in the output device using the alsa/stdio/pipe "audio_backend_latency_offset" setting.
+// To compensate for a delay in the output device please use the alsa/stdio/pipe "audio_backend_latency_offset" setting.
// Static latencies for different sources. These have been estimated from listening tests.
latencies =
projects / thirdparty / shairport-sync.git / commitdiff
