diff options
| author | Mike Brady <mikebrady@eircom.net> | 2015-08-20 10:12:53 -0400 |
|---|---|---|
| committer | Mike Brady <mikebrady@eircom.net> | 2015-08-20 10:12:53 -0400 |
| commit | a258925eae6ced61cc6bc73d21e3ee8134943f51 (patch) | |
| tree | 1b35b5f047171028af7ab98d1e82cffd5934086d /man | |
| parent | f8f7a3f11dda4214096f21e6d82c8e7e3d0905d5 (diff) | |
More edits and typo fixes and update references to mixer_type
Diffstat (limited to 'man')
| -rw-r--r-- | man/shairport-sync.7 | 60 | ||||
| -rw-r--r-- | man/shairport-sync.7.xml | 82 | ||||
| -rw-r--r-- | man/shairport-sync.html | 82 |
3 files changed, 113 insertions, 111 deletions
diff --git a/man/shairport-sync.7 b/man/shairport-sync.7 index 6301ed3..1449c43 100644 --- a/man/shairport-sync.7 +++ b/man/shairport-sync.7 @@ -17,11 +17,13 @@ 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 audio device connected via an audio back end. At present, the only fully-implemented back end is for ALSA. +shairport-sync plays audio streamed from iTunes or from an AirPlay device to an 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. -Settings can be made using the configuration file (recommended for all new installations) or the by using command-line options. +shairport-sync can additionally be compiled and configured to stream raw audio to a pipe or to stdout. + +Settings can be made using the configuration file (recommended for all new installations) or by using command-line options. .SH CONFIGURATION FILE SETTINGS You should use the configuration file for setting up shairport-sync. This file is normally \fI/etc/shairport-sync.conf\f1. You may need to have root privileges to modify it. @@ -43,13 +45,11 @@ Settings are organised into groups, for example, there is a "general" group of s \fBoutput_device = "hw:0";\f1 -\fBmixer_type = "hardware";\f1 - \fBmixer_control_name = "PCM";\f1 \fB};\f1 -Most settings have sensible default values, so -- as in the example above -- users generally only need to set (1) the service name, (2) a password (if desired) and (3) the output device. If the output device has a hardware mixer that can be used for volume control, then (4) the fact that the output mixer is hardware and (5) the output device mixer's volume-control name should be specificed. It is highly desirable to use the hardware mixer for volume control, if available -- response time is reduced to zero and the processor load is reduced. In the example above, "soxr" interpolation was also enabled. +Most settings have sensible default values, so -- as in the example above -- users generally only need to set (1) the service name, (2) a password (if desired) and (3) the output device. If the output device has a mixer that can be used for volume control, then (4) the volume control's name should be specificed. It is highly desirable to use the output device's mixer for volume control, if available -- response time is reduced to zero and the processor load is reduced. In the example above, "soxr" interpolation was also enabled. A sample configuration file with all possible settings, but with all of them commented out, is installed at \fI/etc/shairport-sync.conf.sample\f1. @@ -73,25 +73,25 @@ Interpolate, or "stuff", the audio stream using the \fImode\f1. Interpolation he 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. 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. .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\fI6001\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. +\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. .TP -\fBudp_port_range=\f1\fI100\f1\fB;\f1 -Use this in conjunction with the prevous setting to specify the range 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. +\fBudp_port_range=\f1\fIrange\f1\fB;\f1 +Use this in conjunction with the prevous setting to specify the \fIrange\f1 of ports that can be checked for availability. Only three ports are needed. The default is 100, thus 100 ports will be checked from port 6001 upwards until three are found. .TP \fBdrift=\f1\fIframes\f1\fB;\f1 Allow playback to drift up to \fIframes\f1 out of exact synchronization before attempting to correct it. The default is 88 frames, i.e. 2 ms. The smaller the tolerance, the more likely it is that overcorrection will occur. Overcorrection is when more corrections (insertions and deletions) are made than are strictly necessary to keep the stream in sync. Use the \fBstatistics\f1 setting to monitor correction levels. Corrections should not greatly exceed net corrections. .TP \fBresync_threshold=\f1\fIthreshold\f1\fB;\f1 -Resynchronise if timings differ by more than \fBthreshold\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 0 to disable resynchronisation. +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 0 to disable resynchronisation. .TP \fBlog_verbosity=\f1\fI0\f1\fB;\f1 Use this to specify how much debugging information should be output or logged. "0" means no debug information, "3" means most debug information. The default is "0". @@ -117,21 +117,21 @@ This is the \fIlatency\f1, in frames, used for forkedDaapd sources. Default is 9 This is the \fIlatency\f1, in frames, used when the source is unrecognised. Default is 88,200. .TP \fB"METADATA" SETTINGS\f1 -Shairport Sync can process metadata provided by the source, such as Track Number, Album Name, cover art, etc. and can provide additional metadata such as volume level, pause/resume, etc. It provides the metadata to a pipe, by default \fI/tmp/shairport-sync-metadata\f1. To process metadata, Shairport Sync must have been compiled with metadata support included. You can check tht 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 provides the metadata to a pipe, by default \fI/tmp/shairport-sync-metadata\f1. To process metadata, shairport-sync must have been compiled with metadata support included. You can check that this is so by running \fBshairport-sync -V\f1; the identification string will contain the word \fBmetadata\f1. The \fBmetadata\f1 group of settings allow you to enable metadata handling and to control certain aspects of it: .TP \fBenabled=\f1\fI"choice"\f1\fB;\f1 -Set the \fIchoice\f1 to "yes" to enable Shairport Sync to look for metadata from the audio source and to forward it, along with metadata generated by Shairport Sync itself, to the metadata pipe. The default is "no". +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 forward it to the metadata pipe. A reason for not enabling cover art is that the images can sometimes be very large and mey 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". .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. +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. @@ -140,7 +140,7 @@ Here you can specify a program and its arguments that will be run just before a 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. @@ -149,24 +149,24 @@ 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"ALSA" SETTINGS\f1 -These settings are for the ALSA back end, used 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: +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 "default". .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, shaiport-sync will control the volume in software. \fBmixer_type=\f1\fI"mixer_type"\f1\fB;\f1 +Specify the \fIname\f1 of the mixer control to be used by shairport-sync to control the volume. The mixer control must be on the mixer device, which by default is the output device. If you do not specify a mixer control name, shairport-sync will adjust the volume in software. \fBmixer_type=\f1\fI"mixer_type"\f1\fB;\f1 This setting is deprecated and will be removed soon. If you wish to use a mixer control to control the volume, then set \fImixer_type\f1 to "hardware". The default is "software". .TP \fBmixer_device=\f1\fI"mixer_device"\f1\fB;\f1 -By default, the mixer is assumed to be output_device is. Use this setting to specify a device other than the output device. +By default, the mixer is assumed to be output_device. Use this setting to specify a device other than the output device. .TP \fBaudio_backend_latency_offset=\f1\fIoffset\f1\fB;\f1 Set this \fIoffset\f1, in frames, to compensate for a fixed delay in the audio back end. For example, if the output device delays by 100 ms, set this to -4410. .TP \fBaudio_backend_buffer_desired_length=\f1\fIlength\f1\fB;\f1 -Use this to set the desired number frames to be in the output device's hardware output buffer. The default is 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 a software mixer become annoying, or it may exceed the hardware buffer size. It may need to be larger on low-powered machines performing other tasks, such as processing metadata. +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 \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. @@ -178,13 +178,13 @@ There are two further settings affecting timing that might be useful if the pipe 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. +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. .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 faster or slower than they are supplied, the buffer will empty or overflow eventually -- Shairport Sync performs no stuffing or interpolation when writing to a pipe. Default setting is 44,100. +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. @@ -197,8 +197,10 @@ These are the settings available within the \fBstdout\f1 group: 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 -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 stdout. For example, if you send the first packet of audio exactly when it is due and, using a \fIaudio_backend_buffer_desired_length\f1 setting of 44100, send subsequent packets of audio a second before they are due to be played, they will be buffered in the stdout reader's buffer, giving it a nominal buffer size of 44,100 frames. Note that if the stdout reader consumes audio faster or slower than they are supplied, the buffer will empty or overflow eventually -- Shairport Sync performs no stuffing or interpolation when writing to stdout. Default setting is 44,100. +Use this setting, in frames, to set the size of the output buffer. It works by determining how soon the second and subsequent packets of audio frames are sent to stdout. For example, if you send the first packet of audio exactly when it is due and, using a \fIaudio_backend_buffer_desired_length\f1 setting of 44100, send subsequent packets of audio a second before they are due to be played, they will be buffered in the stdout reader's buffer, giving it a nominal buffer size of 44,100 frames. Note that if the stdout reader consumes audio packets faster or slower than they are supplied, the buffer will eventually empty or overflow -- shairport-sync performs no stuffing or interpolation when writing to stdout. Default setting is 44,100 frames. .SH OPTIONS +Note: if you are setting up shairport-sync for the first time or are updating an existing installation, you are encouraged to use the configuration file settings described above. Most of the options described below simply replicate the configuration settings and are retained to provide backward compatability with older installations of shairport-sync. + Many of the 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: 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. @@ -308,17 +310,17 @@ Use the specified output \fIdevice\f1. You may specify a card, e.g. \fBhw:0\f1, Use the specified hardware \fImixer\f1 for volume control. Use this to specify where the mixer is to be found. For example, if the mixer is associated with a card, as is often the case, specify the card, e.g. \fBhw:0\f1. If (unusually) the mixer is associated with a specific device on a card, specify the device, e.g. \fBhw:0,1\f1. The default is the device named in the \fB-d\f1 option, if given, or the device named \fBdefault\f1. .TP \fB-t \f1\fIdevicetype\f1 -The type of the output device is \fIdevicetype\f1 which must be \fBhardware\f1 or \fBsoftware\f1. The default is \fBsoftware\f1. If you specify \fBhardware\f1 you must also specify the output device using the \fB-d\f1 option and the name of the volume control using the \fB-c\f1 option. You may also need to specify the mixer using the \fB-m\f1 option. +This option is deprecated and is ignored. For your information, its functionality has been automatically incorporated in the -c option -- if you specify a mixer name with the -c option, it is assumed that the mixer is implemented in hardware. .SH EXAMPLES Here is a slightly contrived but typical example: -shairport-sync \fB-d\f1 \fB-a "Joe's Stereo"\f1 \fB-S soxr\f1 \fB--\f1 \fB-d hw:1,0\f1 \fB-m hw:1\f1 \fB-t hardware\f1 \fB-c PCM\f1 +shairport-sync \fB-d\f1 \fB-a "Joe's Stereo"\f1 \fB-S soxr\f1 \fB--\f1 \fB-d hw:1,0\f1 \fB-m hw:1\f1 \fB-c PCM\f1 -The program will run in daemon mode ( \fB-d\f1 ), will be visible as "Joe's Stereo" ( \fB-a "Joe's Stereo"\f1 ) and will use the SoX Resampler Library-based stuffing ( \fB-S soxr\f1 ). The audio backend options following the \fB--\f1 separator specify that the audio will be output on output 0 of soundcard 1 ( \fB-d hw:1,0\f1 ) and will take advantage of the same sound card's hardware (\fB-t hardware\f1) mixer ( \fB-m hw:1\f1 ) using the level control named "PCM" ( \fB-c "PCM"\f1 ). +The program will run in daemon mode ( \fB-d\f1 ), will be visible as "Joe's Stereo" ( \fB-a "Joe's Stereo"\f1 ) and will use the SoX Resampler Library-based stuffing ( \fB-S soxr\f1 ). The audio backend options following the \fB--\f1 separator specify that the audio will be output on output 0 of soundcard 1 ( \fB-d hw:1,0\f1 ) and will take advantage of the same sound card's mixer ( \fB-m hw:1\f1 ) using the level control named "PCM" ( \fB-c "PCM"\f1 ). The example above is slightly contrived in order to show the use of the \fB-m\f1 option. Typically, output 0 is the default output of a card, so the output device could be written \fB-d hw:1\f1 and then the mixer option would be unnecessary, giving the following, simpler, command: -shairport-sync \fB-d\f1 \fB-a "Joe's Stereo"\f1 \fB-S soxr\f1 \fB--\f1 \fB-d hw:1\f1 \fB-t hardware\f1 \fB-c PCM\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. diff --git a/man/shairport-sync.7.xml b/man/shairport-sync.7.xml index 7902324..14c8be6 100644 --- a/man/shairport-sync.7.xml +++ b/man/shairport-sync.7.xml @@ -66,8 +66,7 @@ <description> <p>shairport-sync plays audio streamed from iTunes or from an AirPlay - device to an audio device connected via an audio back end. At present, - the only fully-implemented back end is for ALSA.</p> + device to an ALSA-compatible audio output device.</p> <p> 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 @@ -76,7 +75,9 @@ enabling, for example, simultaneous multi-room operation. </p> - <p>Settings can be made using the configuration file (recommended for all new installations) or the by using command-line options.</p> + <p>shairport-sync can additionally be compiled and configured to stream raw audio to a pipe or to stdout.</p> + + <p>Settings can be made using the configuration file (recommended for all new installations) or by using command-line options.</p> </description> @@ -97,12 +98,11 @@ <p><opt></opt></p> <p><opt>alsa = {</opt></p> <p><p><opt>output_device = "hw:0";</opt></p></p> - <p><p><opt>mixer_type = "hardware";</opt></p></p> <p><p><opt>mixer_control_name = "PCM";</opt></p></p> <p><opt>};</opt></p> <p>Most settings have sensible default values, so -- as in the example above -- users generally only need to set (1) the service name, (2) a password (if desired) and - (3) the output device. If the output device has a hardware mixer that can be used for volume control, then (4) the fact that the output mixer is hardware and (5) the output device mixer's volume-control name should be specificed. It is highly desirable to use the hardware mixer for volume control, if available -- response time is reduced to zero and the processor load is reduced. In the example above, "soxr" interpolation was also enabled.</p> + (3) the output device. If the output device has a mixer that can be used for volume control, then (4) the volume control's name should be specificed. It is highly desirable to use the output device's mixer for volume control, if available -- response time is reduced to zero and the processor load is reduced. In the example above, "soxr" interpolation was also enabled.</p> <p>A sample configuration file with all possible settings, but with all of them commented out, is installed at <file>/etc/shairport-sync.conf.sample</file>.</p> @@ -149,23 +149,23 @@ <option> <p><opt>mdns_backend=</opt><arg>"backend"</arg><opt>;</opt></p> - <optdesc>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 <arg>backend</arg>. The default is "avahi". Perform the command <opt>shairport-sync -h</opt> to get a list of available mDNS modules.</optdesc> + <optdesc>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 <arg>backend</arg>. The default is "avahi". Perform the command <opt>shairport-sync -h</opt> to get a list of available mDNS modules.</optdesc> </option> <option> <p><opt>output_backend=</opt><arg>"backend"</arg><opt>;</opt></p> - <optdesc>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 <arg>backend</arg>. The default is "alsa". Perform the command <opt>shairport-sync -h</opt> to get a list of available audio backends. Only the alsa backend supports synchronisation.</optdesc> + <optdesc>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 <arg>backend</arg>. The default is "alsa". Perform the command <opt>shairport-sync -h</opt> to get a list of available audio backends. Only the alsa backend supports synchronisation.</optdesc> </option> <option> <p><opt>port=</opt><arg>portnumber</arg><opt>;</opt></p> - <optdesc>Use this to specify the <arg>portnumber</arg> Shairport Sync uses to listen for service requests from iTunes, etc. The default is port 5000.</optdesc> + <optdesc>Use this to specify the <arg>portnumber</arg> shairport-sync uses to listen for service requests from iTunes, etc. The default is port 5000.</optdesc> </option> <option> - <p><opt>udp_port_base=</opt><arg>6001</arg><opt>;</opt></p> - <optdesc>When Shairport Sync starts to play audio, it establises three UDP connections to the audio source. Use this setting to specify the starting <arg>portnumber</arg> for these three ports. It will pick the first three unused ports starting from <arg>portnumber</arg>. The default is port 6001.</optdesc> + <p><opt>udp_port_base=</opt><arg>portnumber</arg><opt>;</opt></p> + <optdesc>When shairport-sync starts to play audio, it establises three UDP connections to the audio source. Use this setting to specify the starting <arg>portnumber</arg> for these three ports. It will pick the first three unused ports starting from <arg>portnumber</arg>. The default is port 6001.</optdesc> </option> <option> - <p><opt>udp_port_range=</opt><arg>100</arg><opt>;</opt></p> - <optdesc>Use this in conjunction with the prevous setting to specify the range of ports that can be checked for availability. Only three ports are needed. The default is 100, thus 100 ports will be checked from port 6001 upwards until three are found.</optdesc> + <p><opt>udp_port_range=</opt><arg>range</arg><opt>;</opt></p> + <optdesc>Use this in conjunction with the prevous setting to specify the <arg>range</arg> of ports that can be checked for availability. Only three ports are needed. The default is 100, thus 100 ports will be checked from port 6001 upwards until three are found.</optdesc> </option> <option> <p><opt>drift=</opt><arg>frames</arg><opt>;</opt></p> @@ -177,7 +177,7 @@ </option> <option> <p><opt>resync_threshold=</opt><arg>threshold</arg><opt>;</opt></p> - <optdesc>Resynchronise if timings differ by more than <opt>threshold</opt> frames. + <optdesc>Resynchronise if timings differ by more than <arg>threshold</arg> 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 @@ -215,22 +215,23 @@ </option> <option><p><opt>"METADATA" SETTINGS</opt></p></option> - <p>Shairport Sync can process metadata provided by the source, such as Track Number, Album Name, cover art, etc. and can provide additional metadata such as volume level, + <p>shairport-sync can process metadata provided by the source, such as Track Number, Album Name, cover art, etc. and can provide additional metadata such as volume level, pause/resume, etc. It provides the metadata to a pipe, by default <file>/tmp/shairport-sync-metadata</file>. - To process metadata, Shairport Sync must have been compiled with metadata support included. - You can check tht this is so by running <opt>shairport-sync -V</opt>; the identification string will contain the word <opt>metadata</opt>.</p> + To process metadata, shairport-sync must have been compiled with metadata support included. + You can check that this is so by running <opt>shairport-sync -V</opt>; the identification string will contain the word <opt>metadata</opt>.</p> <p>The <opt>metadata</opt> group of settings allow you to enable metadata handling and to control certain aspects of it:</p> <option> <p><opt>enabled=</opt><arg>"choice"</arg><opt>;</opt></p> - <optdesc>Set the <arg>choice</arg> to "yes" to enable Shairport Sync to look for metadata from the audio source and to forward it, - along with metadata generated by Shairport Sync itself, to the metadata pipe. The default is "no".</optdesc> + <optdesc>Set the <arg>choice</arg> to "yes" to enable shairport-sync to look for metadata from the audio source and to forward it, + along with metadata generated by shairport-sync itself, to the metadata pipe. The default is "no".</optdesc> </option> <option> <p><opt>include_cover_art=</opt><arg>"choice"</arg><opt>;</opt></p> - <optdesc>Set the <arg>choice</arg> to "yes" to enable Shairport Sync to look for cover art from the audio source and to forward it to the metadata pipe. - A reason for not enabling cover art is that the images can sometimes be very large and mey delay transmission of subsequent metadata through the pipe. + <optdesc>Set the <arg>choice</arg> to "yes" to enable shairport-sync to look for cover art from the audio source and to include it in the feed to the metadata pipe. + You must also enable metadata (see above). + One reason for not including cover art is that the images can sometimes be very large and may delay transmission of subsequent metadata through the pipe. The default is "no".</optdesc> </option> <option> @@ -239,7 +240,7 @@ </option> <option><p><opt>"SESSIONCONTROL" SETTINGS</opt></p></option> - <p>Shairport Sync can run programs just before it starts to play an audio stream and just after it finishes. + <p>shairport-sync can run programs just before it starts to play an audio stream and just after it finishes. You specify them using the sessioncontrol group settings run_this_before_play_begins and run_this_after_play_ends. </p> @@ -255,7 +256,7 @@ </option> <option> <p><opt>wait_for_completion=</opt><arg>"choice"</arg><opt>;</opt></p> - <optdesc>Set <arg>choice</arg> to "yes" to make Shairport Sync wait until the programs specified in the <opt>run_this_before_play_begins</opt> + <optdesc>Set <arg>choice</arg> to "yes" to make shairport-sync wait until the programs specified in the <opt>run_this_before_play_begins</opt> and <opt>run_this_after_play_ends</opt> have completed execution before continuing. The default is "no".</optdesc> </option> <option> @@ -271,7 +272,7 @@ </option> <option><p><opt>"ALSA" SETTINGS</opt></p></option> - <p>These settings are for the ALSA back end, used used to communicate with audio output devices in the ALSA system. + <p>These settings are for the ALSA back end, used to communicate with audio output devices in the ALSA system. (By the way, you can use tools such as <opt>alsamixer</opt> or <opt>aplay</opt> 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 <opt>alsa</opt> group settings:</p> @@ -285,7 +286,7 @@ <p><opt>mixer_control_name=</opt><arg>"name"</arg><opt>;</opt></p> <optdesc>Specify the <arg>name</arg> 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, shaiport-sync will control the volume in software.</optdesc> + If you do not specify a mixer control name, shairport-sync will adjust the volume in software.</optdesc> </option> <p><opt>mixer_type=</opt><arg>"mixer_type"</arg><opt>;</opt></p> <optdesc>This setting is deprecated and will be removed soon. If you wish to use a mixer control to control the volume, then set <arg>mixer_type</arg> to "hardware". @@ -293,7 +294,7 @@ </option> <option> <p><opt>mixer_device=</opt><arg>"mixer_device"</arg><opt>;</opt></p> - <optdesc>By default, the mixer is assumed to be output_device is. Use this setting to specify a device other than the output device.</optdesc> + <optdesc>By default, the mixer is assumed to be output_device. Use this setting to specify a device other than the output device.</optdesc> </option> <option> <p><opt>audio_backend_latency_offset=</opt><arg>offset</arg><opt>;</opt></p> @@ -304,8 +305,9 @@ <p><opt>audio_backend_buffer_desired_length=</opt><arg>length</arg><opt>;</opt></p> <optdesc>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 a software mixer become annoying, or it may exceed the hardware buffer size. - It may need to be larger on low-powered machines performing other tasks, such as processing metadata.</optdesc> + 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.</optdesc> </option> <option><p><opt>"PIPE" SETTINGS</opt></p></option> @@ -319,7 +321,7 @@ <option> <p><opt>name=</opt><arg>"/path/to/pipe"</arg><opt>;</opt></p> - <optdesc>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. + <optdesc>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.</optdesc> </option> @@ -338,8 +340,8 @@ 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 <arg>audio_backend_buffer_desired_length</arg> 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 faster or slower than they are supplied, the buffer will empty or overflow eventually -- - Shairport Sync performs no stuffing or interpolation when writing to a pipe. Default setting is 44,100. + 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. </optdesc> </option> @@ -365,8 +367,8 @@ 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 <arg>audio_backend_buffer_desired_length</arg> setting of 44100, send subsequent packets of audio a second before they are due to be played, they will be buffered in the stdout reader's buffer, giving it a nominal buffer size of 44,100 frames. - Note that if the stdout reader consumes audio faster or slower than they are supplied, the buffer will empty or overflow eventually -- - Shairport Sync performs no stuffing or interpolation when writing to stdout. Default setting is 44,100. + Note that if the stdout reader consumes audio packets faster or slower than they are supplied, the buffer will eventually empty or overflow -- + shairport-sync performs no stuffing or interpolation when writing to stdout. Default setting is 44,100 frames. </optdesc> </option> @@ -374,6 +376,10 @@ <options> + <p>Note: if you are setting up shairport-sync for the first time or are updating an existing installation, + you are encouraged to use the configuration file settings described above. Most of the options described below + simply replicate the configuration settings and are retained to provide backward compatability with older installations of shairport-sync.</p> + <p>Many of the options take sensible default values, so you can normally ignore most of them. See the EXAMPLES section for typical usages.</p> @@ -700,11 +706,8 @@ <p><opt>-t </opt><arg>devicetype</arg></p> <optdesc> <p> - The type of the output device is <arg>devicetype</arg> which must be - <opt>hardware</opt> or <opt>software</opt>. The default is <opt>software</opt>. - If you specify <opt>hardware</opt> you must also specify the output device using the - <opt>-d</opt> option and the name of the volume control using the <opt>-c</opt> option. - You may also need to specify the mixer using the <opt>-m</opt> option. + This option is deprecated and is ignored. For your information, its functionality has been automatically incorporated in the -c option + -- if you specify a mixer name with the -c option, it is assumed that the mixer is implemented in hardware. </p></optdesc> </option> </options> @@ -717,7 +720,6 @@ <opt>--</opt> <opt>-d hw:1,0</opt> <opt>-m hw:1</opt> - <opt>-t hardware</opt> <opt>-c PCM</opt> </cmd> <p>The program will run in daemon mode ( <opt>-d</opt> ), will be visible as @@ -725,8 +727,7 @@ Library-based stuffing ( <opt>-S soxr</opt> ). The audio backend options following the <opt>--</opt> separator specify that the audio will be output on output 0 of soundcard 1 ( - <opt>-d hw:1,0</opt> ) and will take advantage of the same sound card's hardware - (<opt>-t hardware</opt>) mixer ( <opt>-m hw:1</opt> ) + <opt>-d hw:1,0</opt> ) and will take advantage of the same sound card's mixer ( <opt>-m hw:1</opt> ) using the level control named "PCM" ( <opt>-c "PCM"</opt> ). </p> <p>The example above is slightly contrived in order to show the use of the <opt>-m</opt> option. @@ -738,7 +739,6 @@ <opt>-S soxr</opt> <opt>--</opt> <opt>-d hw:1</opt> - <opt>-t hardware</opt> <opt>-c PCM</opt> </cmd> diff --git a/man/shairport-sync.html b/man/shairport-sync.html index a936dd5..c587b03 100644 --- a/man/shairport-sync.html +++ b/man/shairport-sync.html @@ -46,8 +46,7 @@ <h2>Description</h2> <p>shairport-sync plays audio streamed from iTunes or from an AirPlay - device to an audio device connected via an audio back end. At present, - the only fully-implemented back end is for ALSA.</p> + device to an ALSA-compatible audio output device.</p> <p> 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 @@ -56,7 +55,9 @@ enabling, for example, simultaneous multi-room operation. </p> - <p>Settings can be made using the configuration file (recommended for all new installations) or the by using command-line options.</p> + <p>shairport-sync can additionally be compiled and configured to stream raw audio to a pipe or to stdout.</p> + + <p>Settings can be made using the configuration file (recommended for all new installations) or by using command-line options.</p> @@ -79,12 +80,11 @@ <p><b></b></p> <p><b>alsa = {</b></p> <p><p><b>output_device = "hw:0";</b></p></p> - <p><p><b>mixer_type = "hardware";</b></p></p> <p><p><b>mixer_control_name = "PCM";</b></p></p> <p><b>};</b></p> <p>Most settings have sensible default values, so -- as in the example above -- users generally only need to set (1) the service name, (2) a password (if desired) and - (3) the output device. If the output device has a hardware mixer that can be used for volume control, then (4) the fact that the output mixer is hardware and (5) the output device mixer's volume-control name should be specificed. It is highly desirable to use the hardware mixer for volume control, if available -- response time is reduced to zero and the processor load is reduced. In the example above, "soxr" interpolation was also enabled.</p> + (3) the output device. If the output device has a mixer that can be used for volume control, then (4) the volume control's name should be specificed. It is highly desirable to use the output device's mixer for volume control, if available -- response time is reduced to zero and the processor load is reduced. In the example above, "soxr" interpolation was also enabled.</p> <p>A sample configuration file with all possible settings, but with all of them commented out, is installed at <em>/etc/shairport-sync.conf.sample</em>.</p> @@ -131,23 +131,23 @@ <p><b>mdns_backend=</b><em>"backend"</em><b>;</b></p> - 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 <em>backend</em>. The default is "avahi". Perform the command <b>shairport-sync -h</b> 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 <em>backend</em>. The default is "avahi". Perform the command <b>shairport-sync -h</b> to get a list of available mDNS modules. <p><b>output_backend=</b><em>"backend"</em><b>;</b></p> - 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 <em>backend</em>. The default is "alsa". Perform the command <b>shairport-sync -h</b> 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 <em>backend</em>. The default is "alsa". Perform the command <b>shairport-sync -h</b> to get a list of available audio backends. Only the alsa backend supports synchronisation. <p><b>port=</b><em>portnumber</em><b>;</b></p> - Use this to specify the <em>portnumber</em> Shairport Sync uses to listen for service requests from iTunes, etc. The default is port 5000. + Use this to specify the <em>portnumber</em> shairport-sync uses to listen for service requests from iTunes, etc. The default is port 5000. - <p><b>udp_port_base=</b><em>6001</em><b>;</b></p> - When Shairport Sync starts to play audio, it establises three UDP connections to the audio source. Use this setting to specify the starting <em>portnumber</em> for these three ports. It will pick the first three unused ports starting from <em>portnumber</em>. The default is port 6001. + <p><b>udp_port_base=</b><em>portnumber</em><b>;</b></p> + When shairport-sync starts to play audio, it establises three UDP connections to the audio source. Use this setting to specify the starting <em>portnumber</em> for these three ports. It will pick the first three unused ports starting from <em>portnumber</em>. The default is port 6001. - <p><b>udp_port_range=</b><em>100</em><b>;</b></p> - Use this in conjunction with the prevous setting to specify the range of ports that can be checked for availability. Only three ports are needed. The default is 100, thus 100 ports will be checked from port 6001 upwards until three are found. + <p><b>udp_port_range=</b><em>range</em><b>;</b></p> + Use this in conjunction with the prevous setting to specify the <em>range</em> of ports that can be checked for availability. Only three ports are needed. The default is 100, thus 100 ports will be checked from port 6001 upwards until three are found. <p><b>drift=</b><em>frames</em><b>;</b></p> @@ -159,7 +159,7 @@ <p><b>resync_threshold=</b><em>threshold</em><b>;</b></p> - Resynchronise if timings differ by more than <b>threshold</b> frames. + Resynchronise if timings differ by more than <em>threshold</em> 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 @@ -197,22 +197,23 @@ <p><b>"METADATA" SETTINGS</b></p> - <p>Shairport Sync can process metadata provided by the source, such as Track Number, Album Name, cover art, etc. and can provide additional metadata such as volume level, + <p>shairport-sync can process metadata provided by the source, such as Track Number, Album Name, cover art, etc. and can provide additional metadata such as volume level, pause/resume, etc. It provides the metadata to a pipe, by default <em>/tmp/shairport-sync-metadata</em>. - To process metadata, Shairport Sync must have been compiled with metadata support included. - You can check tht this is so by running <b>shairport-sync -V</b>; the identification string will contain the word <b>metadata</b>.</p> + To process metadata, shairport-sync must have been compiled with metadata support included. + You can check that this is so by running <b>shairport-sync -V</b>; the identification string will contain the word <b>metadata</b>.</p> <p>The <b>metadata</b> group of settings allow you to enable metadata handling and to control certain aspects of it:</p> <p><b>enabled=</b><em>"choice"</em><b>;</b></p> - Set the <em>choice</em> to "yes" to enable Shairport Sync to look for metadata from the audio source and to forward it, - along with metadata generated by Shairport Sync itself, to the metadata pipe. The default is "no". + Set the <em>choice</em> to "yes" to enable shairport-sync to look for metadata from the audio source and to forward it, + along with metadata generated by shairport-sync itself, to the metadata pipe. The default is "no". <p><b>include_cover_art=</b><em>"choice"</em><b>;</b></p> - Set the <em>choice</em> to "yes" to enable Shairport Sync to look for cover art from the audio source and to forward it to the metadata pipe. - A reason for not enabling cover art is that the images can sometimes be very large and mey delay transmission of subsequent metadata through the pipe. + Set the <em>choice</em> to "yes" to enable shairport-sync to look for cover art from the audio source and to include it in the feed to the metadata pipe. + You must also enable metadata (see above). + One reason for not including cover art is that the images can sometimes be very large and may delay transmission of subsequent metadata through the pipe. The default is "no". @@ -221,7 +222,7 @@ <p><b>"SESSIONCONTROL" SETTINGS</b></p> - <p>Shairport Sync can run programs just before it starts to play an audio stream and just after it finishes. + <p>shairport-sync can run programs just before it starts to play an audio stream and just after it finishes. You specify them using the sessioncontrol group settings run_this_before_play_begins and run_this_after_play_ends. </p> @@ -237,7 +238,7 @@ <p><b>wait_for_completion=</b><em>"choice"</em><b>;</b></p> - Set <em>choice</em> to "yes" to make Shairport Sync wait until the programs specified in the <b>run_this_before_play_begins</b> + Set <em>choice</em> to "yes" to make shairport-sync wait until the programs specified in the <b>run_this_before_play_begins</b> and <b>run_this_after_play_ends</b> have completed execution before continuing. The default is "no". @@ -253,7 +254,7 @@ <p><b>"ALSA" SETTINGS</b></p> - <p>These settings are for the ALSA back end, used used to communicate with audio output devices in the ALSA system. + <p>These settings are for the ALSA back end, used to communicate with audio output devices in the ALSA system. (By the way, you can use tools such as <b>alsamixer</b> or <b>aplay</b> to discover what devices are available.) 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 <b>alsa</b> group settings:</p> @@ -267,7 +268,7 @@ <p><b>mixer_control_name=</b><em>"name"</em><b>;</b></p> Specify the <em>name</em> 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, shaiport-sync will control the volume in software. + If you do not specify a mixer control name, shairport-sync will adjust the volume in software. <p><b>mixer_type=</b><em>"mixer_type"</em><b>;</b></p> This setting is deprecated and will be removed soon. If you wish to use a mixer control to control the volume, then set <em>mixer_type</em> to "hardware". @@ -275,7 +276,7 @@ <p><b>mixer_device=</b><em>"mixer_device"</em><b>;</b></p> - By default, the mixer is assumed to be output_device is. Use this setting to specify a device other than the output device. + By default, the mixer is assumed to be output_device. Use this setting to specify a device other than the output device. <p><b>audio_backend_latency_offset=</b><em>offset</em><b>;</b></p> @@ -286,8 +287,9 @@ <p><b>audio_backend_buffer_desired_length=</b><em>length</em><b>;</b></p> 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 a software mixer become annoying, or it may exceed the hardware buffer size. - It may need to be larger on low-powered machines performing other tasks, such as processing metadata. + 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. <p><b>"PIPE" SETTINGS</b></p> @@ -301,7 +303,7 @@ <p><b>name=</b><em>"/path/to/pipe"</em><b>;</b></p> - 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. @@ -320,8 +322,8 @@ 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 <em>audio_backend_buffer_desired_length</em> 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 faster or slower than they are supplied, the buffer will empty or overflow eventually -- - Shairport Sync performs no stuffing or interpolation when writing to a pipe. Default setting is 44,100. + 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. @@ -347,8 +349,8 @@ 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 <em>audio_backend_buffer_desired_length</em> setting of 44100, send subsequent packets of audio a second before they are due to be played, they will be buffered in the stdout reader's buffer, giving it a nominal buffer size of 44,100 frames. - Note that if the stdout reader consumes audio faster or slower than they are supplied, the buffer will empty or overflow eventually -- - Shairport Sync performs no stuffing or interpolation when writing to stdout. Default setting is 44,100. + Note that if the stdout reader consumes audio packets faster or slower than they are supplied, the buffer will eventually empty or overflow -- + shairport-sync performs no stuffing or interpolation when writing to stdout. Default setting is 44,100 frames. @@ -358,6 +360,10 @@ <h2>Options</h2> + <p>Note: if you are setting up shairport-sync for the first time or are updating an existing installation, + you are encouraged to use the configuration file settings described above. Most of the options described below + simply replicate the configuration settings and are retained to provide backward compatability with older installations of shairport-sync.</p> + <p>Many of the options take sensible default values, so you can normally ignore most of them. See the EXAMPLES section for typical usages.</p> @@ -688,11 +694,8 @@ <p><b>-t </b><em>devicetype</em></p> <p> - The type of the output device is <em>devicetype</em> which must be - <b>hardware</b> or <b>software</b>. The default is <b>software</b>. - If you specify <b>hardware</b> you must also specify the output device using the - <b>-d</b> option and the name of the volume control using the <b>-c</b> option. - You may also need to specify the mixer using the <b>-m</b> option. + This option is deprecated and is ignored. For your information, its functionality has been automatically incorporated in the -c option + -- if you specify a mixer name with the -c option, it is assumed that the mixer is implemented in hardware. </p> @@ -706,7 +709,6 @@ <b>--</b> <b>-d hw:1,0</b> <b>-m hw:1</b> - <b>-t hardware</b> <b>-c PCM</b> <br> @@ -715,8 +717,7 @@ Library-based stuffing ( <b>-S soxr</b> ). The audio backend options following the <b>--</b> separator specify that the audio will be output on output 0 of soundcard 1 ( - <b>-d hw:1,0</b> ) and will take advantage of the same sound card's hardware - (<b>-t hardware</b>) mixer ( <b>-m hw:1</b> ) + <b>-d hw:1,0</b> ) and will take advantage of the same sound card's mixer ( <b>-m hw:1</b> ) using the level control named "PCM" ( <b>-c "PCM"</b> ). </p> <p>The example above is slightly contrived in order to show the use of the <b>-m</b> option. @@ -728,7 +729,6 @@ <b>-S soxr</b> <b>--</b> <b>-d hw:1</b> - <b>-t hardware</b> <b>-c PCM</b> <br> |