From 66929ce3448da8e156eea8d3237ad999c8627cd5 Mon Sep 17 00:00:00 2001 From: Mike Brady Date: Sat, 29 Jul 2017 17:18:11 +0200 Subject: [PATCH] Update manual and make the sndio format settings conform to the alsa settings --- audio_sndio.c | 14 +- man/shairport-sync.7 | 171 +++++++++++---------- man/shairport-sync.7.xml | 291 +++++++++++++++++------------------- man/shairport-sync.html | 291 +++++++++++++++++------------------- scripts/shairport-sync.conf | 10 +- 5 files changed, 382 insertions(+), 395 deletions(-) diff --git a/audio_sndio.c b/audio_sndio.c index d8b80ad1..92f73bed 100644 --- a/audio_sndio.c +++ b/audio_sndio.c @@ -72,13 +72,13 @@ struct sndio_formats { }; static struct sndio_formats formats[] = { - {"s8", SPS_FORMAT_S8, 8, 1, 1, SIO_LE_NATIVE}, - {"u8", SPS_FORMAT_U8, 8, 1, 0, SIO_LE_NATIVE}, - {"s16", SPS_FORMAT_S16, 16, 2, 1, SIO_LE_NATIVE}, - {"s24", SPS_FORMAT_S24, 24, 4, 1, SIO_LE_NATIVE}, - {"s24le3", SPS_FORMAT_S24_3LE, 24, 3, 1, 1}, - {"s24be3", SPS_FORMAT_S24_3BE, 24, 3, 1, 0}, - {"s32", SPS_FORMAT_S32, 24, 4, 1, SIO_LE_NATIVE}}; + {"S8", SPS_FORMAT_S8, 8, 1, 1, SIO_LE_NATIVE}, + {"U8", SPS_FORMAT_U8, 8, 1, 0, SIO_LE_NATIVE}, + {"S16", SPS_FORMAT_S16, 16, 2, 1, SIO_LE_NATIVE}, + {"S24", SPS_FORMAT_S24, 24, 4, 1, SIO_LE_NATIVE}, + {"S24_3LE", SPS_FORMAT_S24_3LE, 24, 3, 1, 1}, + {"S24_3BE", SPS_FORMAT_S24_3BE, 24, 3, 1, 0}, + {"S32", SPS_FORMAT_S32, 24, 4, 1, SIO_LE_NATIVE}}; static void help() { printf(" -d output-device set the output device [default*|...]\n"); diff --git a/man/shairport-sync.7 b/man/shairport-sync.7 index 1b460331..189e81b3 100644 --- a/man/shairport-sync.7 +++ b/man/shairport-sync.7 @@ -2,7 +2,7 @@ .SH NAME shairport-sync \- Synchronised Audio Player for iTunes / AirPlay .SH SYNOPSIS -\fBshairport-sync [-dvw]\fB [-a \fB\fIname\fB]\fB [-A \fB\fIlatency\fB]\fB [-B \fB\fIcommand\fB]\fB [-c \fB\fIconfigurationfile\fB]\fB [-E \fB\fIcommand\fB]\fB [--get-cover-art]\fB [--logOutputLevel=]\fB [-L \fB\fIlatency\fB]\fB [-m \fB\fIbackend\fB]\fB [--meta-dir=\fB\fIdirectory\fB]\fB [-o \fB\fIbackend\fB]\fB [--password=\fB\fIsecret\fB]\fB [-r \fB\fIthreshold\fB]\fB [--statistics]\fB [-S \fB\fImode\fB]\fB [-t \fB\fItimeout\fB]\fB [--tolerance=\fB\fIframes\fB]\fB [-- \fB\fIaudio_backend_options\fB]\fB +\fBshairport-sync [-djvw]\fB [-a \fB\fIname\fB]\fB [-A \fB\fIlatency\fB]\fB [-B \fB\fIcommand\fB]\fB [-c \fB\fIconfigurationfile\fB]\fB [-E \fB\fIcommand\fB]\fB [--get-cover-art]\fB [--logOutputLevel=]\fB [-L \fB\fIlatency\fB]\fB [-m \fB\fIbackend\fB]\fB [--meta-dir=\fB\fIdirectory\fB]\fB [-o \fB\fIbackend\fB]\fB [--password=\fB\fIsecret\fB]\fB [-r \fB\fIthreshold\fB]\fB [--statistics]\fB [-S \fB\fImode\fB]\fB [-t \fB\fItimeout\fB]\fB [--tolerance=\fB\fIframes\fB]\fB [-- \fB\fIaudio_backend_options\fB]\fB shairport-sync -D\fB @@ -15,7 +15,7 @@ shairport-sync -R\fB shairport-sync -V\fB \f1 .SH DESCRIPTION -shairport-sync plays audio streamed from iTunes or from an AirPlay device to an Advanced Linux Sound Architecture (ALSA) compatible audio output device. +shairport-sync plays audio streamed from iTunes or from an AirPlay device to an ALSA compatible audio output device (available on Linux and FreeBSD) , to a "sndio" output device (available on OpenBSD, FreeBSD and Linux) or to a PulseAudio output stream (available on Linux). A feature of shairport-sync is that the audio is played synchronously. This means that if many devices are playing the same stream at the same time, all the outputs will stay in step with one another. This allows multiple devices to play the same source without getting out of phase with one another, enabling, for example, simultaneous multi-room operation. @@ -68,28 +68,28 @@ The following substitutions are allowed: \fB%h\f1 for the computer's hostname, \ The default is "%H", which is replaced by the hostname with the first letter capitalised. .TP \fBpassword=\f1\fI"password"\f1\fB;\f1 -Require the password \fIpassword\f1 to connect to the service. If you leave this setting commented out, no password is needed. +Require the password \fIpassword\f1 to connect to the service. If you leave this setting commented out, no password is needed. .TP \fBinterpolation=\f1\fI"mode"\f1\fB;\f1 Interpolate, or "stuff", the audio stream using the \fImode\f1. Interpolation here refers to the process of adding or removing frames of audio to or from the stream sent to the output device to keep it exactly in synchrony with the player. The default mode, "basic", is normally almost completely inaudible. The alternative mode, "soxr", is even less obtrusive but requires much more processing power. For this mode, support for libsoxr, the SoX Resampler Library, must be selected when shairport-sync is compiled. .TP \fBstatistics=\f1\fI"setting"\f1\fB;\f1 -Use this \fIsetting\f1 to enable ("yes") or disable ("no") the output of some statistical information on the console or in the log. The default is to disable statistics. +Use this \fIsetting\f1 to enable ("yes") or disable ("no") the output of some statistical information on the console or in the log. The default is to disable statistics. .TP \fBmdns_backend=\f1\fI"backend"\f1\fB;\f1 -shairport-sync has a number of modules of code ("backends") for interacting with the mDNS service to be used to advertise itself. Normally, the first mDNS backend that works is selected. This setting forces the selection of the specific mDNS \fIbackend\f1. The default is "avahi". Perform the command \fBshairport-sync -h\f1 to get a list of available mDNS modules. +shairport-sync has a number of modules of code ("backends") for interacting with the mDNS service to be used to advertise itself. Normally, the first mDNS backend that works is selected. This setting forces the selection of the specific mDNS \fIbackend\f1. The default is "avahi". Perform the command \fBshairport-sync -h\f1 to get a list of available mDNS modules. .TP \fBoutput_backend=\f1\fI"backend"\f1\fB;\f1 -shairport-sync has a number of modules of code ("backends") through which audio is output. Normally, the first audio backend that works is selected. This setting forces the selection of the specific audio \fIbackend\f1. The default is "alsa". Perform the command \fBshairport-sync -h\f1 to get a list of available audio backends. Only the alsa backend supports synchronisation. +shairport-sync has a number of modules of code ("backends") through which audio is output. Normally, the first audio backend that works is selected. This setting forces the selection of the specific audio \fIbackend\f1. Perform the command \fBshairport-sync -h\f1 to get a list of available audio backends -- the default is the first on this list. Only the "alsa", "sndio" and "pa" backends support synchronisation. .TP \fBport=\f1\fIportnumber\f1\fB;\f1 -Use this to specify the \fIportnumber\f1 shairport-sync uses to listen for service requests from iTunes, etc. The default is port 5000. +Use this to specify the \fIportnumber\f1 shairport-sync uses to listen for service requests from iTunes, etc. The default is port 5000. .TP \fBudp_port_base=\f1\fIportnumber\f1\fB;\f1 -When shairport-sync starts to play audio, it establises three UDP connections to the audio source. Use this setting to specify the starting \fIportnumber\f1 for these three ports. It will pick the first three unused ports starting from \fIportnumber\f1. The default is port 6001. +When shairport-sync starts to play audio, it establises three UDP connections to the audio source. Use this setting to specify the starting \fIportnumber\f1 for these three ports. It will pick the first three unused ports starting from \fIportnumber\f1. The default is port 6001. .TP \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. +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_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. @@ -98,13 +98,13 @@ Allow playback to drift up to \fIseconds\f1 out of exact synchronization before 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. The value \fI0\f1 means no debug information, \fI3\f1 means most debug information. The default is \fI0\f1. +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 \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. +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. +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. @@ -118,98 +118,112 @@ As a third example, you can actually extend the range provided by a mixer. Many 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 \fI"_raop._tcp"\f1. +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 "stereo", "mono", "reverse stereo", "both left" or "both right". Default is "stereo". +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. +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. +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 +\fBaudio_backend_latency_offset_in_seconds=\f1\fIoffset_in_seconds\f1\fB;\f1 +Set this \fIoffset_in_seconds\f1 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_in_seconds=\f1\fIlength_in_seconds\f1\fB;\f1 +Use this \fIlength_in_seconds\f1 to set the desired length of the queue of audio frames in the backend's output buffer. + +The default is 0.15 seconds for the ALSA backend, 0.35 seconds for the PA backend and one second for all other backends. + +If this value is set too small, underflow may occur on low-powered machines. If set too large, the response times to the volume control may become excessive, or it may exceed the backend's buffer size. It may need to be larger on low-powered machines that are also performing other tasks, such as processing metadata. +.TP +\fBaudio_backend_silent_lead_in_time=\f1\fIlead_in_time_in_seconds\f1\fB;\f1 +This is an advanced setting. Use the \fIlead_in_time_in_seconds\f1 to set the desired length of the period of silence (a "silent lead-in") played before a play session begins. + +The purpose of this silent lead-in is to give the backend sufficient time to prepare for operation and to make an estimate (and, importantly, to correct the estimate) of the exact time at which to begin playing audio to achieve initial synchronisation. The value can be from 0.0 up to a maximum of either 4.0 seconds. The actual duration will be close to the setting but can not exceed the latency set by the client, usually 2 seconds or a little more. + +If the value chosen is too short for synchronised backends such as the ALSA, sndio or PA backends, then audio will not be synchronised correctly at the start of play. The default is to have a silent lead-in of approximately the same time as the latency set by the client. .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 \fBoutput_device=\f1\fI"output_device"\f1\fB;\f1 -Use the output device called \fIoutput_device\f1. The default is the device called \fI"default"\f1. +Use the output device called \fIoutput_device\f1. The default is the device called \fI"default"\f1. .TP .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 is ignored. For your information, its functionality has been automatically incorporated in the \fBmixer_control_name\f1 setting -- if you specify a mixer name with the \fBmixer_control_name\f1 setting, it is assumed that the mixer is implemented in hardware. +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 is ignored. For your information, its functionality has been automatically incorporated in the \fBmixer_control_name\f1 setting -- if you specify a mixer name with the \fBmixer_control_name\f1 setting, it is assumed that the mixer is implemented in hardware. .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_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_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. +By default, the mixer is assumed to be output_device. Use this setting to specify a device other than the output device. .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. +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 \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. +Use this optional advanced setting to set the alsa period size near to this value. .TP \fBbuffer_size=\f1\fInumber\f1\fB;\f1 -Use this optional advanced setting to set the alsa buffer size near to this value. +Use this optional advanced setting to set the alsa buffer size near to this value. .TP \fBuse_mmap_if_available=\f1\fI"yes"\f1\fB;\f1 -Use this optional advanced setting to control whether MMAP-based output is used to communicate with the DAC. Default is \fI"yes"\f1. +Use this optional advanced setting to control whether MMAP-based output is used to communicate with the DAC. Default is \fI"yes"\f1. +.TP +\fB"SNDIO" SETTINGS\f1 +These settings are for the SNDIO back end, used to communicate with audio output devices in the SNDIO system. +.TP +\fBdevice=\f1\fI"snd/0"\f1\fB;\f1 +Use this optional setting to specify the name of the output device, e.g. \fI"snd/0"\f1. +.TP +\fBrate=\f1\fI44100\f1\fB;\f1 +Use this optional setting to specify the output rate in frames per second. Valid rates are 44100, 88200, 176400 or 352800. The output device must have the capability to accept data at the specified rate. Default is 44100. +.TP +\fBformat=\f1\fI"S16"\f1\fB;\f1 +Use this optional setting to specify the output format. Allowable values are "U8", "S8", "S16", "S24", "S24_3LE", "S24_3BE" or "S32". The device must have the capability to accept the format you specify. + +"S" means signed; "U" means unsigned; BE means big-endian and LE means little-endian. Except where stated (using *LE or *BE), endianness matches that of the processor. The default is "S16". + +Since the SNDIO backend does not use a hardware mixer for volume control, dither will be introduced into the output if it is less than full volume. Thus, (unless you are ignoring the volume control setting), consider using 32- or 24-bit output if your device is capable of it, to get the lowest possible levels of dither. + +Please note that 32- or 24-bit has not been extensively tested on SNDIO. +.TP +\fBround=\f1\fIvalue\f1\fB;\f1 +Use this optional advanced setting to specify the period size of the SNDIO channel. If omitted, a SNDIO system default value will be used. +.TP +\fBbufsiz=\f1\fIvalue\f1\fB;\f1 +Use this optional advanced setting to specify the buffer size of the SNDIO channel. If omitted, a SNDIO system default value will be used. +.TP +\fB"PA" SETTINGS\f1 +These settings are for the new PulseAudio backend. +.TP +\fBapplication_name=\f1\fI"Shairport Sync"\f1\fB;\f1 +Use this to set the name to appear in the Sounds "Applications" tab when Shairport Sync is active Default is "Shairport Sync". .TP \fB"PIPE" SETTINGS\f1 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 \fIname\f1 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 \fBaplay\f1. The \fIaudio_backend_latency_offset_in_seconds\f1 affects precisely when the first audio packet is sent and the \fIaudio_backend_buffer_desired_length_in_seconds\f1 setting affects the nominal output buffer size. - -These are the settings available within the \fBpipe\f1 group: .TP \fBname=\f1\fI"/path/to/pipe"\f1\fB;\f1 -Use this to specify the name and location of the pipe. The pipe will be created and opened when shairport-sync starts up and will be closed upon shutdown. Frames of audio will be sent to the pipe in packets of 352 frames and will be discarded if the pipe has not have a reader attached. The sender will wait for up to five seconds for a packet to be written before discarding it. -.TP -\fBaudio_backend_latency_offset_in_seconds=\f1\fIoffset_in_seconds\f1\fB;\f1 -Packets of audio frames are written to the pipe synchronously -- that is, they are written at exactly the time they should be played. You can offset the time of initial audio output relative to its nominal time using this setting. For example to send an audio stream to the pipe 100 milliseconds before it is due to be played, set this to -0.1. Default setting is 0.0. -.TP -\fBaudio_backend_buffer_desired_length_in_seconds=\f1\fIbuffer_length_in_seconds\f1\fB;\f1 -Use this setting, in seconds, 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 the pipe. For example, if you send the first packet of audio exactly when it is due and, using a \fIaudio_backend_buffer_desired_length_in_seconds\f1 setting of 1.0, send subsequent packets of audio a second before they are due to be played, they will be buffered in the pipe reader's buffer, giving it a nominal buffer size of 1 second. Note that if the pipe 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 a pipe. Default setting is 1.0 seconds. +Use this to specify the name and location of the pipe. The pipe will be created and opened when shairport-sync starts up and will be closed upon shutdown. Frames of audio will be sent to the pipe in packets of 352 frames and will be discarded if the pipe has not have a reader attached. The sender will wait for up to five seconds for a packet to be written before discarding it. .TP \fB"STDOUT" SETTINGS\f1 -These settings are for the STDOUT backend, used to route audio to standard output ("stdout"). The audio is in raw CD audio format, usually 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 \fBaplay\f1. The \fIaudio_backend_latency_offset_in_seconds\f1 affects precisely when the first audio packet is sent and the \fIaudio_backend_buffer_desired_length_in_seconds\f1 setting affects the nominal output buffer size. - -These are the settings available within the \fBstdout\f1 group: -.TP -\fBaudio_backend_latency_offset_in_seconds=\f1\fIoffset_in_seconds\f1\fB;\f1 -Packets of audio frames are written to stdout synchronously -- that is, they are written at exactly the time they should be played. You can offset the time of initial audio output relative to its nominal time using this setting. For example to send an audio stream to stdout 100 milliseconds before it is due to be played, set this to -0.1. Default setting is 0.0. -.TP -\fBaudio_backend_buffer_desired_length_in_seconds=\f1\fIbuffer_length_in_seconds\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_in_seconds\f1 setting of 1.0, 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 1 second. 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 1.0 seconds. +There are no settings for the STDOUT backend. .TP \fB"AO" SETTINGS\f1 -These settings are for the AO backend, used for the libao audio library. - -There are two settings affecting timing. The \fIaudio_backend_latency_offset_in_seconds\f1 affects precisely when the first audio packet is sent and the \fIaudio_backend_buffer_desired_length_in_seconds\f1 setting affects the nominal output buffer size. - -These are the settings available within the \fBao\f1 group: -.TP -\fBaudio_backend_latency_offset_in_seconds=\f1\fIoffset_in_seconds\f1\fB;\f1 -Packets of audio frames are written to the libao system synchronously -- that is, they are written at exactly the time they should be played. You can offset the time of initial audio output relative to its nominal time using this setting. For example to send an audio stream to stdout 100 milliseconds before it is due to be played, set this to -0.1. Default setting is 0.0. -.TP -\fBaudio_backend_buffer_desired_length_in_seconds=\f1\fIbuffer_length_in_seconds\f1\fB;\f1 -Use this setting, in seconds, 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 the libao system. For example, if you send the first packet of audio exactly when it is due and, using a \fIaudio_backend_buffer_desired_length_in_seconds\f1 setting of 1.0, 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 1 second. Note that if the libao system 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 libao. Default setting is 1.0 seconds. +There are no configuration file settings for the AO backend. .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 the command \fB$ shairport-sync -V\f1; the identification string will contain the word \fBmetadata\f1. @@ -219,40 +233,40 @@ Please note that different sources provide different levels of metadata. Some pr 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". +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". +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. +Specify the absolute path name of the pipe through which metadata should be sent The default is \fI/tmp/shairport-sync-metadata\f1. .TP \fBsocket_address=\f1\fI"hostnameOrIP"\f1\fB;\f1 -If \fIhostnameOrIP\f1 is set to a host name or and IP address, UDP packets containing metadata will be sent to this address. May be a multicast address. Additionally, \fIsocket-port\f1 must be non-zero and \fIenabled\f1 must be set to "yes". +If \fIhostnameOrIP\f1 is set to a host name or and IP address, UDP packets containing metadata will be sent to this address. May be a multicast address. Additionally, \fIsocket-port\f1 must be non-zero and \fIenabled\f1 must be set to "yes". .TP \fBsocket_port=\f1\fIport\f1\fB;\f1 -If \fBsocket_address\f1 is set, use \fIport\f1 to specify the port to send UDP packets to. Must not be zero. +If \fBsocket_address\f1 is set, use \fIport\f1 to specify the port to send UDP packets to. Must not be zero. .TP \fBsocket_msglength=\f1\fI65000\f1\fB;\f1 -The maximum packet size for any UDP metadata. This must be between 500 or 65000. The default is 500. +The maximum packet size for any UDP metadata. This must be between 500 or 65000. The default is 500. .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. +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. +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". +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. +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. +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. .SH OPTIONS This section is about the command-line options available in shairport-sync. @@ -283,7 +297,7 @@ Disconnect the shairport-sync daemon from the output device and exit. (Requires Please note that this feature is deprecated and will be removed in a future version of shairport-sync. .TP \fB-d | --daemon\f1 -Instruct shairport-sync to demonise itself. It will write its Process ID (PID) to a file, usually at \fI/var/run/shairport-sync.pid\f1, which is used by the \fB-k\f1, \fB-D\f1 and \fB-R\f1 options to locate the daemon at a later time. +Instruct shairport-sync to demonise itself. It will write its Process ID (PID) to a file, usually at \fI/var/run/shairport-sync/shairport-sync.pid\f1, which is used by the \fB-k\f1, \fB-D\f1 and \fB-R\f1 options to locate the daemon at a later time. See also the \fB-j\f1 option. .TP \fB-E \f1\fIprogram\f1\fB | --on-stop=\f1\fIprogram\f1 Execute \fIprogram\f1 when playback has ended. Specify the full path to the program, e.g. \fI/usr/bin/logger\f1. Executable scripts can be used, but they must have \fI#!/bin/sh\f1 (or whatever is appropriate) in the headline. @@ -298,6 +312,9 @@ Please note that cover art data may be very large, and may place too great a bur \fB-h | --help\f1 Print brief help message and exit. .TP +\fB-j\f1 +Instruct shairport-sync to demonise itself. Unlike the \fB-d\f1 option, it will not write a Process ID (PID) to a file -- it will just (hence the "j") demonise itself. +.TP \fB-k | --kill\f1 Kill the shairport-sync daemon and exit. (Requires that the daemon has written its PID to an agreed file -- see the \fB-d\f1 option). .TP diff --git a/man/shairport-sync.7.xml b/man/shairport-sync.7.xml index 89cfcfbc..8dd38d68 100644 --- a/man/shairport-sync.7.xml +++ b/man/shairport-sync.7.xml @@ -35,7 +35,7 @@ - shairport-sync [-dvw] + shairport-sync [-djvw] [-a name] [-A latency] [-B command] @@ -64,7 +64,7 @@

shairport-sync plays audio streamed from iTunes or from an AirPlay - device to an Advanced Linux Sound Architecture (ALSA) compatible audio output device.

+ device to an ALSA compatible audio output device (available on Linux and FreeBSD) , to a "sndio" output device (available on OpenBSD, FreeBSD and Linux) or to a PulseAudio output stream (available on Linux).

A feature of shairport-sync is that the audio is played synchronously. This means that if many devices are playing the same stream at the same @@ -133,11 +133,11 @@

password="password";

- Require the password password to connect to the service. If you leave this setting commented out, no password is needed. +

Require the password password to connect to the service. If you leave this setting commented out, no password is needed.

 + + + -

These settings are for the ALSA back end, used to communicate with audio output devices in the ALSA system. @@ -256,159 +279,113 @@

output_device="output_device";

- Use the output device called output_device. The default is the device called "default". +

Use the output device called output_device. The default is the device called "default".

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. +

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 SNDIO back end, used to communicate with audio output devices in the SNDIO system.

+ + + + + + + + +

These settings are for the new PulseAudio backend.

+ +

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_in_seconds affects precisely - when the first audio packet is sent - and the audio_backend_buffer_desired_length_in_seconds 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, usually 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_in_seconds affects precisely when the first audio packet is sent - and the audio_backend_buffer_desired_length_in_seconds setting affects the nominal output buffer size.

-

These are the settings available within the stdout group:

- - - - +

There are no settings for the STDOUT backend.

-

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

-

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

-

These are the settings available within the ao group:

+

There are no configuration file settings for the AO backend.

- - - -

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, @@ -421,33 +398,33 @@

enabled="choice";

- Set the choice to "yes" to enable shairport-sync to look for metadata from the audio source and to forward it, - along with metadata generated by shairport-sync itself, to the metadata pipe. The default is "no". +

Set the choice to "yes" to enable shairport-sync to look for metadata from the audio source and to forward it, + along with metadata generated by shairport-sync itself, to the metadata pipe. The default is "no".

 @@ -456,29 +433,29 @@ @@ -554,9 +531,9 @@

Instruct shairport-sync to demonise itself. It will write its Process ID (PID) to a file, usually at - /var/run/shairport-sync.pid, which is used by the + /var/run/shairport-sync/shairport-sync.pid, which is used by the -k, -D and -R options to locate - the daemon at a later time. + the daemon at a later time. See also the -j option.

@@ -590,6 +567,14 @@

+ +