My logo

· Home
· News
· Downloads
· Gallery
· Articles
· Links
· Where's BeCrux
· My thesis

· IceGenerator
· ClamCour
· Wally
· QExchange
· ImageViewer

Created with free software
Hosted also at

Current release: 0.5.5-pre2 - Pre-release
Download it - Changelog

Icecast ID3V2

·Telnet interface

IceGenerator is a direct streaming generator for Icecast/Shoutcast. It runs as a daemon. Three child processes handle all the stuff. A fourth (optional) child cares about telnet communication.
Main idea for this program is radio automation on a Icecast/Shoutcast server. If you have many server processes and CPU saving is your priority, u can use IceGenerator.
Obviously mp3s/oggs will be already resampled to allow their streaming on your bandwidth capability.

This is a pre-realease version, cause many big changes are in progress. I'd like that you can test it along its development.

· Automatically put into playlist directories full of mp3s, or a MySQL table
· No resampling is allowed, so CPU is saved
· MP3s/OGGs are played randomly or in alphabetic order, without repeating twice a song
· You can loop the whole playlist at its end
· When IceGenerator quits, finish its last song first
· IceGenerator status is optionally reported to syslog/log file
· Very useful when used with crond
· ID3 support

· Linux 2.x/FreeBSD/NetBSD/MacOS/Solaris/OpenBSD
· You have to install libshout2. You can find it here
· For ID3 support, you have to install id3lib. You can find it here
· An IceCast/Shoutcast server
· An Intel 486-like CPU class (maybe a fast 386-like will work)
· A good broadband connection

Just type:

make install

Configure options:
--with-id3 adds ID3 support
--with-mysql adds MySQL support
--with-pgsql adds PostGreSQL support

Binary is installed in /usr/local/bin as default.
It requires a configuration file, located in /usr/local/etc as default, that indicates mp3s/oggs paths and all the stuff related to connection to Icecast. A sample configuration file is in etc/ directory of this package. All mp3s MUST HAVE .mp3 extension, and oggs MUST HAVE .ogg extension. Case is irrilevant.

Configure your streaming server properly. The default user for Icecast-2.0 is "source", but you can change as you want. You can also set a mount point different from "/", so you an many instances of icegenerator at once (each one with a different mount point, obviously).

Then type "icegenerator" and put on your stream player (like XMMS). If you can't hear music, maybe your volume is too low :-D

More options (like icegenerator.conf path, deamon start) are available at command line. Type "icegeneator -h" for synopsys.

To quit this daemon, just run "killall icegenerator", and wait for last song to finish.

Really simple, uh?

NOTE: Some players (like WinAmp, XMMS, etc.) requires a valid mount point for OGG files. They need .OGG extension, cause MIME header isn't evaluated. Keep in mind it ...

All configuration options are listed in icegenerator.conf file that usually resides in /usr/local/etc of your system.

Each line that starts with a '#' is treated as a comment.

Section Command What is means
Server IP
Specify here your IceCast/ShoutCast server IP
Specify here your IceCast/ShoutCast server port
Specify what protocol your IceCast/ShoutCast uses. Refer to your stream server documentation for further details. Only two protocols are supported, ICY and HTTP
Specify mount point for clients, that is where they find your stream server in http path. For example, setting MOUNT as /my_stream requires that clients use URL http://your_server:your_port/my_stream. REMEMBER TO SET A VIRTUAL MOUNT POINT HERE FOR OGG STREAMING. MANY PLAYERS (LIKE WINAMP, XMMS, ETC.) CAN'T AUTO RECOGNIZE OGG STREAMING WITHOUT .OGG EXTENSION
Specify which user has streaming rights. As far as I know, IceCast uses "source" as default, but u can use anything else, cause it's ignored. However you can find more informations in your stream server documentation
Specify password to connect to your stream server
Playlist FORMAT
Specify what type of audio data are you going to stream. Only MP3 and OGG files are allowed. Use "0" for OGG, "1" for MP3
Here is one of strong point of IceGenerator, its capability to accept many ways to search for audio songs. First three chars of this variable specify where are your audio songs, use "PTH" for directories, "SQL" for a MySQL table (only allowed if MySQL support is enabled during compilation), "PQL" for a PostGreSQL table (only allowed if PostGreSQL support is enabled during compilation), "PLS" for .PLS playlist file support, "M3U" for .M3U playlist file support. After a ':' character, you can specify all option that refers to way that you have chosen. It will be explain after.
RECURSIVE When this variable is set to 1, IceGenerator search for audio songs in subdirectories of directories specified in MP3PATH. Obviously, it is ignored when you use MySQL as source data
DUMPFILE Specify a file where stream is saved
LOOP If set, playlist is looped at its end
SHUFFLE If set, playlist is played randomly
Information NAME Specify name, genre, description and URL of your stream
BITRATE Specify bitrate of your stream. This value is purely informational, it doesn't affect real bitrate
PUBLIC If set, your META is published into stream directory server(s)
METAUPDATE Specify delay (in seconds) between META information update that is sent to clients. A value of "0" disables META information change, and only NAME value is displayed
MDFPATH Specify path of your global MetaDataFile. It will be explained later
Logging LOG Specify logging type. "0" means no logging at all, "1" logs to system log daemon, "2" logs to /var/log/icegenerator.log
Telnet DATAPORT Specify port used for telnet interface. If not specified at all, telnet interface will be disabled. A value of "0" sets default port (8796)

MP3PATH command
As told before, here you specify where to look for audio songs. It accepts three characters, that specify type of search, a ';', and then specific parameters for that search, that are always separated by ';'.

Type Parameters What it means
pth You can specify one or more directories separated with ';'. Wrong paths will be skipped

host your SQL server ip or symbolic name
port your SQL server port. If you specify "0", default port will be used
user SQL user that has access rights to database that you'll specify. Only SELECT right is required
password password for SQL user
database database name that contains table that contains audio songs paths
table table name that contains audio songs paths
field field name that contains audio songs paths

you have to specify only a playlist file path

· You have two directories full of OGG files, /path1/dir and /my_audio/rock/80s.
· You have a MySQL server located at, you have a database called webextra with a table called songsdata and a column called songs. MySQL user that has access rights is called john.;0;john;secretpassword;webextra;songsdata;songs

Telnet interface

You can connect to IceGenerator during stream with a TCP connection like telnet. Connection port is specified with DATAPORT option. After command is sent, an answer is returned and connection is closed. Commands that not require an answer have an "OK" string in return. All commands MUST HAVE a '.' character at their end.
Available command are reported in the following table:

Command What it means
TRACK returns information about current track
LOOP returns "1" or "0" if loop is active or not
SHUFFLE returns "1" or "0" if shuffle is active or not
LOOPON activates loop
LOOPOFF deactivates loop
SHUFFLEON deactivates shuffle
SHUFFLEOFF returns "1" or "0" if shuffle is active or not

More commands will be available in future.


This is main brand new feature added to IceGenerator, and it's called IceMetaL. Formerly it's a simple programming language that I've created, and it's used to customize META informations that appear on client software.

Its constructs are very simple. They are two:

·LOOP .. ENDLOOP: declares a loop like C/C++ do..while
·PRINT: send a META string to client

Let's make an example.

  PRINT "Here I am before loop"
  LOOP 3
    PRINT "This is a loop"
  PRINT "Here I am after loop"

The META sequence that IceGenerator sends is:

  Here I am before loop
  This is a loop
  This is a loop
  This is a loop
  This is a loop
  Here I am after loop

Really simple, I think. Let's explain every instruction.

* PRINT ("string" | ID3_TAG)
PRINT is used to send a META to client. It requires a parameter that can be:
- a fixed string enclosed by double quotes
- an ID3 tag of the file that is in streaming. The ID3 tag allowed are:



    PRINT "This is a test string"

    Sends 'This is a test string' to client


    Sends song's ID3 Title tag to client (if exists)

* LOOP [number]
This instruction starts a loop. It can be followed by an integer positive number that specifies how many times we have to loop again. Remember that number specifies OTHER passed before the first pass, so if you specify 3, for example, it will make the first pass and loop again 3 times.
If number is not specified, the loop is an infinite loop (that is, will loop until song is played).

It closes a loop. Loops can be nested (limit is 20 nested loops).

Let's make a final example.

  PRINT "This is a global test"
  LOOP 4
    PRINT "This is an inner loop"

This sends this sequence:

  "This is a global test"
  Song's ID3 artist tag
  "This is an inner loop"br>   Song's ID3 title tag
  "This is an inner loop"
  Song's ID3 title tag
  "This is an inner loop"
  Song's ID3 title tag
  "This is an inner loop"
  Song's ID3 title tag
  "This is an inner loop"
  Song's ID3 title tag
  "This is a global test"
  Song's ID3 artist tag
  "This is an inner loop"
  Song's ID3 title tag

and so on, until song is finished.

IceMetaL MetaDataFile

MetaDataFile is a file that contain IceMetaL code for your song. It must have "mdf" extension.

How it works? Let's make an example.

Suppose that your songs are placed into /home/john/streams.

Here you have two subdirs, "Madonna" and "Jackson".

This is your directory layout:

- /john
  | -myglobalfile.mdf
  | /streams
      | -Genesis - Invisible touch.mp3
      | -REM - Shiny happy people.mp3
      | /Madonna
        | -Like a virgin.mp3
        | -Like a virgin.mdf
        | -Borderline.mp3
      | /Jackson
        | -default.mdf
        | -Billy Jean.mp3
        | -Smooth Criminal.mp3
        | -Bad.mp3
        | -Bad.mdf

You have set MDFPATH variabile in icegenerator.conf to /home/john/myglobalfile.mdf

When IceGenerator fetchs a songs, it looks for an .mdf file that have the same name of song. If exists, it uses it, otherwise it looks for a "default.mdf" file placed into the same dir of song. If a local .mdf file can't be found, it uses global .mdf specified with MDFPATH variable. If a global .mdf file isn't set, filename (without .mp3 or .ogg extension and path) will be sent.

So these are .mdf file for our songs:

Genesis - Invisible touch.mp3   myglobalfile.mdf
REM - Shiny happy people.mp3   myglobalfile.mdf
Like a virgin.mp3   Like a virgin.mdf
Borderline.mp3   myglobalfile.mdf
Billy Jean.mp3   default.mdf
Smooth Criminal.mp3   default.mdf
Bad.mp3   Bad.mdf

In this way, you can fine customize your META settings.

I'd to thank

·TSx7 (alias techtonik)
·Stefani Banerian
·Michel Hendriks
·Jacob Brandup
·Patrick Atlas

for help me fixing bugs and suggesting more features.

Special thanks to Adam Beorn for developing a PHP class as IceGenerator interface.
Hope he can post it soon.

Many thanks also to SourceForge, FreshMeat, Berlios, SourceWell, IceWalkers for hosting and promoting this project.


Slack Promo

This site is dedicated in loving memory of my uncle Michael, died on July, 2003.

Copyright © 2004 - All rights reserved.
Author: Tony Sin(x) '76
You can contact me by email - tony (at) becrux (dot) com
also using an OpenGPG crypted email, with this key
or via ICQ - UIN 74913362
or via MSN - tortugalabs (at) hotmail (dot) com

Many thanks to W3C for site validation.
Valid HTML 4.01! Valid CSS!