From ad76e11b947b472d6b7c5afc8345c5aa21d47e3b Mon Sep 17 00:00:00 2001 From: Mike Brady Date: Mon, 13 Jun 2016 10:07:03 +0100 Subject: [PATCH] Small editorial changes to the man pages --- man/shairport-sync.7 | 60 ++++++++++++++-------------- man/shairport-sync.7.xml | 62 ++++++++++++++--------------- man/shairport-sync.html | 84 ++++++++++++++++++++-------------------- 3 files changed, 103 insertions(+), 103 deletions(-) diff --git a/man/shairport-sync.7 b/man/shairport-sync.7 index 85202518..ccbc9929 100644 --- a/man/shairport-sync.7 +++ b/man/shairport-sync.7 @@ -15,11 +15,11 @@ 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 ALSA-compatible audio output device. +shairport-sync plays audio streamed from iTunes or from an AirPlay device to an Advanced Linux Sound Architecture (ALSA) compatible audio output device. -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 play the same source without getting out of phase with one another, enabling, for example, simultaneous multi-room operation. +A feature of shairport-sync is that the audio is played synchronously. This means that if many devices are playing the same stream at the same time, all the outputs will stay in step with one another. This allows multiple devices to play the same source without getting out of phase with one another, enabling, for example, simultaneous multi-room operation. -shairport-sync can additionally be compiled and configured to stream raw audio to a pipe or to stdout. +shairport-sync can be compiled to stream audio, without synchronisation, to a pipe, to stdout or to a libao output device (an "AO" device). It can also be compiled to stream metadata to a pipe or socket. Settings can be made using the configuration file (recommended for all new installations) or by using command-line options. .SH CONFIGURATION FILE SETTINGS @@ -61,7 +61,7 @@ These are the settings available within the \fBgeneral\f1 group: \fBname=\f1\fI"service_name"\f1\fB;\f1 Use this \fIservice_name\f1 to identify this player in iTunes, etc. -The following substitutions are allowed: \fB%h\f1 for the computer's hostname, \fB%H\f1 for the computer's hostname with the first letter capitalised (ASCII only), \fB%v\f1 for the Shairport Sync version number, e.g. "2.8.4" and \fB%V\f1 for the Shairport Sync version string, e.g. "2.8.4-OpenSSL-Avahi-ALSA-soxr-metadata". +The following substitutions are allowed: \fB%h\f1 for the computer's hostname, \fB%H\f1 for the computer's hostname with the first letter capitalised (ASCII only), \fB%v\f1 for the shairport-sync version number, e.g. "2.8.4" and \fB%V\f1 for the shairport-sync version string, e.g. "2.8.4-OpenSSL-Avahi-ALSA-soxr-metadata". The default is "%H", which is replaced by the hostname with the first letter capitalised. .TP @@ -106,7 +106,7 @@ Use this \fIdBvalue\f1 to reduce or increase the attenuation range, in decibels, For example, if a mixer has a minimum volume of -80 dB and a maximum of +20 dB, you might wish to use only 60 dB of the 100 dB available. This might be because the sound becomes inaudible at the lowest setting and unbearably loud at the highest setting -- indeed, many domestic HiFi systems have a volume control range of just 60 to 80dB. -Another potential use might be where the range specified by the mixer does not match the capabilities of the device. For example, the Raspberry Pi's DAC that feeds the built-in audio jack claims a range of 106 dB but has a useful range of only about 35dB. The setting allows you to specify the maximum range from highest to lowest. The range suggested for the Raspberry Pi's built-in audio DAC, which feeds the headphone jack, is 35. Using it in this case gives the volume control a much more useful range of settings. +Another potential use might be where the range specified by the mixer does not match the capabilities of the device. For example, the Raspberry Pi's DAC that feeds the built-in audio jack claims a range of 106 dB but has a useful range of only about 30 dB. The setting allows you to specify the maximum range from highest to lowest. The range suggested for the Raspberry Pi's built-in audio DAC, which feeds the headphone jack, is 30. Using it in this case gives the volume control a much more useful range of settings. As a third example, you can actually extend the range provided by a mixer. Many cheaper DACs have hardware mixers that offer a restricted attenuation range. If you specify a volume range greater than the range of the mixer, software attenuation and hardware attenuation will be combined to give the specified range. @@ -139,7 +139,7 @@ Set this \fIoffset\f1, in frames, to compensate for a fixed delay in the audio b Use this to set the desired number frames to be in the output device's hardware output buffer. The default is 6,615 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. .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 soner 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 "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. .TP \fBperiod_size=\f1\fInumber\f1\fB;\f1 Use this optional advanced setting to set the alsa period size near to this value. @@ -148,7 +148,7 @@ Use this optional advanced setting to set the alsa period size near to this valu Use this optional advanced setting to set the alsa buffer size near to this value. .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, stereo. +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. @@ -160,13 +160,13 @@ These are the settings available within the \fBpipe\f1 group: 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=\f1\fIoffset_in_frames\f1\fB;\f1 -Packets of audio frames are written to the pipe synchronously -- that is, they are written to 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 -4410. Default setting is 0. +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 -4410. Default setting is 0. .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 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\f1 setting of 44100, 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 44,100 frames. 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 44,100 frames. .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: PCM 16 bit little endian, 44,100 samples per second, stereo. +These settings are for the STDOUT backend, used to route audio to standard output ("stdout"). The audio is in raw CD audio format: PCM 16 bit little endian, 44,100 samples per second, interleaved stereo. There are two settings affecting timing that might be useful if the stdout reader is, for example, a program to play an audio stream such as \fBaplay\f1. The \fIaudio_backend_latency_offset\f1 affects precisely when the first audio packet is sent and the \fIaudio_backend_buffer_desired_length\f1 setting affects the nominal output buffer size. @@ -189,10 +189,10 @@ These are the settings available within the \fBao\f1 group: 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 -4410. Default setting is 0. .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 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\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 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 44,100 frames. +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 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\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 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 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. +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. Please note that different sources provide different levels of metadata. Some provide a lot; some provide almost none. @@ -205,10 +205,10 @@ Set the \fIchoice\f1 to "yes" to enable shairport-sync to look for metadata from 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. "socket-port" must be non-zero and "enabled" 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. @@ -235,11 +235,11 @@ If \fBchoice\f1 is set to "yes", then another source will be able to interrupt a 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. +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. +shairport-sync now sets latencies automatically using information supplied by the source, typically either 88,200 or 99,577 frames. The following relates to the old scheme of using fixed latencies, which ignored the latency information supplied by the source. There are four default latency settings. One latency matches the latency used by recent versions of iTunes when playing audio and another matches the latency used by so-called "AirPlay" devices, including iOS devices and iTunes and Quicktime Player when they are playing video. A third latency is used when the audio source is forked-daapd. The fourth latency is the default if no other latency is chosen and is used for older versions of iTunes. @@ -257,23 +257,25 @@ This is the \fIlatency\f1, in frames, used for forkedDaapd sources. Default is 9 \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 compatibility with older installations of Shairport Sync. +This section is about the command-line options available in 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. +Note: if you are setting up shairport-sync for the first time or are updating an existing installation, you are encouraged to use the configuration file settings described above. Most of the command-line options described below simply replicate the configuration settings and are retained to provide backward compatibility with older installations of shairport-sync. -The command line for shairport-sync can take two kinds of options: regular \fBprogram options\f1 and \fBaudio backend options\f1. Program options are always listed first, followed by any audio backend options, preceded by a \fB--\f1 symbol. +Many command-line options take sensible default values, so you can normally ignore most of them. See the EXAMPLES section for typical usages. + +There are two kinds of command-line options for shairport-sync: regular \fBprogram options\f1 and \fBaudio backend options\f1. Program options are always listed first, followed by any audio backend options, preceded by a \fB--\f1 symbol. .SH PROGRAM OPTIONS -These options are used by shairport-sync itself. +These command-line options are used by shairport-sync itself. .TP \fB-a \f1\fIservice name\f1\fB | --name=\f1\fIservice name\f1 -Use this \fIservice name\f1 to identify this player in iTunes, etc. The following substitutions are allowed: \fB%h\f1 for the computer's hostname, \fB%H\f1 for the computer's hostname with the first letter capitalised (ASCII only), \fB%v\f1 for the Shairport Sync version number, e.g. "2.8.4" and \fB%V\f1 for the Shairport Sync version string, e.g. "2.8.4-OpenSSL-Avahi-ALSA-soxr-metadata". +Use this \fIservice name\f1 to identify this player in iTunes, etc. The following substitutions are allowed: \fB%h\f1 for the computer's hostname, \fB%H\f1 for the computer's hostname with the first letter capitalised (ASCII only), \fB%v\f1 for the shairport-sync version number, e.g. "2.8.4" and \fB%V\f1 for the shairport-sync version string, e.g. "2.8.4-OpenSSL-Avahi-ALSA-soxr-metadata". The default is "%H", which is replaced by the hostname with the first letter capitalised. .TP \fB-A | --AirPlayLatency=\f1\fIlatency\f1 Use this \fIlatency\f1, in frames, for audio streamed from an AirPlay device. The default is 88,200 frames, where there are 44,100 frames to the second. -Please note that this feature is deprecated and will be removed in a future version of Shairport Sync. +Please note that this feature is deprecated and will be removed in a future version of shairport-sync. .TP \fB-B \f1\fIprogram\f1\fB | --on-start=\f1\fIprogram\f1 Execute \fIprogram\f1 when playback is about to begin. 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. @@ -286,7 +288,7 @@ Read configuration settings from \fIfilename\f1. The default is to read them fro \fB-D | --disconnectFromOutput\f1 Disconnect the shairport-sync daemon from the output device and exit. (Requires that the daemon has written its PID to an agreed file -- see the \fB-d\f1 option). -Please note that this feature is deprecated and will be removed in a future version of Shairport Sync. +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. @@ -299,7 +301,7 @@ If you want shairport-sync to wait until the command has completed before contin \fB--forkedDaapdLatency=\f1\fIlatency\f1 Use this \fIlatency\f1, in frames, for audio streamed from a forked-daapd based source. The default is 99,400 frames, where there are 44,100 frames to the second. -Please note that this feature is deprecated and will be removed in a future version of Shairport Sync. +Please note that this feature is deprecated and will be removed in a future version of shairport-sync. .TP \fB--get-coverart\f1 This option requires the \fB--meta-dir\f1 option to be set, and enables shairport-sync to request cover art from the source and to transmit it through the metadata pipe. @@ -312,7 +314,7 @@ Print brief help message and exit. \fB-i | --iTunesLatency=\f1\fIlatency\f1 Use this \fIlatency\f1, in frames, for audio streamed from an iTunes source, where iTunes is Version 10 or later. The default is 99,400 frames, where there are 44,100 frames to the second. If the source is iTunes but is earler than Version 10, the \fIdefault latency\f1 is used (see the \fB-L\f1 option). Some third party programs masquerade as older versions of iTunes. -Please note that this feature is deprecated and will be removed in a future version of Shairport Sync. +Please note that this feature is deprecated and will be removed in a future version of shairport-sync. .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). @@ -320,7 +322,7 @@ Kill the shairport-sync daemon and exit. (Requires that the daemon has written i \fB-L | --latency=\f1\fIlatency\f1 Use this to set the \fIdefault latency\f1, in frames, for audio coming from an unidentified source or from an iTunes Version 9 or earlier source. The standard value for the \fIdefault latency\f1 is 88,200 frames, where there are 44,100 frames to the second. -Please note that this feature is deprecated and will be removed in a future version of Shairport Sync. +Please note that this feature is deprecated and will be removed in a future version of shairport-sync. .TP \fB--meta-dir=\f1\fIdirectory\f1 Listen for metadata coming from the source and send it, along with metadata from shairport-sync itself, to a pipe called \fIshairport-sync-metadata\f1 in the \fIdirectory\f1 you specify. If you add the \fB--get-cover-art\f1 then cover art will be sent through the pipe too. See \fBhttps://github.com/mikebrady/shairport-sync-metadata-reader\f1 for a sample metadata reader. @@ -340,7 +342,7 @@ Require the password \fIsecret\f1 to be able to connect and stream to the servic \fB-R | --reconnectToOutput\f1 Reconnect the shairport-sync daemon to the output device and exit. It may take a few seconds to synchronise. (Requires that the daemon has written its PID to an agreed file -- see the \fB-d\f1 option). -Please note that this feature is deprecated and will be removed in a future version of Shairport Sync. +Please note that this feature is deprecated and will be removed in a future version of shairport-sync. .TP \fB-r \f1\fIthreshold\f1\fB | --resync=\f1\fIthreshold\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 \fB0\f1 to disable resynchronisation. @@ -368,7 +370,7 @@ Print debug information. Repeat up to three times to get more detail. \fB-w | --wait-cmd\f1 Wait for commands specified using \fB-B\f1 or \fB-E\f1 to complete before continuing execution. .SH AUDIO BACKEND OPTIONS -These options are passed to the chosen audio backend. The audio backend options are preceded by a \fB--\f1 symbol to introduce them and to separate them from any program options. In this way, option letters can be used as program options and also as audio backend options without ambiguity. +These command-line options are passed to the chosen audio backend. The audio backend options are preceded by a \fB--\f1 symbol to introduce them and to separate them from any program options. In this way, option letters can be used as program options and also as audio backend options without ambiguity. In the ALSA backend, audio is sent to an output device which you can specify using the \fB-d\f1 option. The output level (the "volume") is controlled using a level control associated with a mixer. By default, the mixer is implemented in shairport-sync itself in software. To use a hardware level control on a mixer on the sound card, specify the name of the mixer control with the \fB-c\f1 option. If the mixer is not associated with the output device, then you need to specify where the mixer is to be found with the \fB-m\f1 option. .TP @@ -394,9 +396,9 @@ The example above is slightly contrived in order to show the use of the \fB-m\f1 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 .SH COMMENTS diff --git a/man/shairport-sync.7.xml b/man/shairport-sync.7.xml index 530f1114..c4ff2d86 100644 --- a/man/shairport-sync.7.xml +++ b/man/shairport-sync.7.xml @@ -65,16 +65,16 @@

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 Advanced Linux Sound Architecture (ALSA) compatible audio output device.

-

A feature of shairport-sync is that the audio is played synchronously. +

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 play the same source without getting out of phase with one another, + This allows multiple devices to play the same source without getting out of phase with one another, enabling, for example, simultaneous multi-room operation.

-

shairport-sync can be compiled to stream raw audio to a pipe or to stdout. It can also be compiled to stream metadata to a pipe or socket.

+

shairport-sync can be compiled to stream audio, without synchronisation, to a pipe, to stdout or to a libao output device (an "AO" device). It can also be compiled to stream metadata to a pipe or socket.

Settings can be made using the configuration file (recommended for all new installations) or by using command-line options.

@@ -122,8 +122,8 @@

The following substitutions are allowed: %h for the computer's hostname, %H for the computer's hostname with the first letter capitalised (ASCII only), - %v for the Shairport Sync version number, e.g. "2.8.4" and - %V for the Shairport Sync version string, e.g. "2.8.4-OpenSSL-Avahi-ALSA-soxr-metadata".

+ %v for the shairport-sync version number, e.g. "2.8.4" and + %V for the shairport-sync version string, e.g. "2.8.4-OpenSSL-Avahi-ALSA-soxr-metadata".

The default is "%H", which is replaced by the hostname with the first letter capitalised.

@@ -303,7 +303,7 @@ @@ -321,7 +321,7 @@

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

+ The audio is in raw CD audio format: PCM 16 bit little endian, 44,100 samples per second, interleaved stereo.

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

@@ -413,12 +413,10 @@ The maximum packet size for any UDP metadata. This must be between 500 or 65000. The default is 500. -

shairport-sync can run programs just before it starts to play an audio stream and just after it finishes. You specify them using the sessioncontrol group settings run_this_before_play_begins and run_this_after_play_ends.

- -

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

+

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.

+

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

The following relates to the old scheme of using fixed latencies, which ignored the latency information supplied by the source. There are four default latency settings. One latency matches the latency used by recent versions of @@ -462,7 +460,6 @@ instead of changing these individual latencies, use the audio_backend_latency_offset setting in the alsa group (or the appropriate other group if you're not outputing through the alsa backend).

- - - + +

This section is about the command-line options available in shairport-sync.

-

Note: if you are setting up Shairport Sync for the first time or are updating an existing installation, - you are encouraged to use the configuration file settings described above. Most of the options described below - simply replicate the configuration settings and are retained to provide backward compatibility 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 command-line options described below + simply replicate the configuration settings and are retained to provide backward compatibility with older installations of shairport-sync.

-

Many of the options take sensible default values, so you can normally +

Many command-line options take sensible default values, so you can normally ignore most of them. See the EXAMPLES section for typical usages.

-

The command line for shairport-sync can take two kinds of options: +

There are two kinds of command-line options for shairport-sync: regular program options and audio backend options. Program options are always listed first, followed by any audio backend options, preceded by a -- symbol.

-

These options are used by shairport-sync itself.

+

These command-line options are used by shairport-sync itself.

@@ -523,7 +520,7 @@ device. The default is 88,200 frames, where there are 44,100 frames to the second.

-

Please note that this feature is deprecated and will be removed in a future version of Shairport Sync.

+

Please note that this feature is deprecated and will be removed in a future version of shairport-sync.

@@ -554,7 +551,7 @@ exit. (Requires that the daemon has written its PID to an agreed file -- see the -d option).

-

Please note that this feature is deprecated and will be removed in a future version of Shairport Sync.

+

Please note that this feature is deprecated and will be removed in a future version of shairport-sync.

@@ -588,7 +585,7 @@ source. The default is 99,400 frames, where there are 44,100 frames to the second.

-

Please note that this feature is deprecated and will be removed in a future version of Shairport Sync.

+

Please note that this feature is deprecated and will be removed in a future version of shairport-sync.

@@ -617,7 +614,7 @@ source, where iTunes is Version 10 or later. The default is 99,400 frames, where there are 44,100 frames to the second. If the source is iTunes but is earler than Version 10, the default latency is used (see the -L option). Some third party programs masquerade as older versions of iTunes.

-

Please note that this feature is deprecated and will be removed in a future version of Shairport Sync.

+

Please note that this feature is deprecated and will be removed in a future version of shairport-sync.

@@ -635,7 +632,7 @@ Use this to set the default latency, in frames, for audio coming from an unidentified source or from an iTunes Version 9 or earlier source. The standard value for the default latency is 88,200 frames, where there are 44,100 frames to the second.

-

Please note that this feature is deprecated and will be removed in a future version of Shairport Sync.

+

Please note that this feature is deprecated and will be removed in a future version of shairport-sync.

@@ -691,7 +688,7 @@ the daemon has written its PID to an agreed file -- see the -d option).

-

Please note that this feature is deprecated and will be removed in a future version of Shairport Sync.

+

Please note that this feature is deprecated and will be removed in a future version of shairport-sync.

@@ -777,10 +774,11 @@
-

These options are passed to the chosen audio backend. The audio backend options are +

These command-line options are passed to the chosen audio backend. The audio backend options are preceded by a -- symbol to introduce them and to separate them from any program options. In this way, option letters can be used as program options and also as audio backend options without ambiguity.

+

In the ALSA backend, audio is sent to an output device which you can specify using the -d option. The output level (the "volume") is controlled using a level control associated with a mixer. @@ -865,8 +863,8 @@

-

Mike Brady developed Shairport Sync from the original Shairport by James Laird.

-

Shairport Sync can be found at

+

Mike Brady developed shairport-sync from the original Shairport by James Laird.

+

shairport-sync can be found at

Shairport can be found at

diff --git a/man/shairport-sync.html b/man/shairport-sync.html index 121f5281..41dfd64a 100644 --- a/man/shairport-sync.html +++ b/man/shairport-sync.html @@ -44,16 +44,16 @@

Description

shairport-sync plays audio streamed from iTunes or from an AirPlay - device to an ALSA-compatible audio output device.

+ device to an Advanced Linux Sound Architecture (ALSA) compatible audio output device.

-

A feature of shairport-sync is that the audio is played synchronously. +

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 play the same source without getting out of phase with one another, + This allows multiple devices to play the same source without getting out of phase with one another, enabling, for example, simultaneous multi-room operation.

-

shairport-sync can additionally be compiled and configured to stream raw audio to a pipe or to stdout.

+

shairport-sync can be compiled to stream audio, without synchronisation, to a pipe, to stdout or to a libao output device (an "AO" device). It can also be compiled to stream metadata to a pipe or socket.

Settings can be made using the configuration file (recommended for all new installations) or by using command-line options.

@@ -103,8 +103,8 @@

The following substitutions are allowed: %h for the computer's hostname, %H for the computer's hostname with the first letter capitalised (ASCII only), - %v for the Shairport Sync version number, e.g. "2.8.4" and - %V for the Shairport Sync version string, e.g. "2.8.4-OpenSSL-Avahi-ALSA-soxr-metadata".

+ %v for the shairport-sync version number, e.g. "2.8.4" and + %V for the shairport-sync version string, e.g. "2.8.4-OpenSSL-Avahi-ALSA-soxr-metadata".

The default is "%H", which is replaced by the hostname with the first letter capitalised.

@@ -185,9 +185,9 @@ This might be because the sound becomes inaudible at the lowest setting and unbearably loud at the highest setting -- indeed, many domestic HiFi systems have a volume control range of just 60 to 80dB.

Another potential use might be where the range specified by the mixer does not match the capabilities of the device. - For example, the Raspberry Pi's DAC that feeds the built-in audio jack claims a range of 106 dB but has a useful range of only about 35dB. + For example, the Raspberry Pi's DAC that feeds the built-in audio jack claims a range of 106 dB but has a useful range of only about 30 dB. The setting allows you to specify the maximum range from highest to lowest. - The range suggested for the Raspberry Pi's built-in audio DAC, which feeds the headphone jack, is 35. + The range suggested for the Raspberry Pi's built-in audio DAC, which feeds the headphone jack, is 30. Using it in this case gives the volume control a much more useful range of settings.

As a third example, you can actually extend the range provided by a mixer. Many cheaper DACs have hardware mixers that offer a restricted attenuation range. @@ -250,7 +250,7 @@

disable_synchronization="no";

This is an advanced setting and is for debugging only. Set to "yes" to disable synchronization. Default is "no". - If you use it to disable synchronisation, then soner or later you'll experience audio glitches due to + If you use it to disable synchronisation, then sooner or later you'll experience audio glitches due to audio buffer overflow or underflow. @@ -265,16 +265,18 @@

"PIPE" SETTINGS

These settings are for the PIPE backend, used to route audio to a named unix pipe. The audio is in raw CD audio format: PCM 16 bit little endian, 44,100 samples per second, - stereo.

+ interleaved stereo.

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

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

These are the settings available within the pipe group:

name="/path/to/pipe";

- Use this to specify the name and location of the pipe. The pipe will be created and opened when shairport-sync starts up and will be closed upon shutdown. + 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. @@ -282,7 +284,7 @@

audio_backend_latency_offset=offset_in_frames;

- Packets of audio frames are written to the pipe synchronously -- that is, they are written to at exactly the time they should be played. + 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 -4410. Default setting is 0. @@ -300,7 +302,7 @@

"STDOUT" SETTINGS

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

+ The audio is in raw CD audio format: PCM 16 bit little endian, 44,100 samples per second, interleaved stereo.

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

@@ -344,7 +346,7 @@

audio_backend_buffer_desired_length=buffer_length_in_frames;

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 to the libao system. + 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 audio_backend_buffer_desired_length 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 libao system consumes audio packets faster or slower than they are supplied, the buffer will eventually empty or overflow -- @@ -356,7 +358,7 @@

shairport-sync can process metadata provided by the source, such as Track Number, Album Name, cover art, etc. and can provide additional metadata such as volume level, pause/resume, etc. It sends the metadata to a pipe, by default /tmp/shairport-sync-metadata. To process metadata, shairport-sync must have been compiled with metadata support included. - You can check that this is so by running shairport-sync -V; the identification string will contain the word metadata.

+ You can check that this is so by running the command $ shairport-sync -V; the identification string will contain the word metadata.

Please note that different sources provide different levels of metadata. Some provide a lot; some provide almost none.

The metadata group of settings allow you to enable metadata handling and to control certain aspects of it:

@@ -375,13 +377,13 @@

pipe_name="filepathname";

- Specify the absolute path name of the pipe through which metadata should be sent The default is /tmp/shairport-sync-metadata". + Specify the absolute path name of the pipe through which metadata should be sent The default is /tmp/shairport-sync-metadata.

socket_address="hostnameOrIP";

If hostnameOrIP is set to a host name or and IP address, UDP packets containing metadata will be sent to this address. - May be a multicast address. "socket-port" must be non-zero and "enabled" must be set to "yes". + May be a multicast address. Additionally, socket-port must be non-zero and enabled must be set to "yes".

socket_port=port;

@@ -392,12 +394,10 @@ The maximum packet size for any UDP metadata. This must be between 500 or 65000. The default is 500. -

"SESSIONCONTROL" SETTINGS

shairport-sync can run programs just before it starts to play an audio stream and just after it finishes. You specify them using the sessioncontrol group settings run_this_before_play_begins and run_this_after_play_ends.

-

run_this_before_play_begins="/path/to/application and args";

Here you can specify a program and its arguments that will be run just before a play session begins. Be careful to include the full path to the application. @@ -426,11 +426,11 @@

"LATENCIES" SETTINGS

-

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

+

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.

+

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

The following relates to the old scheme of using fixed latencies, which ignored the latency information supplied by the source. There are four default latency settings. One latency matches the latency used by recent versions of @@ -441,7 +441,6 @@ instead of changing these individual latencies, use the audio_backend_latency_offset setting in the alsa group (or the appropriate other group if you're not outputing through the alsa backend).

-

itunes=latency;

This is the latency, in frames, used for iTunes 10 or later. Default is 99,400. @@ -458,22 +457,22 @@

default=latency;

This is the latency, in frames, used when the source is unrecognised. Default is 88,200. - - +

Options

+

This section is about the command-line options available in shairport-sync.

-

Note: if you are setting up Shairport Sync for the first time or are updating an existing installation, - you are encouraged to use the configuration file settings described above. Most of the options described below - simply replicate the configuration settings and are retained to provide backward compatibility 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 command-line options described below + simply replicate the configuration settings and are retained to provide backward compatibility with older installations of shairport-sync.

-

Many of the options take sensible default values, so you can normally +

Many command-line options take sensible default values, so you can normally ignore most of them. See the EXAMPLES section for typical usages.

-

The command line for shairport-sync can take two kinds of options: +

There are two kinds of command-line options for shairport-sync: regular program options and audio backend options. Program options are always listed first, followed by any audio backend options, preceded by @@ -481,7 +480,7 @@

Program Options

-

These options are used by shairport-sync itself.

+

These command-line options are used by shairport-sync itself.

@@ -493,8 +492,8 @@

The following substitutions are allowed: %h for the computer's hostname, %H for the computer's hostname with the first letter capitalised (ASCII only), - %v for the Shairport Sync version number, e.g. "2.8.4" and - %V for the Shairport Sync version string, e.g. "2.8.4-OpenSSL-Avahi-ALSA-soxr-metadata".

+ %v for the shairport-sync version number, e.g. "2.8.4" and + %V for the shairport-sync version string, e.g. "2.8.4-OpenSSL-Avahi-ALSA-soxr-metadata".

The default is "%H", which is replaced by the hostname with the first letter capitalised.

@@ -506,7 +505,7 @@ device. The default is 88,200 frames, where there are 44,100 frames to the second.

-

Please note that this feature is deprecated and will be removed in a future version of Shairport Sync.

+

Please note that this feature is deprecated and will be removed in a future version of shairport-sync.

@@ -537,7 +536,7 @@ exit. (Requires that the daemon has written its PID to an agreed file -- see the -d option).

-

Please note that this feature is deprecated and will be removed in a future version of Shairport Sync.

+

Please note that this feature is deprecated and will be removed in a future version of shairport-sync.

@@ -571,7 +570,7 @@ source. The default is 99,400 frames, where there are 44,100 frames to the second.

-

Please note that this feature is deprecated and will be removed in a future version of Shairport Sync.

+

Please note that this feature is deprecated and will be removed in a future version of shairport-sync.

@@ -600,7 +599,7 @@ source, where iTunes is Version 10 or later. The default is 99,400 frames, where there are 44,100 frames to the second. If the source is iTunes but is earler than Version 10, the default latency is used (see the -L option). Some third party programs masquerade as older versions of iTunes.

-

Please note that this feature is deprecated and will be removed in a future version of Shairport Sync.

+

Please note that this feature is deprecated and will be removed in a future version of shairport-sync.

@@ -618,7 +617,7 @@ Use this to set the default latency, in frames, for audio coming from an unidentified source or from an iTunes Version 9 or earlier source. The standard value for the default latency is 88,200 frames, where there are 44,100 frames to the second.

-

Please note that this feature is deprecated and will be removed in a future version of Shairport Sync.

+

Please note that this feature is deprecated and will be removed in a future version of shairport-sync.

@@ -674,7 +673,7 @@ the daemon has written its PID to an agreed file -- see the -d option).

-

Please note that this feature is deprecated and will be removed in a future version of Shairport Sync.

+

Please note that this feature is deprecated and will be removed in a future version of shairport-sync.

@@ -761,10 +760,11 @@

Audio Backend Options

-

These options are passed to the chosen audio backend. The audio backend options are +

These command-line options are passed to the chosen audio backend. The audio backend options are preceded by a -- symbol to introduce them and to separate them from any program options. In this way, option letters can be used as program options and also as audio backend options without ambiguity.

+

In the ALSA backend, audio is sent to an output device which you can specify using the -d option. The output level (the "volume") is controlled using a level control associated with a mixer. @@ -855,8 +855,8 @@

Credits

-

Mike Brady developed Shairport Sync from the original Shairport by James Laird.

-

Shairport Sync can be found at https://github.com/mikebrady/shairport-sync.

+

Mike Brady developed shairport-sync from the original Shairport by James Laird.

+

shairport-sync can be found at https://github.com/mikebrady/shairport-sync.

Shairport can be found at https://github.com/abrasive/shairport.