[NET]: Bug-fix for getaddrinfo()
[paraslash.git] / audiod.ggo
index b0b8d0c..41af85e 100644 (file)
-section "general options"
-option "user" u "run as user 'name'. Read the output of 'para_server -h' for a detailed information on this option." string typestr="name" no
-option "loglevel" l "set loglevel (0-6)" int typestr="level" default="4" no
-option "daemon" d "run as background daemon" flag off
-option "force" F "force startup even if socket exits" flag off
-option "logfile" L "(default=stdout/stderr)" string typestr="filename" no
-option "mode" m "mode to use on startup (on/off/sb)" string typestr="mode" default="on" no
-option "socket" s "well-known socket to listen on (default=/var/paraslash/audiod_sock.<host_name>)" string typestr="filename" no
+#########################
+section "General options"
+#########################
 
-option "user_allow" -
-
-"allow this user to connect to para_audiod.
-May be specified multiple times. If not
-specified at all, allow all users to
-connect."
-
-int typestr="uid" default="-1" no multiple
-
-section "stream i/o options."
-
-#################
+text "
+       These options are identical to their counterparts in para_server
+       and are discussed in detail there.
+"
 
-option "receiver" r "Select receiver.
+option "loglevel" l
+#~~~~~~~~~~~~~~~~~~
+"set loglevel (1-6)"
+int typestr="level"
+default="4"
+optional
+
+option "logfile" L
+#~~~~~~~~~~~~~~~~~
+"where to write log output"
+string typestr="filename"
+optional
+
+option "daemon" d
+#~~~~~~~~~~~~~~~~
+"run as background daemon"
+flag off
+dependon="logfile"
+
+option "user" u
+#~~~~~~~~~~~~~~
+"run as the given user"
+string typestr="name"
+optional
+
+option "group" g
+#~~~~~~~~~~~~~~~
+"set group id"
+string typestr="group"
+optional
+
+########################
+section "Audiod options"
+########################
+
+option "force" F
+#~~~~~~~~~~~~~~~
+"force startup"
+flag off
+details="
+       If this flag is not given, para_audiod refuses to start if the
+       well-known socket file (see the --socket option) already exists
+       because this usually means that para_audiod is already running
+       and listening on that socket. After a crash or if para_audiod
+       received a SIGKILL signal, a stale socket file might remain and
+       you have to use --force once to force startup of para_audiod.
+"
 
-May be given multiple times, once for each
-supported audio format. receiver_spec
-consists of an audio format and the receiver
-name, separated by a colon, and any options
-for that receiver, seperated by whitespace.
-If any receiver options are present, the
-whole receiver argument must be quoted.
+option "mode" m
+#~~~~~~~~~~~~~~
+"startup mode"
+string typestr="mode"
+default="on"
+optional
+details="
+       Para_audiod supports three modes of operation: On, off and
+       standby (sb).  This option selects the mode that should be
+       used on startup. If para_audiod operates in \"on\" mode, it
+       will connect to para_server in order to receive its status
+       information. If para_server announces the availability of an
+       audio stream, para_audiod will automatically download, decode
+       and play the audio stream according to the given stream I/O
+       options, see below.
+
+       In \"standby\" mode, para_audiod will only receive the
+       status information from para_server but will not download
+       the audio stream.
+
+       In \"off\" mode, para_audiod does not connect para_server at
+       all, but still listens on the local socket for connections.
+"
 
-Example:
+option "socket" s
+#~~~~~~~~~~~~~~~~
+"well-known socket"
+string typestr="filename"
+optional
+details="
+       Para_audiod uses a \"well-known\" socket to listen
+       on for connections from para_audioc. This socket is a
+       special file in the file system; its location defaults to
+       /var/paraslash/audiod_sock.<host_name>.
+
+       para_audioc, the client program used to connect to para_audiod,
+       opens this socket in order to talk to para_audiod.  If the
+       default value for para_audiod is changed, para_audioc must be
+       instructed to use also \"filename\" for connecting para_audiod.
+"
 
--r 'mp3:http -i www.paraslash.org -p 8009'
+option "user_allow" -
+#~~~~~~~~~~~~~~~~~~~~
+"allow thus uid"
+int typestr="uid"
+default="-1"
+optional
+multiple
+details="
+       Allow the user identified by \"uid\" to connect to para_audiod.
+       May be specified multiple times. If not specified at all,
+       all users are allowed to connect.
+
+       This feature requires unix socket credentials and is currently
+       only supported on Linux systems. On other operating systems,
+       the option is silently ignored and all local users are allowed
+       to connect to para_audiod.
 "
 
-string typestr="receiver_spec" default="http" no multiple
+option "clock_diff_count" -
+#~~~~~~~~~~~~~~~~~~~~~~~~~~
+"sync clock on startup"
+int typestr="count"
+default="0"
+optional
+details="
+       Check the clock difference between the host running para_server
+       and the local host running para_audiod that many times before
+       starting any stream I/0. Set this to non-zero for non-local
+       setups if the clocks of these two hosts are not syncronized
+       by ntp or similar.
+"
 
-#################
-option "no_default_filters" D "Configure filters manually.
+#############################
+section "Stream I/O options"
+#############################
+
+option "receiver" r
+#~~~~~~~~~~~~~~~~~~
+"select receiver"
+string typestr="receiver_spec"
+default="http"
+optional
+multiple
+details="
+       This option may be given multiple times, once for each
+       supported audio format. The \"receiver_spec\" consists of
+       an audio format and the receiver name, separated by a colon,
+       and any options for that receiver, seperated by whitespace.
+       If any receiver options are present, the whole receiver
+       argument must be quoted.
+
+       Example:
+
+               -r 'mp3:http -i my.host.org -p 8009'
+"
 
-If (and only if) this option is set, the
---filter options take effect.  Otherwise, the
-compiled-in default filters mp3dec (oggdec)
-and wav are activated for mp3 (ogg) streams."
 
+option "no_default_filters" D
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"Configure filters manually"
 flag off
-#################
-
-option "filter" f "Select filter(s) manually.
-
-May be given multiple times. filter_spec
-consists of an audio format, the name of the
-filter, and any options for that filter.
-
-Examples:
-       -f mp3:mp3dec
-       -f 'mp3:compress --anticlip --volume 2'
+details="
+       If (and only if) this option is set, the --filter options
+       (see below) take effect.  Otherwise, the compiled-in default
+       filters mp3dec, oggdec and aacdec are activated for mp3, ogg,
+       aac streams respectively.
+"
 
-Note that these options are ignored by default,
-see --no_default_filters."
+option "filter" f
+#~~~~~~~~~~~~~~~~
+"Use non-default filters"
+string typestr="filter_spec"
+optional
+multiple
+dependon="no_default_filters"
+details="
+       This option may be given multiple times. The \"filter_spec\"
+       consists of an audio format, the name of the filter, and any
+       options for that filter. Mote that order matters.
 
-string typestr="filter_spec" no multiple
+       Examples:
 
-#################
+               --filter 'mp3:mp3dec'
 
-option "stream_write_cmd" w
+               --filter 'mp3:compress --inertia 5 --damp 2'
 
-"Specify stream writer.
+"
 
-May be given multiple times, once for each
-supported audio format. Default value is
-'para_play' for both mp3 and ogg. You can use
-the START_TIME() macro for these commands.
-Each occurence of START_TIME() gets replaced
-at runtime by the stream start time announced
-by para_server, plus any offsets."
+option "writer" w
+#~~~~~~~~~~~~~~~~
+"Specify stream writer."
+string typestr="writer_spec"
+optional
+multiple
+details="
+       May be given multiple times, even multiple times for the same
+       audio format.  Default value is \"alsa\" for all supported
+       audio formats. Example:
 
-string typestr="format:command" no multiple
+               --writer 'aac:osx'
 
-#################
+"
 
 option "stream_delay" -
-
-"Time to add to para_server's start_time.
-
-Amount of time to be added to the server
-stream start time for stream_write_cmd if
-START_TIME() was given. Useful for
-syncronizing the audio output of clients."
-
-int typestr="milliseconds" default="200" no
-
-#################
-
-option "stream_timeout" -
-
-"Deactivate slot if idle for that many seconds"
-
-int typestr="seconds" default="30" no
+#~~~~~~~~~~~~~~~~~~~~~~
+"time for client sync"
+int typestr="milliseconds"
+default="200"
+optional
+details="
+       Add the given amount of milliseconds to the stream start time
+       announced by para_server and do not send data to the writer
+       before that time (modulo clock difference).
+
+       This is useful mainly for syncronizing the audio output of
+       different clients.
+"