| 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 |
<?xml version="1.0"?> |
| 31 |
<ices> |
| 32 |
general settings |
| 33 |
stream section |
| 34 |
</ices> |
| 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 |
<background>0</background> |
| 40 |
<logpath>/var/log/ices</logpath> |
| 41 |
<logfile>ices.log</logfile> |
| 42 |
<logsize>2048</logsize> |
| 43 |
<loglevel>3</loglevel> |
| 44 |
<consolelog>0</consolelog> |
| 45 |
<pidfile>/var/log/ices/ices.pid</pidfile> |
| 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 <logfile>.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 |
<stream> |
| 95 |
Metadata |
| 96 |
Input |
| 97 |
Instance |
| 98 |
</stream> |
| 99 |
</pre> |
| 100 |
|
| 101 |
<h3>Metadata</h3> |
| 102 |
<pre> |
| 103 |
<metadata> |
| 104 |
<name>My Stream</name> |
| 105 |
<genre>Rock</genre> |
| 106 |
<description>A short description of your stream</description> |
| 107 |
<url>http://mysite.org</url> |
| 108 |
</metadata> |
| 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 <metadata> |
| 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 |
<instance> |
| 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 |
</instance> |
| 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 |
<resample> |
| 241 |
<in-rate>44100</in-rate> |
| 242 |
<out-rate>22050</out-rate> |
| 243 |
</resample> |
| 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 |
<downmix>1</downmix> |
| 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 |
<savefile>/home/ices/dump/stream1.ogg</savefile> |
| 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 |
<encode> |
| 280 |
<quality>0</quality> |
| 281 |
<nominal-bitrate>65536</nominal-bitrate> |
| 282 |
<maximum-bitrate>131072</maximum-bitrate> |
| 283 |
<minimum-bitrate>-1</minimum-bitrate> |
| 284 |
<managed>0</managed> |
| 285 |
<samplerate>22050</samplerate> |
| 286 |
<channels>1</channels> |
| 287 |
<flush-samples>11000</flush-samples> |
| 288 |
</encode> |
| 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 |
|