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