m4/lls/audiod.suite.m4

   1 m4_define(PROGRAM, para_audiod)
   2 m4_define(DEFAULT_CONFIG_FILE, ~/.paraslash/audiod.conf)
   3 [suite audiod]
   4 version-string = GIT_VERSION()
   5 [supercommand para_audiod]
   6         purpose = connect to para_server, receive, decode and play audio streams
   7         [description]
   8                 para_audiod runs on a host with an audio device and connects
   9                 para_server to obtain status information and receive the current audio
  10                 stream. The stream is transformed through any number of filters and
  11                 then written to the configured output device.
  12
  13                 Moreover, para_audiod listens on a local socket and sends status
  14                 information to local clients on request. Access to the local socket
  15                 can be restricted by means of Unix socket credentials, if available.
  16         [/description]
  17         m4_include(common-option-section.m4)
  18         m4_include(help.m4)
  19         m4_include(detailed-help.m4)
  20         m4_include(version.m4)
  21         m4_include(config-file.m4)
  22         m4_include(loglevel.m4)
  23         m4_include(logfile.m4)
  24         m4_include(color.m4)
  25         m4_include(log-timing.m4)
  26         m4_include(daemon.m4)
  27         m4_include(user.m4)
  28         m4_include(group.m4)
  29         m4_include(priority.m4)
  30         m4_include(per-command-options-section.m4)
  31         [option force]
  32                 summary = force startup
  33                 short_opt = F
  34                 [help]
  35                         If this flag is not given, para_audiod refuses to start if the
  36                         well-known socket file (see the --socket option) already exists
  37                         because this usually means that para_audiod is already running and
  38                         listening on that socket. After a crash or if para_audiod received
  39                         a SIGKILL signal, a stale socket file might remain and you have to
  40                         use --force once to force startup of para_audiod.
  41                 [/help]
  42         [option mode]
  43                 summary = select startup mode
  44                 arg_info = required_arg
  45                 arg_type = string
  46                 typestr = mode
  47                 values = {AUDIOD_ON = "on", AUDIOD_OFF = "off",  AUDIOD_STANDBY = "sb"}
  48                 default_val = on
  49                 [help]
  50                         para_audiod supports three modes of operation: On, off and standby
  51                         (sb).  This option selects the mode that should be used at startup. If
  52                         mode is "on", para_audiiod connects para_server to receive status
  53                         information. If the server announces the availability of an audio
  54                         stream, para_audiod downloads, decodes and plays the audio stream
  55                         according to the given stream I/O options, see below.
  56
  57                         In "standby" mode, para_audiod only receives the status information
  58                         from para_server but does not download the audio stream.
  59
  60                         In "off" mode, para_audiod does not connect para_server at all,
  61                         but still listens on the local socket.
  62                 [/help]
  63         [option socket]
  64                 short_opt = s
  65                 summary = path to the well-known socket
  66                 arg_info = required_arg
  67                 arg_type = string
  68                 typestr = path
  69                 [help]
  70                         para_audiod listens on a "well-known" socket for connections
  71                         from para_audioc. This socket is a special file in the file system;
  72                         its location defaults to /var/paraslash/audiod_sock.$hostname.
  73
  74                         para_audioc, the client program used to connect to para_audiod,
  75                         opens this socket in order to talk to para_audiod. If the default
  76                         value for para_audiod is changed, para_audioc must be instructed to
  77                         use also <path> to connect para_audiod.
  78                 [/help]
  79         [option user-allow]
  80                 summary = allow this user to connect to audiod
  81                 arg_info = required_arg
  82                 arg_type = string
  83                 typestr = username
  84                 [help]
  85                         Allow the user identified by username (either a string or a UID) to
  86                         connect to para_audiod. This option may be given multiple times. If
  87                         not specified at all, all users are allowed to connect.
  88
  89                         This feature is based on the ability to send unix credentials through
  90                         local sockets using ancillary data (SCM_CREDENTIALS). Currently it
  91                         only works on Linux. On other operating systems the option is silently
  92                         ignored and all local users are allowed to connect.
  93                 [/help]
  94         [option clock-diff-count]
  95                 summary = sync clock on startup
  96                 arg_info = required_arg
  97                 arg_type = uint32
  98                 typestr = count
  99                 [help]
 100                         Check the clock difference between the host running para_server and
 101                         the local host running para_audiod this many times before starting
 102                         any stream I/0. Set this to non-zero for non-local setups if the
 103                         clocks of these two hosts are not synchronized by ntp or similar.
 104                 [/help]
 105         [option Stream-IO-options]
 106                 summary = Stream I/O options
 107                 flag ignored
 108         [option receiver]
 109                 short_opt = r
 110                 summary = select receiver
 111                 arg_info = required_arg
 112                 arg_type = string
 113                 typestr = receiver_spec
 114                 default_val = http
 115                 flag multiple
 116                 [help]
 117                         This option may be given multiple times, for each audio format
 118                         separately. If multiple definitions for an audio format are given,
 119                         the first one is selected.
 120
 121                         The <receiver_spec> consists of an audio format specifier and one or
 122                         more receiver arguments, separated by a colon.
 123
 124                         The audio format specifier is a regular expression which specifies
 125                         the set of audio formats for which this option should apply.
 126
 127                         If any receiver options are present, the whole receiver argument must
 128                         be quoted:
 129
 130                                 -r 'mp3:http -i my.host.org -p 8009'
 131
 132                         Since a single dot '.' matches the name of any audio format, specifying
 133                         '.' instead of 'mp3' above activates the http receiver for all audio
 134                         formats.
 135                 [/help]
 136         [option filter]
 137                 short_opt = f
 138                 summary = specify the filter configuration
 139                 arg_info = required_arg
 140                 arg_type = string
 141                 typestr = filter_spec
 142                 flag multiple
 143                 [help]
 144                         This option may be given multiple times. The <filter_spec< consists
 145                         of an audio format specifier (see above), the name of the filter,
 146                         and any options for that filter. Note that order matters.
 147
 148                         The compiled-in defaults apply to all audio formats for which no
 149                         --filter option was given. These defaults depend on the receiver
 150                         being used.
 151
 152                         For HTTP streams, only the decoder for the current audio format
 153                         is activated. UDP and DCCP streams, on the other hand, are sent
 154                         FEC-encoded by para_server. In order to play such streams, the
 155                         receiver output must be FEC-decoded first, i.e. fed to the fecdec
 156                         filter. Therefore the default for UDP and DCCP streams is to activate
 157                         the fecdec filter, followed by the decoding filter for the audio
 158                         format.
 159
 160                         Examples:
 161
 162                                 --filter 'mp3:mp3dec'
 163
 164                                 --filter 'mp3|aac:compress --inertia 5 --damp 2'
 165
 166                                 --filter '.:fecdec'
 167                 [/help]
 168         [option writer]
 169                 short_opt = w
 170                 summary = specify one or more stream writers
 171                 arg_info = required_arg
 172                 arg_type = string
 173                 typestr = writer_spec
 174                 flag multiple
 175                 [help]
 176                         May be given multiple times, even multiple times for the same audio
 177                         format. The default is to use the first supported writer. Example:
 178
 179                                 --writer 'aac|wma:oss'
 180                 [/help]
 181         [option stream-delay]
 182                 summary = specify time interval for client sync
 183                 arg_info = required_arg
 184                 arg_type = uint32
 185                 typestr = count
 186                 [help]
 187                         Check the clock difference between the host running para_server and
 188                         the local host running para_audiod this many times before starting
 189                         any stream I/0. Set this to non-zero for non-local setups if the
 190                         clocks of these two hosts are not synchronized by ntp or similar.
 191                 [/help]