Config File
The ices 2 configuration file is in XML format, which is described in detail below.
There are a few sample XML files provided which show the main ways ices is used.
A live audio feed often comes from a soundcard but may come via a server such as JACK
- ices-oss.xml
- ices-alsa.xml
- ices-jack.xml
Other possibilities usually involve a playlist, but you may want to invoke a separate
program which can produce PCM via a pipe into ices.
- ices-pcm.xml
- ices-playlist.xml
The ices-switch.xml is an example of how you can define a series of inputs. You could
use this to switch between a live session and a pre-recorded playlist if it require. All
available inputs can be used with this mechanism, but only 1 can be used at any one time.
A switch between inputs can occur if an input stops or manual intervention occurs with a
USR2 signal.
An unusual one is the ices-fixit.xml, which is basically a playlist but just outputs
to files and the timer is disabled so that it runs very quickly. This can be used to
split files or maybe even repair some Ogg Vorbis files.
General layout
<?xml version="1.0"?>
<ices>
general settings
stream section
</ices>
General settings
These apply to IceS as a whole. The example below gives a useful example to work to
<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>
background
Set to 1 if you want IceS to put itself into the background.
logpath
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.
logfile
The name of the logfile created. On log re-opening the existing logfile is
renamed to <logfile>.old. In the case of HUP, renaming is not done as
it is often moved/deleted before the signal is sent.
logsize
When the log file reaches this size (in kilobytes) then the log file will
be cycled (the default is 2Meg). Sending the HUP signal reopens the log
which is another way for logs to be cycled.
loglevel
A number that represents the amount of logging performed.
- 1 - Only error messages are logged
- 2 - The above and warning messages are logged
- 3 - The above and information messages are logged
- 4 - The above and debug messages are logged
consolelog
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.
pidfile
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.
Stream section
This describes how the input and outgoing streams are configured.
<stream>
Global metadata
Inputs
Runners
</stream>
Global metadata
<name>My Stream</name>
<genre>Rock</genre>
<description>A short description of your stream</description>
<url>http://mysite.org</url>
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.
Inputs
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.
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.
Runners
A runner is a thread. You need at least 1, but each runner can process
several encodings. As encoding is a CPU intensive task, grouping these
into the same runner can help the load on the machine, especially if your
machine does other work. Often only 1 runner is needed but you could say
that the general rule of thumb is 1 runner per CPU.
While a runner may indicate the CPU usage, the actual encoding of the
stream is placed within an <instance>. More than 1 instance can be
defined within each runner.
<runner>
<instance>
...
</instance>
<instance>
...
</instance>
</runner>
Instance
Each instance defines 1 encoded stream. This means that for multiple
bitrate/quality streams, a separate <instance> is needed for each
bitrate. Each instance defines a particular set actions that occur on the
passed in audio. Any modifications to the input data are isolated to the
instance.
<instance>
name
description
genre
url
resample
downmix
encode
savefile
shout
</instance>
name, description, genre and url
These are exactly the same as the ones defined in the global metadata.
In here they override the global settings, so often these are not needed
Resample
<resample>
<out-rate>22050</out-rate>
</resample>
This is used to force the samples coming from the input to be at a specific
samplerate, this can be useful if the input can be varied or if the input can only
do 1 samplerate like 48000 and you want to stream at 22050. Reducing the samplerate
is one way to reduce the stream bitrate but you lose higher frequency sound.
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.
Downmix
<downmix>1</downmix>
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.
Encode
<encode>
<quality>0</quality>
<nominal-bitrate>65536</nominal-bitrate>
<maximum-bitrate>131072</maximum-bitrate>
<minimum-bitrate>-1</minimum-bitrate>
<managed>0</managed>
<passthru>0</passthru>
</encode>
quality
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.
nominal-bitrate
State a bitrate that the encoder should try to keep to. This can be used as an
alternative to selecting quality.
managed
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.
maximum-bitrate
State bitrate in bits per second to limit max bandwidth used on a stream. Only
applies if managed is enabled.
minimum-bitrate
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
shouldn't really be needed.
passthru
Set to 1 if you want incoming pre-recoded vorbis (from playlist) to not
be re-encoded. This should only really be used if you have a PCM input
that needs encoding but a playlist that does not.
Savefile
<savefile>
<filename>/archive/ices/%F/stream.ogg</filename>
<duration>86400</duration>
<fmask>0644<fmask>
<dmask>0755<dmask>
<on-metadata>1</on-metadata>
</savefile>
Sometimes the stream transmitted wants to be saved to disk. This can be useful
for live recordings.
filename
State a filename for saving the Ogg Vorbis data. Files can be re-opened so
you probably want to state a pattern like as shown that allows for expanding
at the time it is opened. The % codes can be found in strftime(2) and can
apply to directories as well as files.
duration
After the stated number of seconds, the current save file is closed and then
another is automatically re-opened based upon the filename pattern.
on-metadata
Like above this determines when the save file is closed and the next reopens,
in this case new headers (new metadata) triggers the reopening.
fmask
When a new file is created, it is given the stated mask so that permission
access is maintained.
dmask
It is possible that new directories could be created (if the pattern uses a
% code for a directory component), if so, then this states the directory
mask.
Shout
This is used to define a connection to an icecast server. Several <shout>
definitions can be used if you want to state different servers for the same
encoded stream. Each shout connection acts independantly from each other but they
send the same encoded stream
<shout>
<hostname>streamingserver.org</hostname>
<port>8000<port>
<password>hackme<password>
<mount>/stream.ogg<mount>
<yp>1<yp>
<flush-samples>20000<flush-samples>
<reconnectdelay>60<reconnectdelay>
</shout>
hostname
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.
port
State the port to connect to, this will be the port icecast is listening on,
typically 8000 but can be any.
password
For providing a stream, a username/password has to be provided, and must
match what icecast expects.
mount
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.
yp
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.
flush-samples
This is the trigger level in samples for when ogg pages are sent out. The
default is the samplerate which means some data is sent each second.
reconnectdelay
This is the number of seconds, after a disconnect, that will be left to pass
before another connection is attempted.