- 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/.
- 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.
- What can it do?
- 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
- Signal handling
- Sending SIGINT to ices will make it exit.
- Sending SIGHUP to ices will make it close and reopen the logfile.
- Reencoding
If compiled with support for reencoding using liblame, 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 :)
I've only tested this with lame 3.86.1, and your mileage my vary.
- 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.
- 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.
- Command line options
Options:
- -B (Background (daemon mode))
- -b <stream bitrate>
- -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>
- 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">
<ices:Playlist>
<ices:File>apan.txt</ices:File>
<ices:Randomize>1</ices:Randomize>
<ices:Type>builtin</ices:Type>
<ices:Module>ices</ices:Module>
</ices:Playlist>
<ices:Server>
<ices:Hostname>localhost</ices:Hostname>
<ices:Port>8000</ices:Port>
<ices:Password>letmein</ices:Password>
<ices:Protocol>xaudiocast</ices:Protocol>
</ices:Server>
<ices:Execution>
<ices:Background>0</ices:Background>
<ices:Verbose>1</ices:Verbose>
<ices:Base_Directory>/tmp</ices:Base_Directory>
<ices:Reencode>0</ices:Reencode>
<ices:Samplerate>-1</ices:Samplerate>
<ices:Channels>-1</ices:Channels>
</ices:Execution>
<ices:Stream>
<ices:Name>Cool ices default name from XML</ices:Name>
<ices:Genre>Cool ices genre from XML</ices:Genre>
<ices:Description>Cool ices description from XML</ices:Description>
<ices:URL>Cool ices URL from XML</ices:URL>
<ices:Bitrate>128</ices:Bitrate>
<ices:Public>1</ices:Public>
</ices:Stream>
</ices:Configuration>
- 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
- 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.
- 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.
- Execution Channels
Command line option: -N <number of channel>
Config file tag: Execution/Channels
Use this to force liblame reencoding to output mp3 data with this many channels.
- 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).
- 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.
- 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 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.
- 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'
- Licensing
ices is licensed under the Gnu General Public License, and for more info about that
I suggest you read the file named COPYING.
- 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 is written by Alexander Haväng [eel@icecast.org].
Last modified: Thu Aug 24 13:01:27 PDT 2000