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

Other possibilities usually involve a playlist, but you may want to invoke a separate program which can produce PCM via a pipe into ices.

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.

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.