Shairport Sync
=============
- Shairport Sync is an AirPlay audio player — it plays audio streamed from iTunes, iOS devices and other AirPlay sources such as Quicktime Player and ForkedDaapd, among others.
-**Welcome to Version 3 of Shairport Sync. This is a big update from version 2.X and is still a work in progress. Please see the Release Notes for more information.**
++**Welcome to Version 3 of Shairport Sync. This is a big update from version 2. Please see the Release Notes for more information.**
+
+ Shairport Sync is an AirPlay audio player – it plays audio streamed from iTunes, iOS devices and other AirPlay sources such as Quicktime Player and ForkedDaapd, among others.
Audio played by a Shairport Sync-powered device stays synchronised with the source and hence with similar devices playing the same source. In this way, synchronised multi-room audio is possible without difficulty. (Hence the name Shairport Sync, BTW.)
Shairport Sync does not support AirPlay video or photo streaming.
-This is the unstable "development" branch. Changes and updates are incorporated into this branch quickly. To access the stable version, where changes are made after due time, please switch to the "master" branch.
+This is the stable "master" branch. Changes and updates are incorporated into this branch relatively slowly. To access the development version, where all the latest changes are made first, please switch to the "development" branch.
- **Please note that, between 2.8.4 and 2.8.5, there is a change in the standard ./configure arguments which you should not ignore!**
-
++**Please note that, between 2.8.4 and 2.8.5, there is a change in the standard ./configure arguments which you should not ignore!** If you are updating Shairport Sync from a version that is 2.8.4 or older, please read the [UPDATING](https://github.com/mikebrady/shairport-sync/blob/master/UPDATING.md) page very carefully.
More Information
----------
--------------
* Better Volume Control — Shairport Sync offers finer control at very top and very bottom of the volume range. See http://tangentsoft.net/audio/atten.html for a good discussion of audio "attenuators", upon which volume control in Shairport Sync is modelled. See also the diagram of the volume transfer function in the documents folder. In addition, Shairport Sync can offer an extended volume control range on devices with a restricted range.
* Hardware Mute — Shairport Sync will mute properly if the hardware supports it.
+ * Support for the Apple ALAC decoder.
+ * Bit depths of 8, 16, 24 and 32 bits, rather than the standard 16 bits.
* Fast Response — With hardware volume control, response is instantaneous; otherwise the response time is 0.15 seconds.
* Non-Interruptible — Shairport Sync sends back a "busy" signal if it's already playing audio from another source, so other sources can't disrupt an existing Shairport Sync session. (If a source disappears without warning, the session automatically terminates after two minutes and the device becomes available again.)
-* Metadata — Shairport Sync can deliver metadata supplied by the source, such as Album Name, Artist Name, Cover Art, etc. through a pipe or UDP socket to a recipient application program — see https://github.com/mikebrady/shairport-sync-metadata-reader for a sample recipient. Sources that supply metadata include iTunes and the Music app in iOS.
+* Metadata — Shairport Sync can deliver metadata supplied by the source, such as Album Name, Artist Name, Cover Art, etc. through a pipe to a recipient application program — see https://github.com/mikebrady/shairport-sync-metadata-reader for a sample recipient. Sources that supply metadata include iTunes and the Music app in iOS.
* Raw Audio — Shairport Sync can deliver raw PCM audio to standard output or to a pipe. This output is delivered synchronously with the source after the appropriate latency and is not interpolated or "stuffed" on its way through Shairport Sync.
* Autotools and Libtool Support — the Shairport Sync build process uses GNU `autotools` and `libtool` to examine and configure the build environment — important for portability and for cross compilation. Previous versions of Shairport looked at the current system to determine which packages were available, instead of looking at the target system for what packages were available.
Note: Historically, Shairport Sync has taken its settings from command line arguments. While this is still the case, it does not always work well across distributions. Accordingly, from version 2.4 onwards, Shairport Sync reads settings from the file `/etc/shairport-sync.conf`. Access to new features will only be provided via the settings file.
-Building And Installing the Development Version
+Building And Installing
---------------------
+
+Shairport Sync may already be available as a package in your Linux distribution (search for `shairport-sync` – the package named `shairport` is a different program). Packages are available on recent versions of Debian, Ubuntu, Arch, OpenWrt and possibly more. If you wish to build and install the latest version of Shairport Sync on OpenWrt, Arch or Fedora platforms, please follow the appropriate instructions below. Limited support is also available for Mac OS X. Otherwise follow the General Build Instructions. Then, when the program has been installed, refer to the section on Configuring Shairport Sync that follows.
+
+**Note**
+
+The following procedures will install the `shairport-sync` application into your system. Before continuing, you should check to see if `shairport-sync` is already installed – you can use the command `$ which shairport-sync` to find where it is located, if installed. If it is installed you should delete it – you may need superuser privileges. After deleting, check again in case further copies are installed elsewhere.
+(If the existing installation of `shairport-sync` is where the new copy will be installed into, it will be overwritten; sometimes, however, the installation is to another location, so it is safer, initially, to delete previous versions manually.)
+
+**Ubuntu:**
+Personal Package Archives for Shairport Sync master and development branches are available at https://launchpad.net/~dantheperson. A `shairport-sync` installer package is available in Ubuntu 16.04.
+
+**Debian:**
+`shairport-sync` is in the Debian archive and is scheduled for release with Debian Stretch (9): https://tracker.debian.org/shairport-sync. A backport for Debian Jessie (8) may be provided given enough demand.
+
+**OpenWrt:**
+There is a Shairport Sync package in OpenWrt `trunk`. Also, there's an OpenWrt package at https://github.com/mikebrady/shairport-sync-for-openwrt, including one that builds back to `Barrier Breaker`.
+
+**Arch Linux:**
+Shairport Sync is available for `x86_64` and `i686` platforms in the Arch Linux Community Repository -- search for `shairport-sync`. See also https://www.archlinux.org/packages/.
+
+An Arch Linux installation package, suitable for compilation on any platform, is available at [EliaCereda/shairport-sync-PKGBUILD](https://github.com/EliaCereda/shairport-sync-PKGBUILD).
+
+**Mac OS X:**
+A [HomeBrew](http://brew.sh) package exists for Shairport Sync. With HomeBrew installed, Shairport Sync can be installed using the command `$brew install shairport-sync`. Note that the installation uses the `libao` library and so synchronisation is not available — playback glitches will occur occasionally, when the `ao` system's buffers overflow or underflow.
+
+**Fedora:**
+Please see the guide at [FEDORA.md](https://github.com/mikebrady/shairport-sync/blob/master/FEDORA.md).
+
+**Cygwin:**
+Please see the guide at [CYGWIN.md](https://github.com/mikebrady/shairport-sync/blob/master/CYGWIN.md).
+
+Sincere thanks to all package contributors!
+
+**General Build Instructions**
+ The following procedures will install the shairport-sync application into your system. Before continuing, you should check to see if shairport-sync is already installed – you can use the command `$ which shairport-sync` to find where it is located, if installed. If it is installed you should delete it – you may need superuser privileges. After deleting, check again in case further copies are installed elsewhere.
To build Shairport Sync from sources on Debian, Ubuntu, Raspbian, etc. follow these instructions.
Debian, Ubuntu and Raspbian users can get the basics with:
-- `apt-get install build-essential git xmltoman` – these may already be installed.
+- `apt-get install build-essential git` – these may already be installed.
- `apt-get install autoconf automake libtool libdaemon-dev libasound2-dev libpopt-dev libconfig-dev`
- `apt-get install avahi-daemon libavahi-client-dev` if you want to use Avahi (recommended).
- - `apt-get install libssl-dev` if you want to use OpenSSL and libcrypto, or use PolarSSL otherwise.
- - `apt-get install libpolarssl-dev` if you want to use PolarSSL, or use OpenSSL/libcrypto otherwise.
- - `apt-get install libsoxr-dev` if you want support for libsoxr-based resampling. This library is in many recent distributions, including Jessie and Raspioan Jessie; if not, instructions for how to build it from source for Raspian/Debian Wheezy are available at [LIBSOXR.md](https://github.com/mikebrady/shairport-sync/blob/master/LIBSOXR.md).
+ - `apt-get install libssl-dev` if you want to use OpenSSL and libcrypto, or use mbed TLS otherwise.
+ - `apt-get install libmbedtls-dev` if you want to use mbed TLS, or use OpenSSL/libcrypto otherwise. (You can still use PolarSSL with `apt-get install libpolarssl-dev` if you want to use PolarSSL, but it is deprecated as it's not longer being supported. It is suggested you use mbed TLS instead.)
+ - `apt-get install libsoxr-dev` if you want support for libsoxr-based resampling. This library is in many recent distributions, including Jessie and Raspbian Jessie; if not, instructions for how to build it from source for Rasbpian/Debian Wheezy are available at [LIBSOXR.md](https://github.com/mikebrady/shairport-sync/blob/development/LIBSOXR.md).
+
+ If you wish to include the Apple ALAC decoder, you need install it first – please refer to the [ALAC](https://github.com/mikebrady/alac) repository for more information.
**Download Shairport Sync:**
To enable Shairport Sync to start automatically at system startup, enter:
-`$sudo systemctl enable shairport-sync`
+`$ sudo systemctl enable shairport-sync`
**Install into a System V system**
- If you are installing onto a System V system:
+ If you are installing onto a System V system, enter:
```
-$sudo make install
+$ sudo make install
```
to install `shairport-sync` along with a `man` page, a default configuration file and a System V startup script to launch it automatically at system startup.
- =======
+ Version 3.0
+ ====
+
+ Big Update
+ ----
+ Version 3 brings in support for 24-bit and 32-bit (and 8 bit!) DACs and for DACs running at multiples of 44,100 samples per second.
+
+ The most obvious audible change is if you are using software volume control and can take advantage of 32- or 24-bit DACs. Dithering can now occur on a 32-bit or 24-bit sample rather than on a 16-bit sample, making the noise floor very much lower. This is the case, for example, with a Pimoroni PHAT DAC.
+
+ Here is the list of new features:
+
+ **New Features**
+ * 8-bit, 16-bit, 24-bit, 24-bit three-byte (S24_3LE and S24_3BE) and 32-bit output to ALSA devices.
+ * 44,100, 88,200, 176,400 and 352,800 sample per second output. This is done using simple upsampling. It's only worth doing if 44,100 samples per second output is not available.
+ * Internal processing including software volume control and interpolation is done after sample size and rate conversion.
+ * Apple ALAC decoder support. This needs the `libalac` library, available at [ALAC](https://github.com/mikebrady/alac), to be installed. Add the flag `--with-apple-alac` to the `./configure` arguments. Then you can choose the Apple ALAC decoder in the configuration file.
+ * Support for `mbed TLS` has been added and the use of `PolarSSL` is deprecated, as `mbed TLS` is a development of `PolarSSL` and `PolarSSL` itself is not being developed further.
+ * Choose Network Interface. Add a new setting, for advanced users only, in the `general` section. Use the `interface` setting to allow you to specify the interface on which to provide the AirPlay service. Omit the setting to get the default, which is to choose the interfaces automatically.
+ * Set Max Volume. Add a new setting, for advanced users only, in the `general` section. Use the `volume_max_db` setting to allow you to specify the maximum level to set on the hardware mixer (if chosen) or the built-in software mixer otherwise. The software mixer's range is 0.0 dB to -96.1 dB. The setting must be a number with a decimal point, e.g. 21.3.
+ * An experimental new back end for `libsoundio`, a C library for cross-platform real-time audio input and output. Many thanks to [Serg Podtynnyi](https://github.com/shtirlic). Please see https://github.com/mikebrady/shairport-sync/pull/433 for more details.
+
+
+ Pesky Changes You Cannot Ignore
+ ----
+ * Processor load is up by about 11%.
+ * Settings have changed -- basically, any timings that were denominated in frames are now in seconds. Please refer to the shairport-sync.conf.sample file for details.
+ * Sox-based interpolation at higher sample rates may overload your CPU -- you might have to choose between higher sample rates and sox-based interpolation.
+
+
+ Version 3.0rc0 – Release Candidate 0
+ ----
+ Note: all Version 3 changes are summarized above.
+
+ **New Feature**
+ * An experimental new back end for `libsoundio`, a C library for cross-platform real-time audio input and output. Many thanks to [Serg Podtynnyi](https://github.com/shtirlic). Please see https://github.com/mikebrady/shairport-sync/pull/433 for more details.
+
+ **Other changes**
+ * Updates to `man` page and [README](https://github.com/mikebrady/shairport-sync/blob/development/README.md). Reports of typos or suggestions for improvement are welcome!
+
+ Version 3.0d24 – Development Version
+ ----
+ Note: all Version 3 changes are summarized above.
+
+ **New Feature**
+ * Set Max Volume. Add a new setting, for advanced users only, in the `general` section. Use the `volume_max_db` setting to allow you to specify the maximum level to set on the hardware mixer (if chosen) or the built-in software mixer otherwise. The software mixer's range is 0.0 dB to -96.1 dB. The setting must be a number with a decimal point, e.g. 21.3.
+
+ Version 3.0d23 – Development Version
+ ----
+ Note: all Version 3 changes are summarized above.
+
+ **New Feature**
+ * Choose Interface. Add a new setting, for advanced users only, in the `general` section. Use the `interface` setting to allow you to specify the interface on which to provide the AirPlay service. Omit the setting to get the default, which is to choose the interfaces automatically.
+
+ Version 3.0d22 – Development Version
+ ----
+ Note: all Version 3 changes are summarized above.
+
+ **Bug Fix**
+ * Fixed a bug which prevented successful building in the OpenWrt build system. The problem was caused by an `#include apple_alac.h` in `player.c` which was actioned even if the apple alac decoder was not selected. This caused the OpenWrt build system to expect the standard C++ library – required by the apple alac code – to be referenced, but it was not specified on the build manifest and therefore stopped the build. The solution was to make the `#include` conditional on selecting the apple alac decoder.
+
+ Version 3.0d21 – Development Version
+ ----
+ Note: all Version 3 changes are summarized above.
+
+ **Bug Fix**
+ * Fixed a bug which turned off resync by default. Duh.
+
+ Version 3.0d20 – Development Version
+ ----
+ Note: all Version 3 changes are summarized above.
+
+ **Bug Fix**
+ * Fix a small and generally silent error in configure.ac so that it only looks for the systemd direcotry if systemd has been chosen. It caused a warning when cross-compiling.
+
+ Version 3.0d19 – Development Version
+ ----
+ Note: all Version 3 changes are summarized above.
+
+ **New Feature**
+ * Reduces processor load back to V2.X levels by using a precalculated array of pseudorandom numbers to do dithering. Doesn't seem to make any audible difference.
+
+ Version 3.0d18 – Development Version
+ ----
+ Note: all Version 3 changes are summarized above.
+
+ **New Features**
+ * 8-bit, 16-bit, 24-bit, 24-bit three-byte (S24_3LE and S24_3BE) and 32-bit output to ALSA devices. (Other back ends are not updated yet.)
+ * 44,100, 88,200, 176,400 and 352,800 sample per second output. This is done using simple upsampling.
+ * Internal processing including software volume control and interpolation is done after sample size and rate conversion.
+ * Apple ALAC decoder support. This needs the `libalac` library, available at [ALAC](https://github.com/mikebrady/alac). Add the flag `--with-apple-alac` to the `./configure` arguments. Then you can choose the Apple ALAC decoder in the configuration file.
+ * Support for `mbed TLS` has been added and the use of `PolarSSL` is deprecated, as `mbed TLS` is a development of `PolarSSL` and `PolarSSL` itself is not being developed further.
+ * Settings that were denominated in frames are now deprecated but still honoured. Deprecation warnings are issued.
+
+ Pesky Changes You Cannot Ignore
+ ====
+ * Settings have changed -- basically, any timings that were denominated in frames are now in seconds. Please refer to the shairport-sync.conf.sample file for details.
+ * Sox-based interpolation at higher sample rates may overload your CPU -- yopu might have to choose between higher sample rates and sox-based interpolation.
+
+ **Bugs**
+ * Documentation is not updated.
+
+Version 2.8.6 – Stable Candidate
+----
+
+**Enhancements**
+* This release contains a small change – it identifies itself as a ShairportSync device rather than an AirPort device. This should make it possible for Tuneblade, and possibly other players, to recognise it correctly.
+
+Version 2.8.5 – Stable Version
+----
+This release includes bug fixes and minor enhancements and is recommended for all users.
+
+Note: if you're upgrading, there is a new `./configure` option:
+====
+The build process now uses the directory path `sysconfdir` to determine where to place the configuration file `shairport-sync.conf`.
+The default value for `sysconfdir` is `/usr/local/etc` which is used in the BSD family, whereas `/etc` is normally used in Linux.
+To retain the present behaviour of Shairport Sync, *you must add an extra parameter to the `./configure... ` command.* The parameter you must add is `--sysconfdir=/etc`. (This has been added to the sample configuration command line in README.md.)
+
+The enhancements and bug fixes in 2.8.5 were made in versions 2.8.4.1 to 2.8.4.8 inclusive. Please read below for the full list.
+
+For advice on updating an installation you built yourself,
+please visit the [UPDATING](https://github.com/mikebrady/shairport-sync/blob/master/UPDATING.md) page.
+
Version 2.8.4.8 – Development Version
----
**Enhancements**
\fBudp_port_range=\f1\fIrange\f1\fB;\f1
Use this in conjunction with the prevous setting to specify the \fIrange\f1 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.
.TP
- \fBdrift=\f1\fIframes\f1\fB;\f1
- Allow playback to drift up to \fIframes\f1 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 \fBstatistics\f1 setting to monitor correction levels. Corrections should not greatly exceed net corrections.
+ \fBdrift_tolerance_in_seconds=\f1\fIseconds\f1\fB;\f1
+ Allow playback to drift up to \fIseconds\f1 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 \fBstatistics\f1 setting to monitor correction levels. Corrections should not greatly exceed net corrections. This setting replaces the deprecated \fBdrift\f1 setting.
.TP
- \fBresync_threshold=\f1\fIthreshold\f1\fB;\f1
- Resynchronise if timings differ by more than \fIthreshold\f1 frames. If the output timing differs from the source timing by more than the threshold, output will be muted and a full resynchronisation will occur. The default threshold is 2,205 frames, i.e. 50 milliseconds. Specify \fI0\f1 to disable resynchronisation.
+ \fBresync_threshold_in_seconds=\f1\fIthreshold\f1\fB;\f1
+ Resynchronise if timings differ by more than \fIthreshold\f1 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 \fBresync_threshold\f1 setting.
.TP
\fBlog_verbosity=\f1\fI0\f1\fB;\f1
-Use this to specify how much debugging information should be output or logged. "0" means no debug information, "3" means most debug information. The default is "0".
+Use this to specify how much debugging information should be output or logged. The value \fI0\f1 means no debug information, \fI3\f1 means most debug information. The default is \fI0\f1.
.TP
\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".
+Set this \fIchoice\f1 to \fI"yes"\f1 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 \fI"no"\f1.
.TP
+ \fBvolume_max_db=\f1\fIdBvalue\f1\fB;\f1
+ 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.
+ .TP
\fBvolume_range_db=\f1\fIdBvalue\f1\fB;\f1
Use this \fIdBvalue\f1 to reduce or increase the attenuation range, in decibels, between the minimum and maximum volume.
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 full "native" range of the mixer is used.
+If you omit this setting, the native range of the mixer is used.
.TP
\fBregtype=\f1\fI"regTypeString"\f1\fB;\f1
-Use this advanced setting to set the service type and transport to be advertised by Zeroconf/Bonjour. Default is "_raop._tcp".
+Use this advanced setting to set the service type and transport to be advertised by Zeroconf/Bonjour. Default is \fI"_raop._tcp"\f1.
.TP
\fBplayback_mode=\f1\fI"mode"\f1\fB;\f1
- The \fImode\f1 can be \fI"stereo"\f1 or \fI"mono"\f1. Default is \fI"stereo"\f1.
+ The \fImode\f1 can be "stereo", "mono", "reverse stereo", "both left" or "both right". Default is "stereo".
+ .TP
+ \fBinterface=\f1\fI"name"\f1\fB;\f1
+ Use this advanced setting if you want to confine Shairport Sync to the named interface. Leave it commented out to get the default bahaviour.
+ .TP
+ \fBalac_decoder=\f1\fI"decodername"\f1\fB;\f1
+ 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.
.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:
\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_latency_offset=\f1\fIoffset\f1\fB;\f1
- Set this \fIoffset\f1, in frames, to compensate for a fixed delay in the audio back end. For example, if the output device delays by 100 ms, set this to \fI-4410\f1. Default is \fI0\f1.
+ \fBaudio_backend_latency_offset_in_seconds=\f1\fIoffset\f1\fB;\f1
+ Set this \fIoffset\f1, 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.
.TP
- \fBaudio_backend_buffer_desired_length=\f1\fIlength\f1\fB;\f1
- Use this to set the desired number frames to be in the output device's hardware output buffer. The default is \fI6,615\f1 frames, or 0.15 seconds. If set too small, buffer underflow may occur on low-powered machines. If too large, the response times when using software volume control (i.e. when not using a mixer control to control volume) become annoying, or it may exceed the hardware buffer size. It may need to be larger on low-powered machines that are also performing other tasks, such as processing metadata.
+ \fBaudio_backend_buffer_desired_length_in_seconds=\f1\fIlength\f1\fB;\f1
+ Use this to set the desired length, in seconds, of the queue of audio frames in the output device's hardware output buffer. The default is 0.15 seconds. If set too small, buffer underflow may occur on low-powered machines. If too large, the response times when using software volume control (i.e. when not using a mixer control to control volume) become annoying, or it may exceed the hardware buffer size. It may need to be larger on low-powered machines that are also performing other tasks, such as processing metadata.
+ .TP
+ \fBoutput_rate=\f1\fIframe rate\f1\fB;\f1
+ 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.
+ .TP
+ \fBoutput_format=\f1\fI"format"\f1\fB;\f1
+ 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.
.TP
\fBdisable_synchronization=\f1\fI"no"\f1\fB;\f1
-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.
+This is an advanced setting and is for debugging only. Set to \fI"yes"\f1 to disable synchronization. Default is \fI"no"\f1. If you use it to disable synchronisation, then sooner or later you'll experience audio glitches due to audio buffer overflow or underflow.
.TP
\fBperiod_size=\f1\fInumber\f1\fB;\f1
Use this optional advanced setting to set the alsa period size near to this value.
</option>
<option>
<p><opt>udp_port_range=</opt><arg>range</arg><opt>;</opt></p>
- <optdesc>Use this in conjunction with the prevous setting to specify the <arg>range</arg> 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.</optdesc>
+ <optdesc>Use this in conjunction with the prevous setting to specify the <arg>range</arg> 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.</optdesc>
</option>
<option>
- <p><opt>drift=</opt><arg>frames</arg><opt>;</opt></p>
- <optdesc>Allow playback to drift 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.
+ <p><opt>drift_tolerance_in_seconds=</opt><arg>seconds</arg><opt>;</opt></p>
+ <optdesc>Allow playback to drift up to <arg>seconds</arg> 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 <opt>statistics</opt> setting to
- monitor correction levels. Corrections should not greatly exceed net corrections.
+ monitor correction levels. Corrections should not greatly exceed net corrections. This setting replaces the deprecated <opt>drift</opt> setting.
</optdesc>
</option>
<option>
</option>
<option>
<p><opt>ignore_volume_control=</opt><arg>"choice"</arg><opt>;</opt></p>
- <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>
+ <optdesc>Set this <arg>choice</arg> to <arg>"yes"</arg> 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 <arg>"no"</arg>.</optdesc>
</option>
+ <option>
+ <p><opt>volume_max_db=</opt><arg>dBvalue</arg><opt>;</opt></p>
+ <optdesc><p>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.</p>
+ </optdesc>
+ </option>
+
<option>
<p><opt>volume_range_db=</opt><arg>dBvalue</arg><opt>;</opt></p>
<optdesc><p>Use this <arg>dBvalue</arg> to reduce or increase the attenuation range, in decibels, between the minimum and maximum volume.</p>
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.</p>
- <p>If you omit this setting, the full "native" range of the mixer is used.</p></optdesc>
+ <p>If you omit this setting, the native range of the mixer is used.</p></optdesc>
</option>
-
<option>
<p><opt>regtype=</opt><arg>"regTypeString"</arg><opt>;</opt></p>
- <optdesc>Use this advanced setting to set the service type and transport to be advertised by Zeroconf/Bonjour. Default is "_raop._tcp".</optdesc>
+ <optdesc>Use this advanced setting to set the service type and transport to be advertised by Zeroconf/Bonjour. Default is <arg>"_raop._tcp"</arg>.</optdesc>
</option>
<option>
It may need to be larger on low-powered machines that are also performing other tasks, such as processing metadata.</optdesc>
</option>
+ <option>
+ <p><opt>output_rate=</opt><arg>frame rate</arg><opt>;</opt></p>
+ <optdesc>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.
+ </optdesc>
+ </option>
+
+ <option>
+ <p><opt>output_format=</opt><arg>"format"</arg><opt>;</opt></p>
+ <optdesc>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.
+ </optdesc>
+ </option>
+
<option>
<p><opt>disable_synchronization=</opt><arg>"no"</arg><opt>;</opt></p>
- <optdesc>This is an advanced setting and is for debugging only. Set to "yes" to disable synchronization. Default is "no".
+ <optdesc>This is an advanced setting and is for debugging only. Set to <arg>"yes"</arg> to disable synchronization. Default is <arg>"no"</arg>.
If you use it to disable synchronisation, then sooner or later you'll experience audio glitches due to
audio buffer overflow or underflow.
</optdesc>
<p><b>udp_port_range=</b><em>range</em><b>;</b></p>
- Use this in conjunction with the prevous setting to specify the <em>range</em> 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.
+ Use this in conjunction with the prevous setting to specify the <em>range</em> 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.
- <p><b>drift=</b><em>frames</em><b>;</b></p>
- Allow playback to drift up to <em>frames</em> 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.
+ <p><b>drift_tolerance_in_seconds=</b><em>seconds</em><b>;</b></p>
+ Allow playback to drift up to <em>seconds</em> 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 <b>statistics</b> setting to
- monitor correction levels. Corrections should not greatly exceed net corrections.
+ monitor correction levels. Corrections should not greatly exceed net corrections. This setting replaces the deprecated <b>drift</b> setting.
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.</p>
- <p>If you omit this setting, the full "native" range of the mixer is used.</p>
+ <p>If you omit this setting, the native range of the mixer is used.</p>
-
<p><b>regtype=</b><em>"regTypeString"</em><b>;</b></p>
- Use this advanced setting to set the service type and transport to be advertised by Zeroconf/Bonjour. Default is "_raop._tcp".
+ Use this advanced setting to set the service type and transport to be advertised by Zeroconf/Bonjour. Default is <em>"_raop._tcp"</em>.
+ <p><b>output_rate=</b><em>frame rate</em><b>;</b></p>
+ 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.
+
+
+
+
+ <p><b>output_format=</b><em>"format"</em><b>;</b></p>
+ 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.
+
+
+
+
<p><b>disable_synchronization=</b><em>"no"</em><b>;</b></p>
- This is an advanced setting and is for debugging only. Set to "yes" to disable synchronization. Default is "no".
+ This is an advanced setting and is for debugging only. Set to <em>"yes"</em> to disable synchronization. Default is <em>"no"</em>.
If you use it to disable synchronisation, then sooner or later you'll experience audio glitches due to
audio buffer overflow or underflow.
// include_cover_art = "no"; // set to "yes" to get Shairport Sync to solicit cover art from the source and pass it via the pipe. You must also set "enabled" to "yes".
// pipe_name = "/tmp/shairport-sync-metadata";
// pipe_timeout = 5000; // wait for this number of milliseconds for a blocked pipe to unblock before giving up
--// socket_address = "226.0.0.1"; // if set to a host name or IP address, UDP packets containing metadata will be sent to this address. May be a multicast address. "socket-port" must be non-zero and "enabled" must be set to yes"
--// socket_port = 5555; // if socket_address is set, the port to send UDP packets to
--// socket_msglength = 65000; // the maximum packet size for any UDP metadata. This will be clipped to be between 500 or 65000. The default is 500.
++// socket_address = "226.0.0.1"; // if set to a host name or IP address, UDP packets containing metadata will be sent to this address. May be a multicast address. "socket-port" must be non-zero and "enabled" must be set to yes"
++// socket_port = 5555; // if socket_address is set, the port to send UDP packets to
++// socket_msglength = 65000; // the maximum packet size for any UDP metadata. This will be clipped to be between 500 or 65000. The default is 500.
};
// Advanced parameters for controlling how a Shairport Sync runs
projects / thirdparty / shairport-sync.git / commitdiff
