Merge branch 'master' into next
[paraslash.git] / ggo / audiod.m4
1 include(header.m4)
2 define(CURRENT_PROGRAM,para_audiod)
3 define(DEFAULT_CONFIG_FILE,~/.paraslash/audiod.conf)
4
5 <qu>
6 #########################
7 section "General options"
8 #########################
9 </qu>
10
11 include(loglevel.m4)
12 include(color.m4)
13 include(config_file.m4)
14 include(logfile.m4)
15 include(daemon.m4)
16 include(user.m4)
17 include(group.m4)
18
19 <qu>
20 ########################
21 section "Audiod options"
22 ########################
23
24 option "force" F
25 #~~~~~~~~~~~~~~~
26 "force startup"
27 flag off
28 details="
29 If this flag is not given, para_audiod refuses to start if the
30 well-known socket file (see the --socket option) already exists
31 because this usually means that para_audiod is already running
32 and listening on that socket. After a crash or if para_audiod
33 received a SIGKILL signal, a stale socket file might remain and
34 you have to use --force once to force startup of para_audiod.
35 "
36
37 option "mode" m
38 #~~~~~~~~~~~~~~
39 "startup mode"
40 string typestr="mode"
41 default="on"
42 optional
43 details="
44 Para_audiod supports three modes of operation: On, off and
45 standby (sb). This option selects the mode that should be
46 used on startup. If para_audiod operates in \"on\" mode, it
47 will connect to para_server in order to receive its status
48 information. If para_server announces the availability of an
49 audio stream, para_audiod will automatically download, decode
50 and play the audio stream according to the given stream I/O
51 options, see below.
52
53 In \"standby\" mode, para_audiod will only receive the
54 status information from para_server but will not download
55 the audio stream.
56
57 In \"off\" mode, para_audiod does not connect para_server at
58 all, but still listens on the local socket for connections.
59 "
60
61 option "socket" s
62 #~~~~~~~~~~~~~~~~
63 "well-known socket"
64 string typestr="filename"
65 optional
66 details="
67 Para_audiod uses a \"well-known\" socket to listen
68 on for connections from para_audioc. This socket is a
69 special file in the file system; its location defaults to
70 /var/paraslash/audiod_sock.<host_name>.
71
72 para_audioc, the client program used to connect to para_audiod,
73 opens this socket in order to talk to para_audiod. If the
74 default value for para_audiod is changed, para_audioc must be
75 instructed to use also \"filename\" for connecting para_audiod.
76 "
77
78 option "user_allow" -
79 #~~~~~~~~~~~~~~~~~~~~
80 "allow this uid"
81 int typestr="uid"
82 default="-1"
83 optional
84 multiple
85 details="
86 Allow the user identified by \"uid\" to connect to para_audiod.
87 May be specified multiple times. If not specified at all,
88 all users are allowed to connect.
89
90 This feature requires unix socket credentials and is currently
91 only supported on Linux systems. On other operating systems,
92 the option is silently ignored and all local users are allowed
93 to connect to para_audiod.
94 "
95
96 option "clock_diff_count" -
97 #~~~~~~~~~~~~~~~~~~~~~~~~~~
98 "sync clock on startup"
99 int typestr="count"
100 default="0"
101 optional
102 details="
103 Check the clock difference between the host running para_server
104 and the local host running para_audiod that many times before
105 starting any stream I/0. Set this to non-zero for non-local
106 setups if the clocks of these two hosts are not syncronized
107 by ntp or similar.
108 "
109
110 #############################
111 section "Stream I/O options"
112 #############################
113
114 option "receiver" r
115 #~~~~~~~~~~~~~~~~~~
116 "select receiver"
117 string typestr="receiver_spec"
118 default="http"
119 optional
120 multiple
121 details="
122 This option may be given multiple times, once for each
123 supported audio format. The \"receiver_spec\" consists of
124 an audio format and the receiver name, separated by a colon,
125 and any options for that receiver, seperated by whitespace.
126 If any receiver options are present, the whole receiver
127 argument must be quoted.
128
129 Example:
130
131 -r 'mp3:http -i my.host.org -p 8009'
132 "
133
134 option "no_default_filters" D
135 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~
136 "Configure filters manually"
137 flag off
138 details="
139 If (and only if) this option is set, the --filter options
140 (see below) take effect. Otherwise, the compiled-in default
141 filters mp3dec, oggdec and aacdec are activated for mp3, ogg,
142 aac streams respectively.
143
144 You have to configure filters manually if you want to use
145 the amp filter or the compress filter which are not activated
146 by default.
147
148 Playing udp streams also requires manual filter configuration
149 because the output of the udp receiver must be fed into the
150 fecdec filter first to produce a stream which can be decoded
151 by the appropriate decoder (mp3dec, oggdec, aacdec). In other
152 words, the fecdec filter must be specified as the first filter
153 of the filter chain for any udp stream.
154 "
155
156 option "filter" f
157 #~~~~~~~~~~~~~~~~
158 "Use non-default filters"
159 string typestr="filter_spec"
160 optional
161 multiple
162 dependon="no_default_filters"
163 details="
164 This option may be given multiple times. The \"filter_spec\"
165 consists of an audio format, the name of the filter, and any
166 options for that filter. Note that order matters.
167
168 Examples:
169
170 --filter 'mp3:mp3dec'
171
172 --filter 'mp3:compress --inertia 5 --damp 2'
173
174 "
175
176 option "writer" w
177 #~~~~~~~~~~~~~~~~
178 "Specify stream writer."
179 string typestr="writer_spec"
180 optional
181 multiple
182 details="
183 May be given multiple times, even multiple times for the same
184 audio format. Default value is \"alsa\" for all supported
185 audio formats. Example:
186
187 --writer 'aac:osx'
188
189 "
190
191 option "stream_delay" -
192 #~~~~~~~~~~~~~~~~~~~~~~
193 "time for client sync"
194 int typestr="milliseconds"
195 default="200"
196 optional
197 details="
198 Add the given amount of milliseconds to the stream start time
199 announced by para_server and do not send data to the writer
200 before that time (modulo clock difference).
201
202 This is useful mainly for syncronizing the audio output of
203 different clients.
204 "
205 </qu>