write: Improve help text of --writer.
[paraslash.git] / m4 / gengetopt / audiod.m4
1 args "--no-handle-help --no-handle-version --conf-parser"
2
3 purpose "Connect to para_server, receive, decode and play audio streams"
4
5 include(header.m4)
6 define(CURRENT_PROGRAM,para_audiod)
7 define(DEFAULT_CONFIG_FILE,~/.paraslash/audiod.conf)
8
9 <qu>
10 #########################
11 section "General options"
12 #########################
13 </qu>
14
15 include(loglevel.m4)
16 include(color.m4)
17 include(config_file.m4)
18 include(logfile.m4)
19 include(log_timing.m4)
20 include(daemon.m4)
21 include(user.m4)
22 include(group.m4)
23 include(priority.m4)
24
25 <qu>
26 ########################
27 section "Audiod options"
28 ########################
29
30 option "force" F
31 #~~~~~~~~~~~~~~~
32 "force startup"
33 flag off
34 details="
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
38 and listening on that socket. After a crash or if para_audiod
39 received a SIGKILL signal, a stale socket file might remain and
40 you have to use --force once to force startup of para_audiod.
41 "
42
43 option "mode" m
44 #~~~~~~~~~~~~~~
45 "startup mode"
46 string typestr="mode"
47 default="on"
48 optional
49 details="
50 Para_audiod supports three modes of operation: On, off and
51 standby (sb). This option selects the mode that should be
52 used on startup. If para_audiod operates in \"on\" mode, it
53 will connect to para_server in order to receive its status
54 information. If para_server announces the availability of an
55 audio stream, para_audiod will automatically download, decode
56 and play the audio stream according to the given stream I/O
57 options, see below.
58
59 In \"standby\" mode, para_audiod will only receive the
60 status information from para_server but will not download
61 the audio stream.
62
63 In \"off\" mode, para_audiod does not connect para_server at
64 all, but still listens on the local socket for connections.
65 "
66
67 option "socket" s
68 #~~~~~~~~~~~~~~~~
69 "well-known socket"
70 string typestr="filename"
71 optional
72 details="
73 Para_audiod uses a \"well-known\" socket to listen
74 on for connections from para_audioc. This socket is a
75 special file in the file system; its location defaults to
76 /var/paraslash/audiod_sock.<host_name>.
77
78 para_audioc, the client program used to connect to para_audiod,
79 opens this socket in order to talk to para_audiod. If the
80 default value for para_audiod is changed, para_audioc must be
81 instructed to use also \"filename\" for connecting para_audiod.
82 "
83
84 option "user-allow" -
85 #~~~~~~~~~~~~~~~~~~~~
86 "allow this user to connect to audiod"
87 string typestr = "username"
88 optional
89 multiple
90 details = "
91 Allow the user identified by username (either a string or
92 a UID) to connect to para_audiod. This option may be given
93 multiple times. If not specified at all, all users are allowed
94 to connect.
95
96 This feature is based on the ability to send unix
97 credentials through local sockets using ancillary data
98 (SCM_CREDENTIALS). Currently it only works on Linux. On
99 other operating systems the option is silently ignored and
100 all local users are allowed to connect.
101 "
102
103 option "clock-diff-count" -
104 #~~~~~~~~~~~~~~~~~~~~~~~~~~
105 "sync clock on startup"
106 int typestr="count"
107 default="0"
108 optional
109 details="
110 Check the clock difference between the host running para_server
111 and the local host running para_audiod that many times before
112 starting any stream I/0. Set this to non-zero for non-local
113 setups if the clocks of these two hosts are not synchronized
114 by ntp or similar.
115 "
116
117 #############################
118 section "Stream I/O options"
119 #############################
120
121 option "receiver" r
122 #~~~~~~~~~~~~~~~~~~
123 "select receiver"
124 string typestr="receiver_spec"
125 default="http"
126 optional
127 multiple
128 details="
129 This option may be given multiple times, for each audio format
130 separately. If multiple definitions for an audio format are
131 given, the first one is selected.
132
133 The \"receiver_spec\" consists of an audio format specifier
134 and one or more receiver arguments, separated by a colon.
135
136 The audio format specifier is a regular expression which
137 specifies the set of audio formats for which this option
138 should apply.
139
140 If any receiver options are present, the whole receiver
141 argument must be quoted:
142
143 -r 'mp3:http -i my.host.org -p 8009'
144
145 Since a single dot '.' matches the name of any audio format,
146 specifying '.' instead of 'mp3' above activates the http
147 receiver for all audio formats.
148
149 "
150
151 option "filter" f
152 #~~~~~~~~~~~~~~~~
153 "Specify the filter configuration."
154 string typestr = "filter_spec"
155 optional
156 multiple
157 details = "
158 This option may be given multiple times. The \"filter_spec\"
159 consists of an audio format specifier (see above), the name
160 of the filter, and any options for that filter. Note that
161 order matters.
162
163 The compiled-in defaults apply to all audio formats for which
164 no --filter option was given. These defaults depend on the
165 receiver being used.
166
167 For HTTP streams, only the decoder for the current audio
168 format is activated. UDP and DCCP streams, on the other
169 hand, are sent FEC-encoded by para_server. In order to play
170 such streams, the receiver output must be FEC-decoded first,
171 i.e. fed to the fecdec filter. Therefore the default for UDP
172 and DCCP streams is to activate the fecdec filter, followed
173 by the decoding filter for the audio format.
174
175 Examples:
176
177 --filter 'mp3:mp3dec'
178
179 --filter 'mp3|aac:compress --inertia 5 --damp 2'
180
181 --filter '.:fecdec'
182
183 "
184
185 option "writer" w
186 #~~~~~~~~~~~~~~~~
187 "Specify stream writer."
188 string typestr="writer_spec"
189 optional
190 multiple
191 details="
192 May be given multiple times, even multiple times for the same
193 audio format. Default value is \"alsa\" for all supported
194 audio formats. Example:
195
196 --writer 'aac|wma:oss'
197
198 "
199
200 option "stream-delay" -
201 #~~~~~~~~~~~~~~~~~~~~~~
202 "time for client sync"
203 int typestr="milliseconds"
204 default="200"
205 optional
206 details="
207 Add the given amount of milliseconds to the stream start time
208 announced by para_server and do not send data to the writer
209 before that time (modulo clock difference).
210
211 This is useful mainly for synchronizing the audio output of
212 different clients.
213 "
214 </qu>