Ices2 XML Configuration
The most popular and most recommended streaming software for use with icecast is ices. The most recent version is named ices2 and it operates well with icecast2. An ices0 release also exists and is used for streaming MP3 audio files. This latter version came about in response to user requests for an alternative streaming solution aside from Ogg Vorbis, which is the favored format of ices2. Ices0 is covered later in this book under the alternative streaming solutions section.
There are couple different methods that can be used to stream audio using the standard ices2 configuration files; one is to stream live raw audio and encode it on the fly, the other is to create a playlist and stream static audio files. The parameters for both differ slightly. Static audio files set aside for streaming must be included on a local playlist and must be physically located on the local or networked hard drive. They should also be in Ogg Vorbis or .ogg format.
The next section explains first how to stream live audio as it is piped into your audio card's input port. The next section explains how to encode and stream static Ogg Vorbis files. Note the differences of each and adjust your settings to match.
Live Audio Streaming Configurations
Use the sample ices-live.xml configuration for streaming a live audio feed on the icecast encoding box. When dealing with different streaming variations, rename this file to be more descriptive and indicative of the stream type. For example, if wanting to stream KSL's live radio feed, this file might be named live-ksl.xml. When streaming any other type of raw audio input, this file could just as easily be renamed to live-test.xml. Use the naming convention that best works for you.
This sample configuration is a customized live-ices.xml file designed for streaming live audio. It is based on the same variables used in the icecast.xml file described previously. Another important item to note is that this live audio streaming configuration is designed to stream three separate audio files of varying quality; highband.ogg, midband.ogg and lowband.ogg. Each is designed to utilize a different portion of the listener's bandwidth with a respective increase in audio quality.
Example 2. Sample Ices2 ices.xml File
<?xml version="1.0"?>
<ices>
<background>0</background>
<logpath>/usr/local/icecast2/logs</logpath>
<logfile>ices.log</logfile>
<loglevel>4</loglevel>
<consolelog>0</consolelog>
<pidfile>/usr/local/icecast2/ices.pid</pidfile>
<stream>
<metadata>
<name>Test Stream</name>
<genre>music</genre>
<description>A test stream</description>
<url>http://icecast.mydomain.com</url>
</metadata>
<input>
<module>oss</module>
<param name="rate">44100</param>
<param name="channels">2</param>
<param name="device">/dev/dsp</param>
<param name="metadata">0</param>
<param name="metadatafilename">live</param>
</input>
<instance>
<hostname>xx.xxx.xxx.xx</hostname>
<port>8000</port>
<password>letmein</password>
<mount>/highband.ogg</mount>
<yp>0</yp>
<reconnectdelay>2</reconnectdelay>
<reconnectattempts>5</reconnectattempts>
<maxqueuelength>80</maxqueuelength>
<encode>
<quality>2</quality>
<nominal-bitrate>96000</nominal-bitrate>
<samplerate>44100</samplerate>
<channels>2</channels>
</encode>
</instance>
<instance>
<hostname>xx.xxx.xxx.xx</hostname>
<port>8000</port>
<password>password_01</password>
<mount>/midband.ogg</mount>
<yp>0</yp>
<reconnectdelay>2</reconnectdelay>
<reconnectattempts>5</reconnectattempts>
<maxqueuelength>80</maxqueuelength>
<downmix>1</downmix>
<resample>
<in-rate>44100</in-rate>
<out-rate>22050</out-rate>
</resample>
<encode>
<nominal-bitrate>32000</nominal-bitrate>
<samplerate>22050</samplerate>
<channels>2</channels>
<quality>1</quality>
</encode>
</instance>
<instance>
<hostname>xx.xxx.xxx.xx</hostname>
<port>8000</port>
<password>password_02</password>
<mount>/lowband.ogg</mount>
<yp>0</yp>
<reconnectdelay>2</reconnectdelay>
<reconnectattempts>5</reconnectattempts>
<maxqueuelength>80</maxqueuelength>
<downmix>1</downmix>
<resample>
<in-rate>44100</in-rate>
<out-rate>11000</out-rate>
</resample>
<encode>
<nominal-bitrate>16000</nominal-bitrate>
<samplerate>11000</samplerate>
<channels>1</channels>
<quality>-1</quality>
</encode>
</instance>
</stream>
</ices> |
There are a couple additional items that should be explained in more detail. Though comments are provided with the example distribution files, beginning users may still have difficulty configuring them for their particular system.
In the example above, there are three separate audio streams at varying sample and bitrates. Each section is a snapshot of the samplerates and bitrates used by each individual stream. As configured here, these three streams are accessed by their unique mountpoint. Any relaying server set up simply pulls these same streams off the master box, using the same mount point. Be certain, however, to know the password required by each. As indicated above, there are three separate passwords for each stream. Customize these passwords to your server and user's needs.
 | One of the first problems you may also encounter when configuring icecast and ices initially is getting the right samplerate. Some audio cards prefer a samplerate of 41000 or 41kHz rather than the more frequently used 44100 or 44.1kHz. SoundBlaster cards work well with a samplerate of 44100, while some older Ensoniq cards required 41000. Test both to see which works best for you. |
Configuring a Static Playlist Stream
Use this configuration for playing a static playlist. The name of this configuration file is ices-playlist.xml. Verify the playlist is located in the directory specified. All other fields are pretty self-explanatory. Consult the comments in the distribution example for additional clarification on what each value means.
Example 3. Example Static Playlist XML File
<?xml version="1.0"?>
<ices>
<background>0</background>
<logpath>/usr/local/icecast2/logs</logpath>
<logfile>ices.log</logfile>
<loglevel>4</loglevel>
<consolelog>0</consolelog>
<pidfile>/usr/local/icecast2/ices.pid</pidfile>
<stream>
<metadata>
<name>Test Playlist</name>
<genre>playlist</genre>
<description>A test playlist</description>
</metadata>
<input>
<module>playlist</module>
<param name="type">basic</param>
<param name="file">playlist.txt</param>
<param name="random">0</param>
<param name="restart-after-reread">0</param>
<param name="once">0</param>
</input>
<instance>
<hostname>xx.xxx.xxx.xx</hostname>
<port>8000</port>
<password>password_01</password>
<mount>/playlist.ogg</mount>
<reconnectdelay>2</reconnectdelay>
<reconnectattempts>5</reconnectattempts>
<maxqueuelength>80</maxqueuelength>
<encode>
<nominal-bitrate>64000</nominal-bitrate>
<samplerate>44100</samplerate>
<channels>2</channels>
</encode>
</instance>
</stream>
</ices> |
Ices2 Configuration Variables
The next few sections explain in more detail each element of the ices2 configuration files, as shown in the two previous sections. It looks first at the streaming file and then examines the static playlist configuration file.
Preliminary Settings
This is the initial portion of a standard ices-live.xml configuration file. It specifies the basic function of the streaming program, the files to which data should be logged or if it should be piped to the console. It also specifies the process ID file of the running process.
<background>0</background> <logpath>/usr/local/icecast2/logs</logpath> <logfile>ices.log</logfile> <loglevel>4</loglevel> <consolelog>0</consolelog> <pidfile>/usr/local/icecast2/ices.pid</pidfile> |
Here is a more detailed analysis of each field and what it accomplishes.
- background
Specifies whether or not the ices2 process should run in the background as a daemon process or be available from the console. It is recommended that you choose the background process, which is the default. Choosing "0" selects the process to run in the background, "1" runs ices2 in the foreground or on the console. Choosing the latter can be dangerous as closing the terminal will also close the application.
- logpath
Defines the directory in which the ices.log file is kept. This directory must be first created or an error message results. The default is /var/log/ices. I prefer keeping my ices.log file in the same directory as my icecast log files. Modify this variable to your system.
- logfile
Specify the name of the log file. The default ices.log file name works well here. If you are running ices2 in tandem with another ices program, you may wish to rename it to reflect the version number.
- loglevel
States the level of logging to perform. The levels defined here match those of icecast2; 1 = error, 2 = warn, 3 = info, 4 = debug. Be aware there is no file rotation program implemented at the present time so if using the debug option or level 4, your log file can grow quite large. Use one of the many Linux log file rotation programs available. Logrotate works well and is included with many distributions.
- consolelog
A value of "1" sends log messages to the console rather than to the log files. Setting this variable to "1" is generally discouraged as writing to the screen or STDIN can stall the ices process, which is a problem for timing critical applications.
- pidfile
Specify the full path and filename to be created at start time. This file contains a single number representing the process ID of the running ices program. This process ID can be used to signal the application of certain events, such as restart if the configuration file is altered. I prefer storing all PID files in the icecast2 root directory.
Stream Settings
The stream settings under ices-live.xml can be broken down into three major sub-headings; metadata, input, and instance. Within each of these sections there are additional variables requiring data input. The section labeled instance can be repeated more than once. It is here multiple streams are specified.
Here is the stream section as it appears in its most rudimentary form. Each sub-category is examined in closer detail in the following sections:
<stream>
<metadata></metadata>
<input></input>
<instance></instance>
</stream> |
Metadata Settings
This section describes what metadata information is passed to icecast within the headers at connection time. This applies to each instance defined within the stream section. It may be overridden by a per-instance <metadata> section:
<metadata>
<name>Test Stream</name>
<genre>music</genre>
<description>A test stream</description>
<url>http://icecast.mydomain.com</url>
</metadata> |
Here are the individual elements for each metadata setting.
- name
State the name of your stream. This should be a brief descriptive message explaining the stream's purpose as this is what normally appears in the audio player's scrolling window.
- genre
Define your audio stream's genre. There are not set rules for this. It can be anything from live music to talk radio to a static playlist. This section is intended more for your own information as it normally does not appear in any media player.
- description
A more verbose explanation of what your audio stream does. This is intended more for your own use as it currently does not display in players on either the Linux or Windows platforms.
- url
Specify a URL to which users should connect. An IP address works as well. This entry is also not passed to listeners.
Input Settings
This portion of the XML code determines the bitrate, channel number and device information of the local audio card and how the data is feed to the ices process. This happens in one of two ways; typically either from a playlist or via a soundcard. These variables may require tweaking depending on the settings you choose and how you wish to encode the audio data.
The layout is consistent between 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 included in a module.
<input>
<module>oss</module>
<param name="rate">44100</param>
<param name="channels">2</param>
<param name="device">/dev/dsp</param>
<param name="metadata">0</param>
<param name="metadatafilename">live</param>
</input> |
Here is a more detailed explanation of the items included within the input section.
- module
This module handles the main audio configuration. In most cases, the variable "oss" works fine and the streaming utility takes input from "line-in". Some users may want to use "alsa". Those wanting to utilize "alsa" in place of "oss" should consult the section at the end of this chapter regarding ALSA modules.
- rate
The bitrate in hertz at which the audio stream is encoded. The default rate of 44100 works in most instances. This is the commonly-used samplerate value for commercial audio CDs. However, some audio cards may require 41000 as the default bit rate. Other drivers may prefer 48000 (DAT). Depending on your format you may want to use a lower rate. When dealing with speech audio I typically use 11000 as the default bitrate, due to the fact this is a talk radio station and does not need high-end encoding. A manageable rate between these two settings might be 22500.
- channels
The number of individual streams to be encoded on the icecast server. If planning on serving more than a single stream or if anticipating serving multiple bitrates in varying formats, increase this number to the number of streams.
- device
The default device through which audio is encoded. The default /dev/dsp works in most instances. Check the setup to see what how the default audio device is configured. If using multiple audio cards, i.e. an audio is installed on the motherboard and a PCI sound card is installed as well, the default settings may need to be modified.
In some cases Red Hat Linux configures dual devices and points them at the same audio card. For example, if installing a 2nd audio card after installing the operating system, both /dev/dsp and /dev/dsp1 may point to the same physical device. This happens especially when using a SoundBlaster Live card. Although there may appear to be two cards, only use is useable.
Once the sound module is loaded and running, create two more entries for the 2nd card to use; /dev/dsp2 and /dev/dsp3. This is done with the following two lines:
# mknod /dev/dsp2 c 14 35 # mknod /dev/dsp3 c 14 51 |
Point the streaming utility, whether it is ices or darkice, to /dev/dsp2 to access the 2nd card. You may also need to use aumix on /dev/mixer1 to set the proper audio levels on the second card.
- metadata
Decide whether to allow the server to read metadata from STDIN by default. The value "0" disables this setting while "1" enables metadata. Metadata arrives in the form of tag=value, and while Ogg Vorbis can handle most any supplied tags, most players only utilize the artist and title tags.
- metadatafilename
This is the name of the file to open and from which the metadata tags are read. If this parameter is missing then standard input (STDIN) is read. A metadata file is often the better approach. The normal procedure is to populate the file contents then send a SIGUSR1 command to the ices process. The format of the file itself is a one comment per line format. Below is a minimalist example of the file. Other tags can be used but players tend to only look for artist and title for displaying information. The data must be in UTF-8 format, though this is not checked by ices.
artist=U2
title=Still Haven't Found What I'm Looking For
Instance Settings
This section of the ices-live.xml file is perhaps the most complicated on account of the many variables available and that when dealing with multiple streams, the 1st instance may lack some items that are present in later instances. The example below shows the additional variables present when dealing with extra audio streams of varying quality.
<instance>
<hostname>xx.xxx.xxx.xx</hostname>
<port>8000</port>
<password>password_01</password>
<mount>/midband.ogg</mount>
<yp>0</yp>
<reconnectdelay>2</reconnectdelay>
<reconnectattempts>5</reconnectattempts>
<maxqueuelength>80</maxqueuelength>
<downmix>1</downmix>
<resample>
<in-rate>44100</in-rate>
<out-rate>22050</out-rate>
</resample>
<encode>
<nominal-bitrate>32000</nominal-bitrate>
<samplerate>22050</samplerate>
<channels>2</channels>
<quality>1</quality>
</encode>
</instance> |
Here are further explanations of each field shown in the XML settings above.
- hostname
Specify the hostname of the icecast server to contact. This can be a FQDN or IP address and can be ipv4. The setting ipv6 works only on systems supporting IPv6. The default is localhost.
- port
State the port to which ices should connect. This is normally the port on which icecast listens. Port 8000 is typically used for icecast, but it can be any port.
- password
When providing a stream to outside resources, a username/password must be provided and must match what icecast expects. This username/password pair is normally the same as that which is included in the icecast.xml file.
- mount
Mountpoints are used to identify a particular stream on icecast servers. These mountpoints are affixed to the end of the domain:port URL loaded in to the audio clients. They must begin with a beginning forward slash or / and, for the benefit of audio clients, should end with the .ogg extension. For example; http://icecast.ksl.com:8000/talkradio.ogg is a valid URL and mountpoint. The mountpoint here is talkradio.ogg.
- yp
Unless this option is set streams do not normally advertise themselves on YP servers. This feature works only if icecast is configured to talk to YP servers.
- reconnectdelay
State the time in seconds the streaming utility should wait before attempting to reconnect to the icecast server.
- reconnectattempts
The number of times the streaming utility should attempt to reconnect to the icecast server.
- maxqueuelength
This is the queue length to be loaded for encoding.
- downmix
This setting is optional. It is included in additional instances aside from the first stream. Refer to the ices-live.xml example for more details on how and when the downmix setting appears. This tells the encoder that this particular instance has been downmixed from a higher encoding rate.
Resample Settings
When streaming multiple streams, use the resample options to configure the other streams at varying bitrate levels.
<resample>
<in-rate>44100</in-rate>
<out-rate>22050</out-rate>
</resample> |
Here are some clarifications of the terms shown above.
- in-rate
This value sets the input rate selected in the input section earlier. Again, the value here is 44100 or 41000, depending on the type and quality of the soundcard.
- out-rate
This value is the new sample rate to use for additional streams. This value should be a lower rate than that of the in-rate. Valid rates include 22500 and 11000. Others are possible.
Encode Settings
The encode options are for changing the settings of a stream. Specify the bitrate, samplerate channels and quality of a specific stream. Other items such as that stream's mountpoint are set elsewhere within the instance section.
<encode>
<nominal-bitrate>32000</nominal-bitrate>
<samplerate>22050</samplerate>
<channels>2</channels>
<quality>1</quality>
</encode> |
Let's break down the variables shown here once more.
- nominal-bitrate
Determines the optimal bitrate of the stream. This is usually set at 96000, 32000, or 16000, depending on what you want your bitrate to be. It is usually higher than the samplerate.
- samplerate
Set the samplerate of this particular stream. This relates directly to the out-rate variable in the resample section.
- channels
Specify the number of channels required. 2 normally equates to stereo and 1 is mono.
- quality
Specify the level of quality; -1 is poor and is reserved for talk radio with a bitrate of 16000. 0 is average, 1 is better and 2 is best used for audio CDs.
Input Modules
This section covers the available input modules for use with ices2. This section borrows liberally from the ices2 documentation page located at the following URL: http://www.icecast.org/files/ices_docs/inputs.html.
There are several input modules available for use with ices, depending on the platform, drivers and libraries available. The general layout is defined as follows:
<input>
<module>module name</module>
<param name="name1">value</param>
<param name="name2">value</param>
<param name="name3">value</param>
</input> |
For live input and encoding on the fly, you may find ALSA supports a particular sound card better than the Open Sound System or OSS. Again, here is the input module for using OSS.
<input>
<module>oss</module>
<param name="rate">44100</param>
<param name="channels">2</param>
<param name="device">/dev/dsp</param>
<param name="metadata">1</param>
<param name="metadatafilename">/home/ices/metadata</param>
</input> |
This module is often used for reading live input from Open Sound System drivers. These are the most common type of sound drivers on Linux systems though they are also available on other platforms. The module reads audio from the DSP device in the format specified by the provided parameters. Explanations for each of the aforementioned variables has already been covered in this chapter.
ALSA Modules
The Advanced Linux Sound Architecture (ALSA) is a completely different sound system designed for Linux, though it also provides OSS compatibility. The OSS driver should work with ALSA as well. But to use ALSA natively a separate module is normally used:
<input>
<module>alsa</module>
<param name="rate">44100</param>
<param name="channels">2</param>
<param name="device">plughw:0,0</param>
<param name="periods">2</param>
<param name="buffer-time">500</param>
<param name="metadata">1</param>
<param name="metadatafilename">/usr/local/ices/metadata</param>
</input> |
The parameters to ALSA are nearly the same as they are for OSS. It performs the same task as OSS, i.e. captures audio from the DSP.
- device
This is the device name as used in ALSA. This can be a physical device as in the case of "hw:0.0" or a virtual device like one with dsnoop.
- periods
Specifies how many interrupts are generated. The default is 2.
- buffer-time
The size of the buffer measured in mS. The default is 500.
Refer to the ALSA documentation page at http://www.alsa-project.org/documentation.php for additional clarifications or insights.
Sun Modules
The Sun Solaris DSP input is similar to OSS. It reads from a soundcard on a Sun Solaris UNIX machine. OpenBSD also has a sound driver that is similar to Solaris and should also be able to use this module. State the sun module by name rather than use "oss" or "alsa".
<module>sun</module> |
The parameters are the same as the OSS and ALSA modules.
StdinPCM
When feeding raw audio to your sounds card or audio device, use this module.
<input>
<module>stdinpcm</module>
<param name="rate">44100</param>
<param name="channels">2</param>
<param name="metadata">1</param>
<param name="metadatafilename">/usr/local/ices/metadata</param>
</input> |
This module should always be available on Linux machines and the parameters are almost the same except for the device. The PCM audio comes from the standard input so it can be generated from some external app feeding into a pipe.
Because it is raw PCM data being fed in to the card, it is impossible to determine the samplerate and channels. Make certain the stated parameters match the incoming PCM or the audio will be incorrectly encoded.
Playlist
The playlist module is used when playing audio from static pre-encoded Ogg Vorbis files. Ices currently checks to see if the same file is played in succession and if so, skips it. This means having a playlist containing a single Ogg file will not work. The method of file selection is determined by the playlist type. The current types are basic and script.
Basic
<param name="type">basic</param> <param name="file">/path/to/playlist</param> <param name="random">0</param> <param name="once">0</param> <param name="restart-after-reread">1</param> |
- file
State the filename path containing a list of Ogg Vorbis files. One file per line is acceptable. Lines beginning with the pound sign or '#' are treated as comments. If a line contains a single '-', then standard input is read, which provides a way of including external Ogg Vorbis streams into ices.
- random
When set to 1, the playlist is set to random when loaded. By default the random setting is off.
- once
When set to 1, the playlist is read through once and then ends. This will cause ices to exit. By default the once variable is off.
- restart-after-reread
If the playlist is re-read midway through, which may occur if the playlist was updated, then this setting restarts to the beginning of the playlist. By default this setting is off.
Be aware also that you do need to have a playlist file entry in the configuration file. If this link does not point to a valid file, the application will not start. Use the following method as a template or example script for creating a playlist:
# find <audio directory> -name *.ogg -print > playlist.txt |
Notice that because ices2 only supports Ogg Vorbis files at the present time, the only viable static audio files are Ogg Vorbis.
Script
<param name="type">basic</param> <param name="program">/path/to/program</param> |
- program
State a path to a program which when run will write as its standard output a path to an Ogg Vorbis file. The program can be anything from an executable to a shell script. It must only start, writes the filename to its standard output and then exit.
Based on the explanation presented here in this chapter, a beginning user should be able to modify an existing icecast or ices configuration and customize to his or her specifications. As stated previously, the sample XML files included with the source code provide additional comments though perhaps not as in-depth as that here. The next chapter examines additional streaming programs in greater detail.