Remove mixer_type stuff and edit and reorganise settings and comments

diff --git a/scripts/shairport-sync.conf b/scripts/shairport-sync.conf
index 3bfcde5bdd75b610b673373d7f191cc6b9c7dbcf..b2ac51a59e4b4dd600e814562022056023d7b5be 100644 (file)
--- a/scripts/shairport-sync.conf
+++ b/scripts/shairport-sync.conf
@@ -5,74 +5,73 @@
 general =
 {
 //     name = "Shairport Sync Player"; // This is the name the service will advertise to iTunes. The default is "Shairport Sync on <hostname>"
-//     mdns_backend = "avahi"; // not used, not tested
-//     output_backend = "alsa"; // alsa is default, other possibilities are "stdout", "pulse", "dummy". Only alsa supports synchronisation.
-//     port = 5000;
-//     udp_port_base = 6001; // start allocation UDP ports from this port number
+//     password = "secret"; // comment out this line if you want to have no password
+//     interpolation = "basic"; // aka "stuffing". Default is "basic", alternative is "soxr". Use "soxr" only if you have a reasonably fast processor.
+//     output_backend = "alsa"; // Run "shairport-sync -h" to get a list of all output_backends, e.g. "alsa", "pipe", "stdout". The default is the first one.
+//     mdns_backend = "avahi"; // Run "shairport-sync -h" to get a list of all mdns_backends. The default is the first one.
+//     port = 5000; // Listen for service requests on this port
+//     udp_port_base = 6001; // start allocating UDP ports from this port number when needed
 //     udp_port_range = 100; // look for free ports in this number of places, starting at the UDP port base (only three are needed).
-//     password = "secret"; // default is no password
-//     interpolation = "basic"; // aka "stuffing". Default is "basic", alternative is "soxr"
-//     statistics = "no"; // print statistics in the log
-//     drift = 88; // allow this number of frames of drift before correcting it
+//     statistics = "no"; // set to "yes" to print statistics in the log
+//     drift = 88; // allow this number of frames of drift away from exact synchronisation before attempting to correct it
 //     resync_threshold = 2205; // a synchronisation error greater than this will cause resynchronisation; 0 disables it
-//     log_verbosity = 0; // "0" means no verbosity, "3" is most verbose.
+//     log_verbosity = 0; // "0" means no debug verbosity, "3" is most verbose.
 //  ignore_volume_control = "no"; // set this to "yes" if you want the volume to be at 100% no matter what the source's volume control is set to.
 };
 
-// Latencies for different sources.
+// Latencies for different sources. These have been estimated from listening tests.
+// It's probably better to compensate for a delay in the output device using the alsa "audio_backend_latency_offset" setting -- see below.
 latencies =
 {
-//     default = 88200;
-//     itunes = 99400;
+//     default = 88200; // used for unrecognised sources and for iTunes up to and including iTunes 9.X.
+//     itunes = 99400; // used for iTunes 10 or later
 //     airplay = 88200;
 //     forkedDaapd = 99400;
 };
 
-
 // How to deal with metadata, including artwork
 metadata =
 {
-//     enabled = "no";
-//     include_cover_art = "no";
+//     enabled = "no"; // et to yes to get Shairport Sync to solicit metadata from the source and to pass it on via a pipe
+//     include_cover_art = "no"; // set to "yes" to get Shairport Sync to solicit cover art from the source and pass it via the pipe. You must also set "enabled" to "yes".
 //     pipe_name = "/tmp/shairport-sync-metadata";
 };
 
 // Advanced parameters for controlling how a Shairport Sync runs
 sessioncontrol = 
 {
-//     run_this_before_play_begins = "/path/to/application and args";
-//     run_this_after_play_ends = "/path/to/application and args";
-//     wait_for_completion = "no";
-//     allow_session_interruption = "no";
-//     session_timeout = 120;
+//     run_this_before_play_begins = "/full/path/to/application and args"; // make sure the application has executable permission. It it's a script, include the #!... stuff on the first line
+//     run_this_after_play_ends = "/full/path/to/application and args"; // make sure the application has executable permission. It it's a script, include the #!... stuff on the first line
+//     wait_for_completion = "no"; // set to "yes" to get Shairport Sync to wait until the "run_this..." applications have terminated before continuing
+//     allow_session_interruption = "no"; // set to "yes" to allow another device to interrupt Shairport Sync while it's playing from an existing audio source
+//     session_timeout = 120; // wait for this number of seconds after a source disappears before terminating the session and becoming available again.
 };
 
 //
 // Back End Settings
 //
 
-// These are parameters for the alsa back end, the only back end that supports synchronisation
+// These are parameters for the "alsa" audio back end, the only back end that supports synchronised audio.
 alsa =
 {
-//  output_device = "default";
-//  mixer_type = "software"; // "software" or "hardware"
-//  mixer_device = "default"; //actually, the mixer default is whatever the output_device is. Normally you wouldn't have to use this.
-//  mixer_control_name = "PCM"; // the name of the mixer to use -- there is no default.
+//  output_device = "default"; // the name of the alsa output device. Use "alsamixer" or "aplay" to find out the names of devices, mixers, etc.
+//  mixer_control_name = "PCM"; // the name of the mixer to use to adjust output volume. If not specified, volume in adjusted in software.
+//  mixer_device = "default"; // the mixer_device default is whatever the output_device is. Normally you wouldn't have to use this.
 //  audio_backend_latency_offset = 0; // Set this offset to compensate for a fixed delay in the audio back end. E.g. if the output device delays by 100 ms, set this to -4410.
 //  audio_backend_buffer_desired_length = 6615; // If set too small, buffer underflow occurs on low-powered machines. Too long and the response times with software mixer become annoying.
 };
 
-// These are parameters for the pipe back end, an experimental back end that directs output to a pipe.
+// These are parameters for the "pipe" audio back end, a back end that directs raw CD-style audio output to a pipe. No interpolation is done.
 pipe =
 {
-//  audio_backend_latency_offset = 0; // Set this offset to compensate for a fixed delay in the audio back end. E.g. if the output device delays by 100 ms, set this to -4410.
-//  audio_backend_buffer_desired_length = 44100;
 //  name = "/path/to/pipe"; // there is no default pipe name for the output
+//  audio_backend_latency_offset = 0; // Set this offset to compensate for a fixed delay in the audio back end. E.g. if the output device delays by 100 ms, set this to -4410.
+//  audio_backend_buffer_desired_length = 44100; // Having started to send audio at the right time, send all subsequent audio this many frames ahead of time, creating a buffer this size.
 };
 
-// These are parameters for the stdout audio back end, an experimental back end that directs output to stdout.
+// These are parameters for the "stdout" audio back end, a back end that directs raw CD-style audio output to stdout. No interpolation is done.
 stdout =
 {
 //  audio_backend_latency_offset = 0; // Set this offset to compensate for a fixed delay in the audio back end. E.g. if the output device delays by 100 ms, set this to -4410.
-//  audio_backend_buffer_desired_length = 44100;
+//  audio_backend_buffer_desired_length = 44100; // Having started to send audio at the right time, send all subsequent audio this many frames ahead of time, creating a buffer this size.
 };