Make mp3_seek_next_header() more readable.
[paraslash.git] / server.ggo
index 4f6e05b..012e104 100644 (file)
+#########################
 section "General options"
-#~~~~~~~~~~~~~~~~~~~~~~~~
+#########################
 
 option "loglevel" l
 #~~~~~~~~~~~~~~~~~~
-
-"set loglevel (0-6)"
-
-       int typestr="level"
-       default="4"
-       optional
+"set loglevel (1-6)"
+int typestr="level"
+default="4"
+optional
+details="
+       Larger values mean less verbose output. Loglevel 1 (debug) gets
+       really noisy; a value of 2 (info) produces still noisy output,
+       but this won't fill up the disk quicky. Messaged logged with
+       loglevel 3 (notice) indicate normal but significant events
+       while level 4 (warning) logs unexpected events that can be
+       handled. Unhandled error conditions are logged with loglevel
+       5 (error) and crititcal errors are logged using loglevel 6
+       (crit).  Finally, loglevel 7 (emerg) is reserved for messages
+       that cause para_server to terminate immediately.
+"
 
 option "port" p
 #~~~~~~~~~~~~~~
-
 "listening port"
-
-       int typestr="portnumber"
-       default="2990"
-       optional
+int typestr="portnumber"
+default="2990"
+optional
+details="
+       para_server listens on this tcp port for incoming connections
+       from clients such as para_client. If the default port is
+       changed, the corresponding option of para_client must be used
+       to connect to para_server.
+"
 
 option "daemon" d
 #~~~~~~~~~~~~~~~~
-
 "run as background daemon"
-
-       flag off
+flag off
+dependon="logfile"
+details="
+       Note that para_server refuses to start in daemon mode if no
+       logfile was specified.
+"
 
 option "user" u
 #~~~~~~~~~~~~~~
-
-"run as user 'name'. para_server does not
-need any special privileges. If started as
-root (EUID == 0) this option must be given at
-the command line (not in the configuration
-file) so that para_server can drop the root
-privileges right after parsing the command
-line options, but before parsing the
-configuration file. In this case,
-real/effective/saved UID are all set to the
-UID of 'name'. As the configuration file
-is read afterwards, those options that have a
-default value depending on the UID (e.g. the
-directory for the configuration file) are
-computed by using the uid of 'name'.
-This option has no effect if para_server is
-started as a non-root user (i.e.  EUID != 0)"
-
-       string typestr="name"
-       optional
+"run as the given user"
+string typestr="name"
+optional
+details="
+       para_server does not need any special privileges. If started
+       as root (EUID == 0) this option must be given at the command
+       line (not in the configuration file) so that para_server
+       can drop the root privileges right after parsing the command
+       line options, but before parsing the configuration file. In
+       this case, real/effective/saved UID are all set to the UID
+       of 'name'. As the configuration file is read afterwards,
+       those options that have a default value depending on the UID
+       (e.g. the directory for the configuration file) are computed
+       by using the uid of 'name'.  This option has no effect if
+       para_server is started as a non-root user (i.e.  EUID != 0)
+"
 
 
 option "group" g
 #~~~~~~~~~~~~~~~
-
-"set group id to according to 'group'. This
-option is silently ignored if EUID != 0.
-Otherwise, real/effective GID and the saved
-set-group ID are all set to the GID given by
-'group'. Must not be given in the config file."
-
-       string typestr="group"
-       optional
-
-
-
+"set group id"
+string typestr="group"
+optional
+details="
+       This option sets the group id according to 'group'. This option
+       is silently ignored if EUID != 0. Otherwise, real/effective
+       GID and the saved set-group ID are all set to the GID given by
+       'group'. Must not be given in the config file.
+"
+
+#############################
 section "Configuration files"
-#~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#############################
 
 
 option "logfile" L
 #~~~~~~~~~~~~~~~~~
-
-"(default=stdout/stderr)"
-
-       string typestr="filename"
-       optional
+"where to write log output"
+string typestr="filename"
+optional
+details="
+       If this option is not given, para_server writes the log
+       messages to to stderr
+"
 
 option "config_file" c
 #~~~~~~~~~~~~~~~~~~~~~
-
 "(default='~/.paraslash/server.conf'"
-
-       string typestr="filename"
-       optional
+string typestr="filename"
+optional
+details="
+       para_server reads its config file right after parsing
+       the options that were given at the command line. If an
+       option is given both at the command line and in the
+       config file, the value that was specified at the command line
+       takes precedence.
+"
 
 option "user_list" -
 #~~~~~~~~~~~~~~~~~~~
-
 "(default='~/.paraslash/server.users')"
 
-       string typestr="filename"
-       optional
-
+string typestr="filename"
+optional
 
 
+##################################
 section "virtual streaming system"
-#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+##################################
 
 
 option "autoplay" a
 #~~~~~~~~~~~~~~~~~~
-
 "start playing on startup"
-
-       flag off
+flag off
 
 option "autoplay_delay" -
 #~~~~~~~~~~~~~~~~~~~~~~~~
-"Time to wait before autoplay starts. Ignored if
-autoplay is off."
-       int typestr="milliseconds"
-       default="0"
-       optional
-
-
+"time to wait before streaming"
+int typestr="ms"
+default="0"
+optional
+dependon="autoplay"
+details="
+       If para_server is started with the autoplay option, this option
+       may be used to set up a delay before para_server streams its
+       first audio file. This is useful for example if para_server
+       and para_audiod are started during system startup. The delay
+       time should be choosen large enough so that para_audiod is
+       already up when para_server starts to stream. Of course, this
+       option depends on the autoplay option.
+"
 option "announce_time" A
 #~~~~~~~~~~~~~~~~~~~~~~~
-
-"Delay betweeen announcing the stream and sending data"
-
-       int typestr="milliseconds"
-       default="300"
-       optional
-
-
-option "selector" S
-#~~~~~~~~~~~~~~~~~~
-
-"(default=random)"
-
-       string typestr="name"
-       optional
-
-
-
-section "mysql selector"
-#~~~~~~~~~~~~~~~~~~~~~~~
-
-
-option "mysql_host" -
-#~~~~~~~~~~~~~~~~~~~~
-
-"mysql server"
-
-       string typestr="ip or hostname"
-       default="localhost"
-       optional
-
-option "mysql_port" -
-#~~~~~~~~~~~~~~~~~~~~
-
-"where mysql is listening"
-
-       int typestr="portnumber"
-       default="3306"
-       optional
-
-
-option "mysql_user" -
-#~~~~~~~~~~~~~~~~~~~~
-
-"default value: username from /etc/passwd"
-
-       string typestr="username"
-       optional
-
-option "mysql_passwd" -
-#~~~~~~~~~~~~~~~~~~~~~~
-
-"(required)"
-
-       string
-       optional
-
-option "mysql_database" -
-#~~~~~~~~~~~~~~~~~~~~~~~~
-
-"name of mysql database"
-
-       string
-       default="paraslash"
-       optional
-
-option "mysql_audio_file_dir"  -
-#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-"dir to search for audio files (required)"
-
-       string typestr="dirname"
-       optional
-
-option "mysql_default_score" -
-#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-"scoring rule to use if stream definition
-does not contain explicit score definition"
-
-       string
-       default="(LASTPLAYED() / 1440 - 1000 / (LASTPLAYED() + 1) - sqrt(NUMPLAYED()))"
-       optional
-
-
-
-
-section "random selector"
-#~~~~~~~~~~~~~~~~~~~~~~~~
-
-
-option "random_dir" -
+"grace time for clients"
+
+int typestr="ms"
+default="300"
+optional
+details="
+       Clients such as para_audiod connect to para_server and execute
+       the stat command to find out whether an audio stream is
+       currently available. This sets the delay betweeen announcing
+       the stream via the output of the stat command and sending
+       the first chunk of data.
+"
+
+#############################
+section "audio file selector"
+#############################
+
+option "afs_database_dir" D
+#~~~~~~~~~~~~~~~~~~~~~~~~~~
+"location of the database"
+string typestr="path"
+optional
+details="
+       Where para_server should look for the  osl
+       database of the audio file selector. The default is
+       '~/.paraslash/afs_database'.
+"
+
+option "afs_socket" s
 #~~~~~~~~~~~~~~~~~~~~
+"Command socket for afs"
+string typestr="path"
+default="/var/paraslash/afs_command_socket"
+optional
+details="
+       For each server command that is handled by the audio file
+       selector, the child process of para_server connects to the
+       audio file selector via a local socket. This option specifies
+       the location of that socket in the file system.
+"
+option "afs_initial_mode" i
+#~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-"dir to search for audio files"
-       string typestr="dirname"
-       default="/home/music"
-       optional
-
-
+"Mood or playlist to load on startup."
+string typestr="<specifier>/<name>"
+optional
 
+details="
+       The argument of this option must be prefixed with either 'p/'
+       or 'm/' to indicate whether a playlist or a mood should be
+       loaded. Example:
+               --afs_initial_mode p/foo
+       loads the playlist named 'foo'.
+"
 
+#####################
 section "http sender"
-#~~~~~~~~~~~~~~~~~~~~
+#####################
 
 
 option "http_port" -
 #~~~~~~~~~~~~~~~~~~~
-
 "tcp port for http streaming"
-
-       int typestr="portnumber"
-       default="8000"
-       optional
+int typestr="portnumber"
+default="8000"
+optional
+details="
+       The http sender of para_server listens on this port for
+       incoming connections. Clients are expected to send the usual
+       http request message such as 'GET / HTTP/'.
+"
 
 option "http_default_deny" -
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-"deny connections from hosts which are not
-explicitly allowed"
-
-       flag off
+"make the http ACL a whitelist"
+flag off
+details="
+       The default is to use blacklists instead, i.e. connections
+       to the http sender are allowed unless the connecting host
+       matches a pattern given by a http_access option. This allows
+       to use access control the other way round: Connections are
+       denied from hosts which are not explicitly allowed by one or
+       more http_access options.
+"
 
 option "http_access" -
 #~~~~~~~~~~~~~~~~~~~~~
-
-"Add given host/network to access control
-list (whitelist if http_default_deny was
-given, blacklist otherwise) before opening
-the tcp port. This option can be given
-multiple times. Example: '192.168.0.0/24'
-whitelists/blacklists the 256 hosts
-192.168.0.x"
-
-       string typestr="a.b.c.d/n"
-       optional
-       multiple
+"add an entry to the http ACL"
+string typestr="a.b.c.d/n"
+optional
+multiple
+details="
+       Add given host/network to access control list (whitelist if
+       http_default_deny was given, blacklist otherwise) before
+       opening the tcp port. This option can be given multiple
+       times. Example: '192.168.0.0/24' whitelists/blacklists the
+       256 hosts 192.168.0.x
+"
 
 option "http_no_autostart" -
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-"do not open tcp port on server startup"
-
-       flag off
+"do not open tcp port on startup"
+flag off
+details="
+       If this option is given, the http sender does not listen on
+       its tcp port. It may be instructed to open this port at a
+       later time by using the sender command.
+"
 
 option "http_max_clients" -
 #~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-"maximal simultaneous connections,
-non-positive value means unlimited"
-
-       int typestr="number"
-       default="-1"
-       optional
-
-
-
-
+"maximal number of connections"
+int typestr="number"
+default="-1"
+optional
+details="
+       The http sender will refuse connections if already that number
+       of clients are currently connected. A non-positive value
+       (the default) allows an unlimited number of simultaneous
+       connections.
+"
+
+#####################
 section "dccp sender"
-#~~~~~~~~~~~~~~~~~~~~
+#####################
 
 
 option "dccp_port" -
 #~~~~~~~~~~~~~~~~~~~
-
 "port for dccp streaming"
+int typestr="portnumber"
+default="8000"
+optional
+details="
+       See http_port for details.
+"
+
+option "dccp_default_deny" -
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"make the dccp ACL a whitelist"
+flag off
+details="
+       See http_default_deny for details.
+"
 
-       int typestr="portnumber"
-       default="5001"
-       optional
-
-
-
-
+option "dccp_access" -
+#~~~~~~~~~~~~~~~~~~~~~
+"add an entry to the dccp ACL"
+string typestr="a.b.c.d/n"
+optional
+multiple
+details="
+       See http_access for details.
+"
+
+option "dccp_max_clients" -
+#~~~~~~~~~~~~~~~~~~~~~~~~~~
+"maximal number of connections"
+int typestr="number"
+default="-1"
+optional
+details="
+       See http_max_clients for details.
+"
+
+#####################
 section "ortp sender"
-#~~~~~~~~~~~~~~~~~~~~
+#####################
 
 option "ortp_target" -
 #~~~~~~~~~~~~~~~~~~~~~
-
-"Add given host/port to the list of targets.
-This option can be given multiple times.
-Example: '224.0.1.38:1500' instructs the ortp
-sender to send to udp port 1500 on host
-224.0.1.38 (unassigned ip in the Local
-Network Control Block 224.0.0/24). This is
-useful for LAN-streaming."
-
-       string typestr="a.b.c.d:p"
-       optional
-       multiple
+"add ortp target"
+string typestr="a.b.c.d:p"
+optional
+multiple
+details="
+       Add given host/port to the list of targets.  This option
+       can be given multiple times.  Example: '224.0.1.38:1500'
+       instructs the ortp sender to send to udp port 1500 on host
+       224.0.1.38 (unassigned ip in the Local Network Control Block
+       224.0.0/24). This is useful for LAN-streaming.
+"
 
 option "ortp_no_autostart" -
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-"do not start to send automatically"
-
-       flag off
+"do not start sending"
+flag off
+details="
+       If this option is given, ortp streaming may be activated at
+       a later time by using the sender command.
+"
 
 option "ortp_default_port" -
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-"default udp port if not specified"
-
-       int typestr="portnumber"
-       default="1500"
-       optional
+"udp port to send to"
+int typestr="port"
+default="1500"
+optional
 
 option "ortp_header_interval" H
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-"time between extra header sends"
-
-       int typestr="milliseconds"
-       default="2000"
-       optional
+"duration for sending header"
+int typestr="ms"
+default="2000"
+optional
+details="
+       As the ortp sender has no idea about connected clients it
+       sends the audio file header periodically if necessary. This
+       option is used to specify the duration of the interval between
+       sending the header. Shorter values decrease the average time
+       clients have to wait before being able to start playback,
+       but this also increases the amount network traffic. Note
+       that this affects only ogg vorbis streams as this is the only
+       audio format that needs an audio file header.
+"
 
 option "ortp_jitter_compensation" j
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-"non-zero values enable ortp's adaptive
-jitter compensation"
-
-       int typestr="milliseconds"
-       default="400"
-       optional
+"configure jitter compensation"
+int typestr="ms"
+default="400"
+optional
+details="
+       ortp's adaptive jitter compensation gets activated whenever
+       this value is greater than zero. See the ortp documentation
+       about details on this feature.
+"