1IceGenerator 0.5.5-pre1 - README 2 3IceGenerator is a direct streaming generator for Icecast/Shoutcast. It runs as a daemon. 4Three child processes handle all the stuff. A fourth (optional) child cares about 5telnet communication. 6Main idea for this program is radio automation on a Icecast/Shoutcast server. If you have 7many server processes and CPU saving is your priority, u can use IceGenerator. 8Obviously mp3s/oggs will be already resampled to allow their streaming on your bandwidth 9capability. 10 11This is a pre-realease version, cause many big changes are in progress. I'd like 12that you can test it along its development. 13 14============ FEATURES/LIMITATIONS ============ 15* Automatically put into playlist directories full of mp3s, or a MySQL table 16* No resampling is allowed, so CPU is saved. 17* MP3s/OGGs are played randomly or in alphabetic order, without repeating twice a song. 18 You can loop the whole playlist at its end. 19* When IceGenerator quits, finish its last song first. 20* IceGenerator status is optionally reported to syslog/log file. 21* Very useful when used with crond. 22* ID3 support 23 24============ REQUIREMENTS ============ 25* Linux 2.x/FreeBSD/NetBSD/MacOS/Solaris/OpenBSD. 26* You have to install libshout2. You can find it at http://www.icecast.org/download.html. 27* For ID3 support, you have to install id3lib. You can find it at http://id3lib.sourceforge.net 28* An IceCast/Shoutcast server. 29* An Intel 486-like CPU class (maybe a fast 386-like will work). 30* A good broadband connection. 31 32 33============ INSTALL ============ 34Just type: 35 36./configure 37make 38make install 39 40Configure options: 41 --with-id3 adds ID3 support 42 --with-mysql adds MySQL support 43 --with-pgsql adds PostGreSQL support 44 45Binary is installed in /usr/local/bin as default. 46It requires a configuration file, located in /usr/local/etc as default, 47that indicates mp3s/oggs paths and all the stuff related to connection to Icecast. 48A sample configuration file is in etc/ directory of this package. 49All mp3s MUST HAVE .mp3 extension, and oggs MUST HAVE .ogg extension. Case is 50irrilevant. 51 52Configure your streaming server properly. The default user for Icecast-2.0 is "source", 53but you can change as you want. You can also set a mount point different from "/", so you 54an many instances of icegenerator at once (each one with a different mount point, obviously). 55 56Then type "icegenerator" and put on your stream player (like XMMS). If you can't 57hear music, maybe your volume is too low :-D 58 59More options (like icegenerator.conf path, deamon start) are available 60at command line. Type "icegeneator -h" for synopsys. 61 62To quit this daemon, just run "killall icegenerator", and wait for last 63song to finish. 64 65Really simple, uh? 66 67NOTE: 68Some players (like WinAmp, XMMS, etc.) requires a valid mount point for OGG files. They 69need .OGG extension, cause MIME header isn't evaluated. Keep in mind it ... 70 71 72============ CONFIGURATION ============ 73All configuration options are listed in icegenerator.conf file that usually 74resides in /usr/local/etc of your sistem. 75 76Each line that starts with a '#' is treated as a comment. 77 78*** Server section *** 79All option in server section are required. 80 81- IP: Specify here your IceCast/ShoutCast server IP 82- PORT: Specify here your IceCast/ShoutCast server port 83- SERVER: Specify what protocol your IceCast/ShoutCast uses. Refer to your 84 stream server documentation for further details. Only two protocols are 85 supported, ICY and HTTP. 86- MOUNT: Specify mount point for clients, that is where they find your stream 87 server in http path. For example, setting MOUNT as /my_stream requires that 88 clients use URL http://your_server:your_port/my_stream. REMEMBER TO SET A VIRTUAL 89 MOUNT POINT HERE FOR OGG STREAMING. MANY PLAYERS (LIKE WINAMP, XMMS, ETC.) CAN'T 90 AUTO RECOGNIZE OGG STREAMING WITHOUT .OGG EXTENSION 91 92*** User section *** 93All option in user section are required. 94 95- USER: Specify which user has streaming rights. As far as I know, IceCast uses 96 "source" as default, but u can use anything else, cause it's ignored. However 97 you can find more informations in your stream server documentation. 98- PASSWORD: Specify password to connect to your stream server. 99 100*** File and playlist section *** 101All option in file and playlist section are required. 102 103- FORMAT: Specify what type of audio data are you going to stream. Only MP3 and OGG 104 files are allowed. Use "0" for OGG, "1" for MP3. 105- MP3PATH: Here is one of strong point of IceGenerator, its capability to accept 106 many ways to search for audio songs. First three chars of this variable specify 107 where are your audio songs, use "PTH" for directories, "SQL" for a MySQL table 108 (only allowed if MySQL support is enabled during compilation), "PQL" for a PostGreSQL 109 table (only allowed if PostGreSQL support is enabled during compilation), "PLS" for .PLS 110 playlist file support, "M3U" for .M3U playlist file support. After a ':' character, 111 you can specify all option that refers to way that you have chosen. 112 + PTH case: you can specify one or more directories separated with ';'. Wrong paths 113 will be skipped. 114 + PQL/SQL case: you have to specify these informations separated with ';' in the 115 following order: 116 % host: your SQL server ip or symbolic name. 117 % port: your SQL server port. If you specify "0", default port will be used. 118 % user: SQL user that has access rights to database that you'll specify. Only 119 SELECT right is required. 120 % password: password for SQL user. 121 % database: database name that contains table that contains audio songs paths. 122 % table: table name that contains audio songs paths. 123 % field: field name that contains audio songs paths. 124 + M3U/PLS case: you have to specify only a playlist file path. 125 126 Examples: 127 + You have two directories full of OGG files, /path1/dir and /my_audio/rock/80s. 128 MP3PATH=pth:/path1/dir;/my_audio/rock/80s 129 130 + You have a MySQL server located at sql.mydomain.com, you have a database called 131 webextra with a table called songsdata and a column called songs. MySQL user 132 that has access rights is called john. 133 MP3PATH=sql:sql.mydomain.com;0;john;secretpassword;webextra;songsdata;songs 134 135- RECURSIVE: When this variable is set to 1, IceGenerator search for audio songs 136 in subdirectories of directories specified in MP3PATH. Obviously, it is ignored 137 when you use MySQL as source data. 138 139- DUMPFILE: Specify a file where stream is saved. 140 141- LOOP: If set, playlist is looped at its end. 142 143- SHUFFLE: If set, playlist is played randomly. 144 145*** Information section *** 146- NAME: 147- GENRE: 148- DESCRIPTION: 149- URL: Specify name, genre, description and URL of your stream. 150 151- BITRATE: Specify bitrate of your stream. This value is purely informational, 152 it doesn't affect real bitrate. 153 154- PUBLIC: If set, your URL is published into stream directory server(s). 155 156- METAUPDATE: Specify delay (in seconds) between META information update that 157 is sent to clients. A value of "0" disables META information change, and 158 only NAME value is displayed. 159 160- MDFPATH: Specify path of your global MetaDataFile. See README.IceMetal 161 for more info. 162 163*** Debug and logging information *** 164- LOG: Specify logging type. "0" means no logging at all, "1" logs to system 165 log daemon, "2" logs to /var/log/icegenerator.log. 166 167*** Telnet interface *** 168- DATAPORT: Specify port used for telnet interface. If not specified at all, 169 telnet interface will be disabled. A value of "0" sets default port (8796). 170 171 172============ TELNET INTERFACE ============ 173You can connect to IceGenerator during stream with a TCP connection like telnet. 174Connection port is specified with DATAPORT option. After command is sent, an 175answer is returned and connection is closed. Commands that not require an answer 176have an "OK" string in return. All commands MUST HAVE a '.' character at their end. 177Available commands are: 178- TRACK: returns information about current track. 179- LOOP: returns "1" or "0" if loop is active or not. 180- SHUFFLE: returns "1" or "0" if shuffle is active or not. 181- LOOPON: activates loop. 182- LOOPOFF: deactivates loop. 183- SHUFFLEON: activates shuffle. 184- SHUFFLEOFF: deactivates shuffle. 185 186More commands will be available in future. 187 188============ ID3 AND ICEMETAL ============ 189See README.IceMetal for info. 190 191 192============ ACKNOWLEDGEMENTS ============ 193I'd to thank 194 195 - DIeMONd 196 - TSx7 (alias techtonik) 197 - Stefani Banerian 198 - Michel Hendriks 199 - Jacob Brandup 200 - Patrick Atlas 201 202for help me fixing bugs and suggesting more features. 203 204Many thanks also to SourceForge, FreshMeat, Berlios, SourceWell, IceWalkers for 205hosting and promoting this project. 206 207 208============ CONTACT ============ 209For all suggestion and bug reporting, write to administrator@tortugalabs.it. 210 211 212GOOD LISTENING!!!!!!! 213