Ogg Vorbis Streaming: ices2 HOWTO

Introduction

ices2 generates Ogg Vorbis sources for icecast2 to stream.
ices2 is written by Michael Smith <msmith@labyrinth.net.au>.

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.

Installation

Amongst others that you probably have installed already, ices2 depends on the following libraries, so make sure you have these installed.

libshout

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:anoncvs@xiph.org:/usr/local/cvsroot login

Next check out the libshout source ... 

cvs -d :pserver:anoncvs@xiph.org:/usr/local/cvsroot co libshout

Build it and install (by default, files are installed into /usr/local): 

cd libshout
./autogen
make
make install

ices2

If you didn't already log into CVS to fetch libshout above, do so now. Next, check out the ices repository: 

cvs -d :pserver:anoncvs@xiph.org:/usr/local/cvsroot co ices

Build in the same way: 

cd ices
./autogen
make
make install

Configuration

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 <encode> section.

Note: Some of the descriptions here are taken (almost) verbatim from the example configurations.

Configuration overview

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>

General configuration

<logpath>/path</logpath>
The directory log files will be written into.

<logfile>ices.log</logfile>
The name of the logfile.

<loglevel>3</loglevel>
What level to log up to. Levels are: 0 (none), 1 (errors), 2 (warnings), 3 (info) or 4 (debug).

<consolelog>0</consolelog>
Set this to 1 if you would prefer to see logs written to the console instead of to the logfile. Useful for debugging.

Metadata configuration

<name>Example stream name</name>
<genre>Example genre</genre>
<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 individual <instance> sections to override metadata on a per-instance basis.

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

<module>playlist</module>
<param name='type'>basic</param>
Select 'basic' playlist module.

<param name='file'>playlist.txt</param>
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.

<param name='random'>1</param>
Set to 0 to play files in order, 1 for random play.

<param name='once'>0</param>
Set to 0 to repeat the playlist indefinitely. Set to 1 to only play through the list once.

... 'Script' playlist input module

<module>playlist</module>
<param name='type'>script</param>
Select 'script' playlist module.

<param name='program'></param>
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.

<module>stdinpcm</module>
<param name='rate'>44100</param>
<param name='channels'>2</param>
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.

<module>oss</module>
Specify either oss or sun.

<param name='device'>/dev/dsp</param>
Specify which device to use. /dev/dsp is a good choice for OSS sound cards, or /dev/audio for the Sun audio device.

<param name='rate'>44100</param>
<param name='channels'>2</param>
Configure the samplerate and number of channels for the soundcard to record.

<param name='metadata'>1</param>
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.

<param name='metadatafilename'>metadata_info</param>
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.

<hostname>localhost</hostname>
<port>8000</port>
Define the server and port number to connect to.

<password>letmein</password>
Set this to the password your server requires to authenticate sources.

<mount>/test.ogg</mount>
This specifies a mountpoint for this instance. This example should result in a stream being available at http://localhost:8001/test.ogg.

<reconnectdelay>2</reconnectdelay>
<reconnectattempts>5</reconnectattempts>
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.

<maxqueuelength>80</maxqueuelength>
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.

<savefile>output_file.ogg</savefile>
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.

Encoding configuration

<samplerate>32000</samplerate>
<channels>2</channels>
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

<quality>0</quality>
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.

<minimum-bitrate>32000</minimum-bitrate>
<maximum-bitrate>48000</maximum-bitrate>
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

<managed>1</managed>
Enable full bitrate management.

<nominal-bitrate>36000</nominal-bitrate>
<minimum-bitrate>32000</minimum-bitrate>
<maximum-bitrate>48000</maximum-bitrate>
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 example: 

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.

Updated 21 Jan 2011