Debian Codegraph @

doc/config.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
5 <title>IceS v2.0 Documentation</title>
6 <link rel="STYLESHEET" type="text/css" href="style.css">
7 </head>
8 <body>
9 <div class=boxtest>
10 <h1>Config File</h1>
11 <table width="100%"><tr><td bgcolor="#007B79" height="10" align="center"></td></tr></table>
12 <p>The ices 2 configuration file is in XML format, which is described in detail below.
13 There are some sample XML files provided in the distribution under the conf directory
14 which show the main way ices is used.<p>
15 </p>
16 live audio streaming, takes audio from the soundcard which can be captured from say the
17 Mic, line-In, CD or a combination of these.
18 <ul>
19 <li>ices-oss.xml</li>
20 <li>ices-alsa.xml</li>
21 <li>ices-roar.xml</li>
22 </ul>
23 <p>Playlist audio streaming, takes pre-encoded Ogg Vorbis files and either sends them
24 as-is or re-encodes them to different settings</p>
25 <ul>
26 <li>ices-playlist.xml</li>
27 </ul>
28 <h2>General layout</h2>
29 <pre>
30 &lt;?xml version="1.0"?&gt;
31 &lt;ices&gt;
32 general settings
33 stream section
34 &lt;/ices&gt;
35 </pre>
36 <h2>General settings</h2>
37 <p>These apply to IceS as a whole. The example below gives a useful example to work to</p>
38 <pre>
39 &lt;background&gt;0&lt;/background&gt;
40 &lt;logpath&gt;/var/log/ices&lt;/logpath&gt;
41 &lt;logfile&gt;ices.log&lt;/logfile&gt;
42 &lt;logsize&gt;2048&lt;/logsize&gt;
43 &lt;loglevel&gt;3&lt;/loglevel&gt;
44 &lt;consolelog&gt;0&lt;/consolelog&gt;
45 &lt;pidfile&gt;/var/log/ices/ices.pid&lt;/pidfile&gt;
46 </pre>
47 <h4>background</h4>
48 <div class=indentedbox>
49 Set to 1 if you want IceS to put itself into the background.
50 </div>
51 <h4>logpath</h4>
52 <div class=indentedbox>
53 A directory that can be written to by the user that IceS runs as. This
54 can be anywhere you want but as log files are created, write access to the
55 stated must be given.
56 </div>
57 <h4>logfile</h4>
58 <div class=indentedbox>
59 The name of the logfile created. On log re-opening the existing logfile is
60 renamed to &lt;logfile&gt;.1
61 </div>
62 <h4>logsize</h4>
63 <div class=indentedbox>
64 When the log file reaches this size (in kilobytes) then the log file will
65 be cycled (the default is 2Meg)
66 </div>
67 <h4>loglevel</h4>
68 <div class=indentedbox>
69 A number that represents the amount of logging performed.
70 <ul>
71 <li>1 - Only error messages are logged
72 <li>2 - The above and warning messages are logged
73 <li>3 - The above and information messages are logged
74 <li>4 - The above and debug messages are logged
75 </ul>
76 </div>
77 <h4>consolelog</h4>
78 <div class=indentedbox>
79 A value of 1 will cause the log messages to appear on the console instead
80 of the log files. Setting this to 1 is generally discouraged as logs are
81 cycled and writing to screen can cause stalls in the application, which
82 is a problem for timing critical applications.
83 </div>
84 <h4>pidfile</h4>
85 <div class=indentedbox>
86 State a filename with path to be created at start time. This file will
87 then contain a single number which represents the process id of the
88 running IceS. This process id can then be used to signal the application
89 of certain events.
90 </div>
91 <h2>Stream section</h2>
92 <p>This describes how the input and outgoing streams are configured.<p>
93 <pre>
94 &lt;stream&gt;
95 Metadata
96 Input
97 Instance
98 &lt;/stream&gt;
99 </pre>
100
101 <h3>Metadata</h3>
102 <pre>
103 &lt;metadata&gt;
104 &lt;name&gt;My Stream&lt;/name&gt;
105 &lt;genre&gt;Rock&lt;/genre&gt;
106 &lt;description&gt;A short description of your stream&lt;/description&gt;
107 &lt;url&gt;http://mysite.org&lt;/url&gt;
108 &lt;/metadata&gt;
109 </pre>
110 <p>
111 This section describes what metadata information is passed in the headers
112 at connection time to icecast. This applies to each instance defined within
113 the stream section but maybe overridden by a per-instance &lt;metadata&gt;
114 section.
115 </p>
116 <h3>Input</h3>
117 <p>
118 This section deals with getting the audio data into IceS. There are a few
119 ways that can happen. Typically it's either from a playlist or via a soundcard.
120 </p>
121 <p>
122 The layout is consistent between the different input modules. Within the
123 input section a module tag is needed to identify the module in question. The
124 rest are made up of param tags specific to the module. There can be several
125 param tags supplied to a module. Details of the module parameters are
126 shown later.
127 </p>
128 <h3>Instance</h3>
129 <p>
130 Multiple instances can be defined to allow for multiple encodings, this
131 is useful for encoding the same input to multiple bitrates. Each instance
132 defines a particular set actions that occur on the passed in audio. Any
133 modifications to the input data is isolated to the instance.
134 </p>
135 <pre>
136 &lt;instance&gt;
137 hostname
138 port
139 password
140 mount
141 tls-mode
142 ca-directory
143 ca-file
144 allowed-ciphers
145 client-certificate
146 yp
147 resample
148 downmix
149 savefile
150 encode
151 &lt;/instance&gt;
152 </pre>
153 <h4>hostname</h4>
154 <div class=indentedbox>
155 State the hostname of the icecast to contact, this can be a name or IP
156 address and can be IPv4 or IPv6 on systems that support IPv6. The default
157 is localhost.
158 </div>
159 <h4>port</h4>
160 <div class=indentedbox>
161 State the port to connect to, this will be the port icecast is listening on,
162 typically 8000 but can be any.
163 </div>
164 <h4>password</h4>
165 <div class=indentedbox>
166 For providing a stream, a username/password has to be provided, and must
167 match what icecast expects.
168 </div>
169 <h4>username</h4>
170 <div class=indentedbox>
171 For providing a stream, a username/password has to be provided, and must
172 match what icecast expects. Default is "source".
173 </div>
174 <h4>mount</h4>
175 <div class=indentedbox>
176 Mountpoints are used to identify a particular stream on a icecast server,
177 they must begin with / and for the sake of certain listening clients should
178 end with the .ogg extension.
179 </div>
180 <h4>tls-mode</h4>
181 <div class=indentedbox>
182 Controls if the server should use a encrypted and authenticated connection
183 to the Icecast server. Supported modes are "auto" (default mode) in which
184 TLS is used if supported by the server, "auto_no_plain" in which TLS is forced
185 but modes supported by the server is still autodetected, "RFC2818" which uses
186 TLS sockets and "RFC2817" to use the HTTP "Upgrade:" mechanism.
187 <b>This requires TLS support compiled into libshout.</b>
188 </div>
189 <h4>ca-directory</h4>
190 <div class=indentedbox>
191 This sets the directory holding certificates of certification authorities used
192 to verify the server. Default is to use operating system's defaults.
193 <b>This requires TLS support compiled into libshout.</b>
194 </div>
195 <h4>ca-file</h4>
196 <div class=indentedbox>
197 In contrast to the ca-directory option this allows to set a single file with
198 certificate(s) used to verify the server. You can use this option to pass IceS
199 the certificate if you are using a self-signed one on the server also.
200 Default is to use operating system's defaults.
201 <b>This requires TLS support compiled into libshout.</b>
202 </div>
203 <h4>allowed-ciphers</h4>
204 <div class=indentedbox>
205 For encrypted and authenticated connections this controls what ciphers may be used.
206 Do not set this option if you do not really know what you are doing. This can easily
207 break setup and security.
208 <b>This requires TLS support compiled into libshout.</b>
209 </div>
210 <h4>client-certificate</h4>
211 <div class=indentedbox>
212 On a TLS connection the client can authenticate to the server using a certificate.
213 This option allows to set such an certificate. This is a file in PEM format
214 containing both the certificate as well as the private key.
215 <b>This requires TLS support compiled into libshout.</b>
216 </div>
217 <h4>yp</h4>
218 <div class=indentedbox>
219 By default streams will not be advertised on a YP server unless this is set,
220 and only then if the icecast if configured to talk to YP servers.
221 </div>
222 <h4>reconnectdelay</h4>
223 <div class=indentedbox>
224 If the connection to the server is lost ices2 will wait a given time before reconnecting.
225 This setting controls how long ices2 will wait before reconnecting.
226 The value is the time in seconds.
227 </div>
228 <h4>reconnectattempts</h4>
229 <div class=indentedbox>
230 This setting controls the number of reconnet attempts ices2 will do before considering
231 the server to be down and stopping the instance.
232 </div>
233 <h4>retry-initial</h4>
234 <div class=indentedbox>
235 This setting controls if being unabled to connect to the server at startup is considered a fatal error.
236 The default is to consider this a fatal error and quit making debugging more easy.
237 </div>
238 <h4>Resample</h4>
239 <pre>
240 &lt;resample&gt;
241 &lt;in-rate&gt;44100&lt;/in-rate&gt;
242 &lt;out-rate&gt;22050&lt;/out-rate&gt;
243 &lt;/resample&gt;
244 </pre>
245 <div class=indentedbox>
246 <p>
247 When encoding or re-encoding, there is a point where you take PCM audio
248 and encode to Ogg Vorbis. In some situations a particular encoded stream may
249 require a lower samplerate to achieve a lower bitrate. The resample will
250 modify the audio data before it enters the encoder, but does not affect
251 other instances.
252 </p>
253 <p>
254 The most common values used are 48000, 44100, 22050 and 11025, and is
255 really only used to resample to a lower samplerate, going to a higher rate
256 serves no purpose within IceS.
257 </p>
258 </div>
259 <h4>Downmix</h4>
260 <pre>
261 &lt;downmix&gt;1&lt;/downmix&gt;
262 </pre>
263 <div class=indentedbox>
264 Some streams want to reduce the bitrate further, reducing the number of channels
265 used to just 1. Converting stereo to mono is fairly common and when this is set
266 to 1 the number of channels encoded is just 1. Like resample, this only affects
267 the one instance it's enabled in.
268 </div>
269 <h4>Savefile</h4>
270 <pre>
271 &lt;savefile&gt;/home/ices/dump/stream1.ogg&lt;/savefile&gt;
272 </pre>
273 <div class=indentedbox>
274 Sometimes the stream transmitted wants to be saved to disk. This can be useful
275 for live recordings.
276 </div>
277 <h4>encode</h4>
278 <pre>
279 &lt;encode&gt;
280 &lt;quality&gt;0&lt;/quality&gt;
281 &lt;nominal-bitrate&gt;65536&lt;/nominal-bitrate&gt;
282 &lt;maximum-bitrate&gt;131072&lt;/maximum-bitrate&gt;
283 &lt;minimum-bitrate&gt;-1&lt;/minimum-bitrate&gt;
284 &lt;managed&gt;0&lt;/managed&gt;
285 &lt;samplerate&gt;22050&lt;/samplerate&gt;
286 &lt;channels&gt;1&lt;/channels&gt;
287 &lt;flush-samples&gt;11000&lt;/flush-samples&gt;
288 &lt;/encode&gt;
289 </pre>
290 <p>
291 Remove this section if you don't want your files reencoded when
292 using playback or RoarAudio input module.
293 </p>
294
295 <p>quality</p>
296 <div class=indentedbox>
297 State a quality measure for the encoder. The range goes from -1 to 10 where -1
298 is the lowest bitrate selection (default 3), and decimals can also be stated, so
299 for example 1.5 is valid. The actual bitrate used will depend on the tuning in
300 the vorbis libs, the samplerate, channels and the audio to encode. A quality of 0
301 at 44100hz and 2 channels is typically around the 64kbps mark.
302 </div>
303 <p>nominal-bitrate</p>
304 <div class=indentedbox>
305 State a bitrate that the encoder should try to keep to. This can be used as an
306 alternative to selecting quality.
307 </div>
308 <p>managed</p>
309 <div class=indentedbox>
310 State 1 to enable full bitrate management in the encoder. This is used with
311 nominal-bitrate, maximum-bitrate and minimum-bitrate to produce a stream with
312 more strict bitrate requirements. Enabling this currently leads to higher CPU
313 usage.
314 </div>
315 <p>maximum-bitrate</p>
316 <div class=indentedbox>
317 State bitrate in bits per second to limit max bandwidth used on a stream. Only
318 applies if managed is enabled.
319 </div>
320 <p>minimum-bitrate</p>
321 <div class=indentedbox>
322 State bitrate in bits per second to limit minimum bandwidth used on a stream.
323 Only applies if managed is enabled, this option has very little use so
324 should not really be needed.
325 </div>
326 <p>samplerate</p>
327 <div class=indentedbox>
328 State the samplerate used for the encoding, this should be either the same as
329 the input or the result of the resample. Getting the samplerate wrong will
330 cause the audio to be represented wrong and therefore sound like it's running
331 too fast or too slow.
332 </div>
333 <p>channels</p>
334 <div class=indentedbox>
335 State the number of channels to use in the encoding. This will either be the
336 number of channels from the input or 1 if downmix is enabled.
337 </div>
338 <p>flush-samples</p>
339 <div class=indentedbox>
340 This is the trigger level at which Ogg pages are created for sending to the server.
341 Depending on the bitrate and compression achieved a single Ogg page can contain many
342 seconds of audio which may not be wanted as that can trigger timeouts.
343 <p>Setting this to the same value as the encode samplerate will mean that a page per
344 second is sent, if a value that is half of the encoded samplerate is specified then
345 2 Ogg pages per second are sent.</p>
346 </div>
347 </div>
348 </body>
349 </html>
350