9.2. Ices0
Most users of icecast2 should be now familiar with ices2 or as it commonly referred to, ices. This is the preferred and recommended streaming solution proposed by the icecast developers. However, as mentioned this release only encodes in Ogg Vorbis format. There exists a prior ices release designed for streaming audio in MP3 rather than in Ogg Vorbis format. This is a welcome solution for users who prefer the MP3 format or do not yet want to migrate their data over to Ogg Vorbis, or for those who wish to be able to stream both formats.
The most current release of ices0 is 0.4. Much like ices2, ices0 is strictly command line and is launched after the icecast server is up and running. This section quickly details the basics of installing and configuring ices0.
 | For those interested, 'ices' is short for 'icesource', or a source for the icecast server. The developers recommend pronouncing 'ices' as 'isis'; or the Egyptian goddess of fertility. |
Ices0 operates in much the same manner as ices2. Using a playlist of static MP3 files, ices0 sends a continuous stream of audio data to an icecast server. The server is then responsible for accepting client connections and feeding the MP3 stream to the listening clients. However, the stream originates in the streamer, or in this case, ices.
 | The terms encoder, streamer and source are used interchangeably throughout this book, and throughout most streaming audio documentation. If compiled with the appropriate libraries, ices can transcode Ogg Vorbis, FLAC and MP4 (AAC) audio files to MP3 on the fly. Store the audio files in the preferred format. |
Download and install the libshout library before building ices0 from source. Run the standard configure script. There are additional variables available such as --with-perl, --with-python and --with-lame if you want to manually add them. However, the script will attempt to detect them automatically. If they cannot be found you may have to point them to the correct library destinations.
For example, with some distributions if using package installs the libraries may be placed in odd locations. In most instances the configure script will locate the libraries but in other you may have to state their location. The file lame.h may be found at /usr/include/lame/lame.h while libmp3lame may be in /usr/lib.
If you have already installed ices2 and would like to save it for later use, backup the binary in /usr/local/bin to something like ices2. Ices0 will overwrite the ices2 binary with its own copy of ices.
# cp /usr/local/bin/ices /usr/local/bin/ices2 |
As is normally the case with most installs using source, here are the standard steps needed to configure and build binaries:
# cp ices-0.4.tar.gz /usr/local/src/ # cd /usr/local/src # gunzip -c ices-0.4.tar.gz | tar xvf - # cd ices-0.4/ # ./configure && make && make install |
To clear up any confusion between the ices0 and ices2 binaries in /usr/local/bin, rename or symbolically link the newly compiled ices binary to ices0. This was a recommended step in the chapter on installing icecast when setting up ices2. I personally recommend renaming each to their own respective versions, i.e. ices-0.4 to ices0 and ices-2 to ices2.
9.2.1. Configuring ices0
After the binary has been built and installed, customize the configuration file to your specifications. There is an example configuration file included with the source in the conf/ directory. This default configuration file is normally copied to the /usr/local/etc directory. Related files such as the ices.pm and the ices.py modules are saved in the /usr/local/etc/modules directory. These are used for the Perl modules and python respectively.
Ices0 can do everything ices2 can do, plus a bit more. It can be configured via hard-coded defaults, using a configuration file, and via command line options. The default configuration file is in XML format similar to the ices-2 release. Edit the distributed configuration and change the values as required.
9.2.1.1. Command Line Options
The command line options should be familiar to older Shoutcast users. Some options have been renamed. Command line use is especially useful to those administrators who must edit the option on the fly.
Here is a list of all available CLI options:
- -B (background or daemon mode)
- -b <stream bitrate>
- -C <crossfade seconds>
- -c <configfile>
- -D <base directory>
- -d <stream description>
- -f <dumpfile on server>
- -F <playlist>
- -g <stream genre>
- -h <host>
- -i (use icy headers)
- -M <interpreter module>
- -m <mountpoint>
- -n <stream name>
- -p <port>
- -P <password>
- -r (randomize playlist)
- -s (private stream)
- -S <perl|python|builtin>
- -u <stream url>
- -N <reencoded number of channels>
- -H <reencoded sample rate>
 | In order to use the configuration files ices depends on the libxml2 package. Verify the xml-config package is in your path. |
9.2.1.2. Example ices.conf File
Here is an example configuration file. Notice this file has several advantages over other streaming utilities such as the ability to randomize the playlist, crossfading between audio tracks, and the capability to run as a daemon program. Otherwise, the standard options are available such as mountpoint, bitrate, stream name and so forth. Experiment with the options until you get the desired effect.
Example 9-3. Example ices.conf File for Ices0
<?xml version="1.0"?>
<ices:Configuration xmlns:ices="http://www.icecast.org/projects/ices">
<Playlist>
<!-- This is the filename used as a playlist when using the builtin
playlist handler. -->
<File>playlist.txt</File>
<!-- Set this to 0 if you don't want to randomize your playlist, and to
1 if you do. -->
<Randomize>1</Randomize>
<!-- One of builtin, perl, or python. -->
<Type>builtin</Type>
<!-- Module name to pass to the playlist handler if using perl or
python. If you use the builtin playlist handler
then this is ignored -->
<Module>ices</Module>
<!-- Set this to the number of seconds to crossfade between tracks.
Leave out or set to zero to disable crossfading (the default).
<Crossfade>5</Crossfade>
-->
</Playlist>
<Execution>
<!-- Set this to 1 if you want ices to launch in the background as a
daemon -->
<Background>0</Background>
<!-- Set this to 1 if you want to see more verbose output from ices -->
<Verbose>0</Verbose>
<!-- This directory specifies where ices should put the logfile,
cue file and pid file (if daemonizing).
Do not use /tmp if you have l33t h4x0rz on your server. -->
<BaseDirectory>/tmp</BaseDirectory>
</Execution>
<Stream>
<Server>
<!-- Hostname or ip of the icecast server you want to connect to -->
<Hostname>localhost</Hostname>
<!-- Port of the same -->
<Port>8000</Port>
<!-- Encoder password on the icecast server -->
<Password>letmein</Password>
<!-- Header protocol to use when communicating with the server.
Shoutcast servers need "icy", icecast 1.x needs "xaudiocast",
and icecast 2.x needs "http". -->
<Protocol>http</Protocol>
</Server>
<!-- The name of the mountpoint on the icecast server -->
<Mountpoint>/ices</Mountpoint>
<!-- The name of the dumpfile on the server for your stream.
DO NOT set this unless you know what you're doing.
<Dumpfile>ices.dump</Dumpfile>
-->
<!-- The name of you stream, not the name of the song! -->
<Name>Default stream</Name>
<!-- Genre of your stream, be it rock or pop or whatever -->
<Genre>Default genre</Genre>
<!-- Longer description of your stream -->
<Description>Default description</Description>
<!-- URL to a page describing your stream -->
<URL>http://localhost/</URL>
<!-- 0 if you don't want the icecast server to publish your stream
on the yp server, 1 if you do -->
<Public>0</Public>
<!-- Stream bitrate, used to specify bitrate if reencoding,
otherwise just used for display on YP and on the server.
Try to keep it accurate -->
<Bitrate>128</Bitrate>
<!-- If this is set to 1, and ices is compiled with liblame support,
ices reencodes the stream on the fly to the stream bitrate. -->
<Reencode>0</Reencode>
<!-- Number of channels to reencode to, 1 for mono or 2 for stereo -->
<!-- Sample rate to reencode to in Hz. Leave out for LAME's best choice
<Samplerate>44100</Samplerate>
-->
<Channels>2</Channels>
</Stream>
</ices:Configuration> |
If any of these features appear confusing or unclear, consult the README file included with the source code. It covers most items shown here in copious detail. Since much of this is a repeat of earlier command line options, you would do best to go directly to the source for any additional clarifications. However, the comments included in the above example configuration file should be enough to assist any beginning user in getting up to speed.
It is worth mentioning that ices-0.4 does perform "lazy reencoding". By this I mean that if the bit rate, channels, and sample rate of the source file match the declared bit rate, channels and sample rate of the stream, ices simply passes the MP3 audio data through to the listener. If, however, there is a mismatch, ices re-encodes the file to match the stream parameters.
9.2.1.3. Customizing Playlists
Often the built-in playlist capabilities of ices are not enough for more advanced users. In view of this ices can also be controlled by a Perl or python script. This allows administrators to produce fancier metadata, perform calls to a database, insert station IDs every half hour or hour.
Impatient users should be able to customize their own specialized options by perusing the included ices.pm.dist or ices.py.dist files. Beginners should continue reading how the following methods may be defined:
- ices_get_next
This method is the only required method. It is called by ices at startup or when it has finished playing the previous file. It should return the path to a track. Returning an empty string signals ices to shut down.
- ices_init
If this method is defined, it is called before any other method in your script. A return value other than 1 indicates your script has failed to initialize and ices should terminate.
- ices_shutdown
If this method is defined, it is called before ices exits.
- ices_get_metadata
If this method is defined, it is called after ices_get_next and the result is used as the current track title on the icecast server.
- ices_get_lineno
If this method is defined, it is called after ices_get_next and the result is used for the line number field of the cue file. This is not a highly used feature.
9.2.2. Starting the Stream
Executing the ices0 stream is as simple as running ices2. Execute the binary and place a call to the configuration file as well. An example startup command may be as follows:
# ices0 /usr/local/icecast/conf/ices.conf & |
Monitor the log file for any error messages or problems. Ices0 is pretty forthright in what problems may arise and generally logs them for debugging purposes. Check the directory you specified in the ices.conf file for logging errors. The default location is /tmp. This directory contains an ices.log and ices.cue file. Tail the former file for a listing of all played audio files. The latter file or ices.cue contains detailed information about the currently playing file.