Ices Manual
__________
A. Introduction
B. What's it for?
C. What can it do?
1. Cue file
2. Signal Handling
3. Playlist Handling
4. Reencoding
5. Vorbis, FLAC and MP4 transcoding
6. Crossfading
D. Configuring
1. Command line options
2. Configuration file (ices.conf)
E. Licensing
F. Developers resources
_______
A. 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/.
B. 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.
C. 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).
o filename
o size (in bytes)
o bitrate (in kbits/s)
o minutes:seconds (total song length)
o percent played (i.e 25, no %-sign)
o 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.
o ID3 Artist
o ID3 Title
2. Signal handling
o Sending SIGINT to ices will make it exit.
o Sending SIGHUP to ices will make it close and reopen the
logfile.
3. Reencoding
If compiled with support for reencoding using libmp3lame, and
you supply the -R command line option or set the
Execution/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.
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.
If you want to change it, I suggest you add support for this
to ices and mail me a patch.
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 :)
You'll need at least lame 3.88beta, and current CVS is a bit
better.
4. 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 an
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 5 functions; test,
init, shutdown, get_next, and get_current_lineno. I suggest
you take a look in the distributed module files and just
expand on that.
5. Vorbis, FLAC and MP4 transcoding
If compiled with the appropriate libraries, ices can transcode
Ogg Vorbis, FLAC and MP4 (AAC) audio files to MP3 on the fly. Keep
your sources in whatever format you like best.
6. Crossfading
If compiled with reencoding support, ices can also crossfade
between tracks, giving you that pro radio station sound.
D. 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:
o -B (Background (daemon mode))
o -b <stream bitrate>
o -C <crossfade seconds>
o -c <configfile>
o -D <base directory>
o -d <stream description>
o -f <dumpfile on server>
o -F <playlist>
o -g <stream genre>
o -h <host>
o -i (use icy headers)
o -M <interpreter module>
o -m <mountpoint>
o -n <stream name>
o -p <port>
o -P <password>
o -r (randomize playlist)
o -s (private stream)
o -S <perl|python|builtin>
o -u <stream url>
o -N <Reencoded number of channels>
o -H <Reencoded sample rate>
2. Configuration file (icec.conf)
Here's a sample configuration file. It's the same as the
ices.conf.dist that is included in the ices distribution.
<?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>http</Protocol>
</Server>
<Execution>
<Background>0</Background>
<Verbose>1</Verbose>
<BaseDirectory>/tmp</BaseDirectory>
<Reencode>0</Reencode>
<Samplerate>-1</Samplerate>
<Channels>-1</Channels>
</Execution>
<Stream>
<Name>Cool ices default name from XML</ice
s:Name>
<Genre>Cool ices genre from XML</Genr
e>
<Description>Cool ices description from XM
L</Description>
<URL>Cool ices URL from XML</URL>
<Bitrate>128</Bitrate>
<Public>1</Public>
</Stream>
</ices:Configuration>
3. Configurations options
This describes all the different options in ices.
o 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.
o Server Port
Command line option: -p <port>
Config file tag: Server/Port
This is the port the server is listening on, by default
8000.
o 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.
o 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.
o Execution Background
Command line option: -B
Config file tag: Execution/Background
This will launch ices in the background, as a daemon.
o 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.
o Execution Base Directory
Command line option: -D <directory>
Config file tag: Execution/BaseDirectory
ices uses this directory for cue files, log files and
temporary playlist files. You need write permissions in
this directory. The default is /tmp
o Execution Reencode
Command line option: -R (turns reencoding on)
Config file tag: Execution/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.
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
definately not enough.
For legal reasons, this option is not available on the
binary distributions.
o Execution Samplerate
Command line option: -H <samplerate>
Config file tag: Execution/Samplerate
Use this to force liblame reencoding to output mp3 data
with this samplerate.
o Execution Channels
Command line option: -N <number of channels>
Config file tag: Execution/Channels
Use this to force liblame reencoding to output mp3 data
with this many channels.
o Stream Mountpoint
Command line option: -m <mount point>
Config file tag: Stream/Mountpoint
This is the name of the mountpoint for this stream on the
icecast server. Clients can access this stream at
http://host:port/<mount point>.
NOTE: This option does nothing if you are running in shoutcast
compatibility mode.
o 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.
o 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.
o Stream Description
Command line option: -d <stream description>
Config file tag: Stream/Description
This option is a description of your stream.
o Stream URL
Command line option: -u <URL>
Config file tag: Stream/URL
This should be a URL describing your stream.
o 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.
o 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).
o 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 passed to the playlist handler.
o 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.
o 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
databases and keeps track of god knows what. ices
handles embedded python and embedded perl, so now you
can write your own modules, without modifying ices, that
does just about anything. Use this option to change the
playlist handler type from builtin (default), to python
or perl.
o 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'
o Playlist Crossfade
Command line option: -C <crossfade secs>
Config file tag: Playlist/Crossfade
If this is greater than zero, and you have reencoding support,
ices will crossfade the specified number of seconds between tracks.
E. Licensing
ices is licensed under the Gnu General Public License, and for
more info about that I suggest you read the file named COPYING.
F. 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 originally written by Alexander Haväng [eel@icecast.org].