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