Ogg Vorbis Streaming: ices2 HOWTO
ices2 generates Ogg Vorbis sources for icecast2 to stream.
ices2 is written by Michael Smith <firstname.lastname@example.org>.
This documentation is almost certainly superceded by the official Icecast documentation.
2011-01-21: Removed dead links, added link to official documentation.
2003-08-20: Added link to Japanese translation.
2002-12-19: No sub-module checkout is required now.
2002-08-10: Complete re-write! Now covers configuration in depth.
- Configuration overview
- General configuration
- Metadata configuration
- Input module configuration
- Streaming instance configuration
- Encoding configuration
- Live streaming with run_ices
Amongst others that you probably have installed already, ices2 depends on the following libraries, so make sure you have these installed.
- libxml (Debian:
apt install libxml2 libxml2-dev)
- libogg, libvorbis (Debian:
apt install libogg0 libogg-dev libvorbis0 libvorbisenc2 libvorbis-dev)
- libshout (maintained in CVS alongside ices2 - see below)
Building ices2 requires libshout. As both are currently in active development, the libshout API changes occasionally. So even if you already installed it, it's a good idea to keep up to date. First, log in to CVS. When prompted for a password, enter 'anoncvs'.
cvs -d :pserver:email@example.com:/usr/local/cvsroot login
Next check out the libshout source ...
cvs -d :pserver:firstname.lastname@example.org:/usr/local/cvsroot co libshout
Build it and install (by default, files are installed into /usr/local):
cd libshout ./autogen make make install
If you didn't already log into CVS to fetch libshout above, do so now. Next, check out the ices repository:
cvs -d :pserver:email@example.com:/usr/local/cvsroot co ices
Build in the same way:
cd ices ./autogen make make install
The configuration file for ices2 is in XML. Two reasonably self-documenting
example configurations are supplied in the
conf subdirectory - one
for playlists and one for live streaming. Most people will be able to adapt
one of these for their purpose, but will probably at least want to tune the
Note: Some of the descriptions here are taken (almost) verbatim from the example configurations.
Here's what an ices2 configuration file looks like. Follow the links for
more detail about a particular section. Note that you can declare multiple
<instance>s for a stream.
<?xml version='1.0'?> <ices> General configuration (logging, etc.) <stream> <metadata> Metadata configuration </metadata> <input> Input module configuration </input> <instance> Streaming instance configuration <encode> Encoding configuration </encode> </instance> </stream> </ices>
The directory log files will be written into.
The name of the logfile.
What level to log up to. Levels are: 0 (none), 1 (errors), 2 (warnings), 3 (info) or 4 (debug).
Set this to 1 if you would prefer to see logs written to the console instead of to the logfile. Useful for debugging.
<name>Example stream name</name>
<description>A short description of your stream</description>
Some general information about the stream. As of 2002-08-11, you can embed a
<metadata> section of exactly same format inside
<instance> sections to override metadata on a
Input module configuration
There are currently four types of input module (actually three, but the playlist module itself supports two different types).
... 'Basic' playlist input module
Select 'basic' playlist module.
Name of the file to take the playlist from. This file should be a plain ASCII text file containing a list of Ogg Vorbis audio files to stream, each on a separate line.
Set to 0 to play files in order, 1 for random play.
Set to 0 to repeat the playlist indefinitely. Set to 1 to only play through the list once.
... 'Script' playlist input module
Select 'script' playlist module.
Name of a program or script to call. All this script should do is output a single line containing the filename to play, however the script itself can be arbitrarily complex. With a little ingenuity you could implement play frequencies, music genre depending on time of day and regularly placed trailers.
If you send ices a HUP signal, it will move to the next track in a playlist.
... STDIN input module
This input module will take raw 16-bit little-endian PCM data from standard input.
Samplerate and number of channels for incoming data.
... Audio device input modules
This will take live audio data from an OSS supported sound card or the Sun audio device.
Specify which device to use.
/dev/dsp is a good choice for
OSS sound cards, or
/dev/audio for the Sun audio device.
Configure the samplerate and number of channels for the soundcard to record.
If set to 1, you can update metadata on the fly. By default ices will read metadata from the standard input (updating when it receives a blank line), but by setting the next parameter you can have it read from a designated file upon receipt of a USR1 signal. Metadata should contain 'name=value' pairs on separate lines. For example:
TITLE=Faster Than Snakes With A Ball And A Chain ARTIST=Cardiacs ALBUM=Greatest Hits CONTACT=http://www.cardiacs.com/
Check the Ogg Vorbis comment field and header specification for tips on what to put here. If, for example, you were running an Internet radio station 24/7 encoded live, you could use this feature to update listeners about the current programme name, etc.
This is the name of the file to check for updated metadata
Streaming instance configuration
You may have one or more instances. This allows you to send the same input data to one or more servers (or to different mountpoints on the same server). Each of them can have different parameters. This is primarily useful for a) relaying to multiple independent servers, and b) encoding/reencoding to multiple bitrates. If one instance fails (for example, the associated server goes down, etc), the others will continue to function correctly.
Define the server and port number to connect to.
Set this to the password your server requires to authenticate sources.
This specifies a mountpoint for this instance. This example should result in a stream being available at
When something goes wrong (e.g. the server crashes, or the network drops) and ices disconnects from the server, these control how often it tries to reconnect, and how many times it tries to reconnect. Delay is in seconds. If you set reconnectattempts to -1, it will continue indefinately. Suggest setting reconnectdelay to a large value if you do this.
This describes how long the internal data queues may be. This basically lets you control how much data gets buffered before ices decides it can't send to the server fast enough, and either shuts down or flushes the queue (dropping the data) and continues. For advanced users only.
This will dump this stream to a file as well as sending it to a server. Useful for streams you are encoding live that you may want to make available on demand later.
<encode> ... </encode>
Unless you are using pre-encoded ogg files from a playlist that you don't want to reencode to a standard bitrate, you will need to include an encoding setup. See the next section for details.
Set up the samplerate and number of channels for this encoding. Note that these must currently match the input data format except when re-encoding Oggs (using a playlist), where resampling and downmixing is implemented.
You can choose to encode using full VBR, partial VBR or full bitrate management.
... Full or partial VBR
A setting (floating point allowed) between -1 and 10. At 44kHz stereo, a quality setting of 0 often yields about 64kbps. Quality 0 is considered the baseline of acceptability, but you can push it as low as -1 if you feel the need.
Partial VBR is enabled by specifying either of these in addition to a quality setting. They will impose a maximum and/or minimum limit on the average encoded bitrate, if possible (for more definite bitrate management, use full management, below).
... Full bitrate management
Enable full bitrate management.
This will force the encoder within certain bitrate bounds over a window of a few seconds. This almost always sounds worse than just using a quality setting, but is useful for ensuring modems users don't drop out while listening to your stream.
Live streaming with run_ices
A script is included in the
contrib subdirectory called
run_ices (latest available here). This creates a config
file from command line parameters and spawns ices2 for live streaming. It can
configure ices2 for multiple encodings (at different bitrates, say) and
supports timed runs, making it ideal for scheduling encodes from cron. For
run_ices -S localhost -P 8000 -p hackme -m oss -q -1 -o low.ogg test/low.ogg -b 128000 -o high.ogg test/high.ogg -t 01:00:00
Will configure ices to send two streams, one at quality setting -1, another at nominal bitrate 128k (http://localhost:8000/test/low.ogg and http://localhost:8000/test/high.ogg respectively) for one hour while also writing those streams to local files called low.ogg and high.ogg. These files could then be copied up to a web server for archived playback. (Server configuration here corresponds to the current sample config in the icecast2 CVS repository).
You can now specify samplerate (-sr) multiple times. The first time will be
used to configure the device. If you set it differently later in the command
line, subsequent instances will be configured with a
<resample> section. For example:
run_ices -sr 44100 -c 2 -q 2 high.ogg -sr 22050 -q -1 low.ogg
Starts two instances, one at 44kHz quality 2, another downsampled to 22kHz and encoded at quality -1.