How to configure and run ices, the icecast streamer

# Ices Manual

1. Introduction
2. What's it for?
3. What can it do?
   1. Cue file
   2. Signal Handling
   3. Reencoding
   4. Crossfading
   5. Multiple streams
   6. Playlist Handling
4. Configuring
   1. Command line options
   2. Configuration file (ices.conf)
5. Licensing
6. Developers resources

1. Introduction

   For a very long time, the only good streaming tool for command line systems was shout. Shout had a lot of issues, it was a quick and dirty hack, it was buggy, it was sending data too fast or too slow, and it was just something no one wanted to fix. So we rewrote it from scratch, and the next generation streamer, 'ices', is here. 'ices' is short for 'icesource', a source for the icecast server. 'ices' should be pronounced 'isis' like the egyptian godess of fertility. For more information about icecast, I suggest you check out the icecast webpage at http://www.icecast.org/.

2. What's it for?

   ices, armed with a list of mp3 files, sends a continuous stream of mp3 data to an icecast server. The server is then responsible for accepting client connections and feeding the mp3 stream to them. But the stream originates in the streamer, 'ices'. The terms 'encoder', 'streamer' and 'source' are used equivalently throughout this document, and throughout all the documentation in the streaming system.

3. What can it do?
   1. Cue file

      The cue file holds information on the file that ices is currently feeding to the server. This is neat for you people out there who like running scripts. I myself, use the cue file in a tcl script, running from a eggdrop bot, on irc. That way I can ask the bot what song is currently playing, how long it is, how much of it has been played, and get information about the next songs on the playlist.
      The file currently has the following lines, (in this order).

      - filename
      - size (in bytes)
      - bitrate (in kbits/s)
      - minutes:seconds (total song length)
      - percent played (i.e 25, no %-sign)
      - playlist line index (i.e 3, if we're playing the 4:th line in the internal playlist. Logical, huh? ) Also, for you scripting people, when ices starts, it writes its process id to the file ices.pid.
      - ID3 Artist
      - ID3 Title
   2. Signal handling

      - Sending SIGINT to ices will make it exit.
      - Sending SIGHUP to ices will make it close and reopen the logfile and playlist, and reload and restart the playlist script if you are using one.
      - Sending SIGUSR1 to ices will make it skip to the next track.
   3. Reencoding

      If compiled with support for reencoding using liblame, and you supply the -R command line option or set the Stream/Reencode to 1 in the XML config file, then ices will start reencoding your files on the fly to the bitrate you specified with the -b option or the Stream/Bitrate tag.
      If you are reencoding and ices was compiled with vorbis support, you may also reencode Ogg Vorbis files as MP3 on the fly. This gives you the opportunity to convert your source files to Ogg Vorbis at your convenience while still supporting as many listeners as possible. Likewise, ices can transcode FLAC and MP4 (AAC) files if you've compiled it with FLAC and FAAD libraries, respectively.
      The sample rate, number of channels, etc, will be chosen on the fly by lame itself, unless you specify something using the -H and -N options. I think you should be fine with whatever lame chooses though.
      Also, please make sure that your files are ok before you start reencoding them with ices. This is because the mpglib part of lame (what does the decoding) is rather unstable and will call exit(0) when errors are encountered.
      This will make ices exit, which is kinda bad :)

   4. Crossfading

      If you've compiled with support for reencoding, you can crossfade between tracks (blend the end of one into the start of the next). This is controlled by the `-C` command line option or the `Playlist/Crossfade` parameter in the configuration file. Both of these take an integer argument, which is the number of seconds to crossfade. Songs less than twice the length of the crossfade requested will not be faded. This is handy for eg station IDs.

   5. Multiple streams

      You can feed the same playlist simultaneously to different mountpoints, by specifying multiple `Stream` sections in the config file or passing multiple `-m`options on the command line. This is especially useful in conjunction with reencoding because you can stream the same music at a high bitrate for broadband listeners and simultaneously at a low bitrate for POTS listeners.

   6. Playlist handling

      About 96% of all emails I got about shout was people asking me to add small changes to shout playlist handling to suit their specific needs. This is course is not how I want to spend my life :) Shout had a feature to call an external program with a system() call, before each song, and that could possibly modify the playlist. This was rather ugly, but did the trick. In ices, we take this a step further and include scripting support inside the program. You can write your own playlist handler in perl or python, whatever you prefer.
      Your script module has to define at least a function named `ices_get_next`, which should return a path to a file or FIFO containing MP3 data.
      In addition you may define the functions `ices_init` and `ices_shutdown` which will be called by ices once before asking for the first song and before shutting down, respectively.
      You may also define `ices_get_lineno`, which specifies the line number of the current track in the cue file. If you don't use the cue file it is safe to omit this function.
      Finally you can define `ices_get_metadata` to return a string you want to use for title streaming. Ices will call this function once per track after calling `ices_get_next`. If this function is not defined or returns null, ices will use whatever it can get out of the file itself, either tags or the file name.
      I suggest you take a look in the distributed module files and just expand on that.

4. Configuring

   ices can do everything shout could do, and more. It can be configured through hard coded defaults, a configfile, and command line options. The configfile is in XML, but don't get scared and run off. Just edit the distributed configfile and change the values you need. The command line options should be familiar to old shout users, although some options have been renamed.

   1. Command line options

      Options:

      - -B (Background (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>
   Note that each time you specify a mount point with `-m` you are creating a new stream, and subsequent stream options will apply only to it.
   2. Configuration file (ices.conf)

      Here's a sample configuration file. It's the same as the ices.conf.dist that is included in the ices distribution. You can specify multiple stream sections with different mountpoints, names, and reencoding options.

          			<?xml version="1.0"?>
          			<ices:Configuration xmlns:ices="http://www.icecast.org/projects/ices">
          			<Playlist>
          				<File>apan.txt</File>
          				<Randomize>1</Randomize>
          				<Type>builtin</Type>
          				<Module>ices</Module>
          			        <Crossfade>0;<Crossfade>
          			</Playlist>
          			<Server>
          				<Hostname>localhost</Hostname>
          				<Port>8000</Port>
          				<Password>letmein</Password>
          				<Protocol>xaudiocast</Protocol>
          			</Server>
          			<Execution>
          				<Background>0</Background>
          				<Verbose>1</Verbose>
          				<Base_Directory>/tmp</Base_Directory>
          			</Execution>
          			<Stream>
          				<Name>Cool ices default name from XML</Name>
          				<Genre>Cool ices genre from XML</Genre>
          				<Description>Cool ices description from XML</Description>
          				<URL>Cool ices URL from XML</URL>
          				<Bitrate>128</Bitrate>
          				<Public>1</Public>
          				<Reencode>0</Reencode>
          				<Samplerate>-1</Samplerate>
          				<Channels>-1</Channels>
          			</Stream>
          			</ices:Configuration>

   3. Configurations options

      This describes all the different options in ices.

      - Server Hostname
        Command line option: -h <host>
        Config file tag: Server/Hostname
        This is the name, or ip, of the host ices should connect to. It has to run a streaming server, capable of the xaudiocast or icy protocol.
        This value defaults to localhost.
      - Server Port
        Command line option: -p <port>
        Config file tag: Server/Port
        This is the port the server is listening on, by default 8000.
      - Server Password
        Command line option: -P <password>
        Config file tag: Server/Password
        The encoder password for the server. If this is not correct, then ices cannot log in on the server, and ices will exit.
      - Server Protocol
        Command line option: -i for icy-headers
        Config file tag: Server/Protocol
        Either xaudiocast or icy. Use xaudiocast if you can, and icy if you must.
      - Execution Background
        Command line option: -B
        Config file tag: Execution/Background
        This will launch ices in the background, as a daemon.
      - Execution Verbose
        Command line option: -v
        Config file tag: Execution/Verbose
        Normally ices outputs what stream is playing and a small amount of extra information. With verbose turned on, you get a whole lot of debugging information and lots of track info.
      - Execution Base Directory
        Command line option: -D <directory>
        Config file tag: Execution/Base_directory
        ices uses this directory for cue files, log files and temporary playlist files. You need write permissions in this directory. The default is /tmp
      - Stream Mountpoint
        Command line option: -m <mountpoint>
        Config file tag: Stream/Mountpoint
        This is the mountpoint of the stream on the icecast server, if using the x-audiocast protocol.
      - Stream Name
        Command line option: -n <stream name>
        Config file tag: Stream/Name
        This is the name of the stream, not to be confused with the name of the song playing.
      - Stream Genre
        Command line option: -g <stream genre>
        Config file tag: Stream/Genre
        This is the genre of your stream, e.g Jazz or Static.
      - Stream Description
        Command line option: -d <stream description>
        Config file tag: Stream/Description
        This option is a description of your stream.
      - Stream URL
        Command line option: -u <URL>
        Config file tag: Stream/URL
        This should be a URL describing your stream.
      - Stream Bitrate
        Command line option: -b <bitrate>
        Config file tag: Stream/Bitrate
        If you turn on reencoding then this will be the bitrate of the stream, otherwize the actual bitrate of the stream is the bitrate your files are encoded at, and this value is for displaying purposes only.
        Read the last 3 lines again, please.
      - Stream Public
        Command line option: -s (makes stream private)
        Config file tag: Stream/Public
        This regulates whether the icecast server will display your stream on a directory server. Default is 1 (yes).
      - Stream Reencode
        Command line option: -R (turns reencoding on)
        Config file tag: Stream/Reencode
        When you turn this option on, ices (if compiled with libmp3lame support) will reencode your mp3 files on the fly to whatever bitrate you specify with the Stream Bitrate option, unless the file bitrate is the same as the stream bitrate.
        PLEASE note that if your files are corrupt, this might crash ices because the library used to decode (mpglib) is not very stable. I suggest you check your files with mp3check or some other mp3 verification program before you add them to your playlist. Just popping them into your favourite player and checking the sound is definitely not enough.
        For legal reasons, this option is not available on the binary distributions.
      - Stream Samplerate
        Command line option: -H <samplerate>
        Config file tag: Stream/Samplerate
        Use this to force reencoding to output mp3 data with this samplerate.
      - Stream Channels
        Command line option: -N <number of channel>
        Config file tag: Stream/Channels
        Use this to force reencoding to output mp3 data with this many channels.
      - Playlist File
        Command line option: -F <file>
        Config file tag: Playlist/File
        This is the file where ices originally looks for files to play.
        When using playlist modules in perl or python, this argument is ignored.
      - Playlist Randomize
        Command line option: -r (randomizes file)
        Config file tag: Playlist/Randomize
        This option is passed to the playlist handler, and tells it to randomize the playlist.
      - Playlist Type
        Command line option: -S <perl|python|builtin>
        Config file tag: Playlist/Type
        By default, ices using a builtin playlist handler. It handles randomization and not much more. Most people want sophisticated playlist handlers that interface with databases and keep track of god knows what. ices handles embedded python and embedded perl, so now you can write your own modules, without modifying ices, that do just about anything. Use this option to change the playlist handler type from builtin (default), to python or perl.
      - Playlist Module
        Command line option: -M <module>
        Config file tag: Playlist/Module
        Use this option to execute a different python or perl module than the default.
        Default for python is ices.py and default for perl is ices.pm, although do NOT specify the file extension for the module. Use 'whatever' instead of 'whatever.pm' or 'whatever.py'
      - Crossfade
        Command line option: -C <seconds>
        Config file tag: Playlist/Crossfade
        If this option is specified and reencoding is enabled, ices will crossfade `seconds` between tracks.
5. Licensing

   ices is licensed under the Gnu General Public License, and for more info about that I suggest you read the file named COPYING.

6. Developers resources

   If you want to write your own streaming software, or perhaps a nice streaming mp3 client, go to developer.icecast.org.

This document was mostly written by Alexander Haväng [eel@icecast.org].