MP3 Overdog Installation Notes
REQUIREMENTS
- Perl
- PERL modules: Net::AIM Text::Query Text::Query-Advanced Text::Query-Simple Storable
- Installed LAME
- Installed Icecast (1.3)
- Installed Ices (0.2.3)
CONFIGURATION
- edit the variables at the top of overdog_beta_10.pl in the REQUIRED section to reflect your setup.
- edit icecast.conf. only change lines pertainint to hostname, path, and password strings note that you'll need to use mkpasswd if you compiled icecast with crypt support
- edit ices.conf.generic. all you really need to change is the password, which should be in plaintext.
- edit ices.pm. change the $overdog_dir variable. should be the same as in overdog_beta_10.pl
- run your $locate_cmd by hand the first time to generate a list of mp3s. eg. "locate.mp3 > mp3_list"
STARTUP
- start icecast using the provided config file that you edited: /usr/bin/icecast -c /full/path/to/icecast.conf
- run overdog_beta_10.pl:./overdog_beta_10.pl
You should see your bot log into AIM
Your bot will ignore everything you (or anyone else) says to it until you add users:
Supposing my screenname is joeuser and the bot is joebot, I'd add myself by doing the following:
[15:46:53] joeuser: admin password adduser joeuser [15:46:53] joebot: User joeuser added!
From there try issuing the help command:
[15:56:28] joeuser: help
[15:56:29] joebot:
Type ? for additional information on getting started.
You can also visit the online help guide here [http://your.hostname.or.IP:81/overdog].
help [command] gives you help for a specific command.
Here are the commands that I understand: ?, add, all, clear, ff, go, help, last, link, list, more, mv, new, next, play, prev, rand, restart, rm, rw, set, sort,
stats, stop, w, whereis
USAGE
Anything you say to the bot that isn't a keyword (use quotes to escape keywords) is considered a query. The idea is that any user can run find mp3s matching their queries and add tracks to their playlist. When they've got a nice playlist (or at any time) the user issues the play command, and the stream is then available for listening.
General Operational Description
An icecast server is running as a daemon at all times. If you're not familiar with how icecast works, read the docs. But the main point is that you can have a single icecast server running and many streams running at the same time at varous URLs. For each stream you need to have an 'encoder' which just supplies the stream data to the server, which then serves it up to clients that connect.
ices encoder joe -- -- aim user joe listens on http://icecast/joe \ / ices encoder bar |--- icecast ---|-- aim user bar listens on http://icecast/bar / \ ices encoder baz -- -- aim user baz listens on http://icecast/baz Each encoder gets a unique mountpoint on the icecast server.
The overdog.pl script logs on to aim and stays online to receive requests from various users. The NET::Aim perl module calls a subroutine on the reception of an instant message. So the entire program flow begins with an IM and the proper action is taken - either start up an ices stream if the user wants to play something, send a signal to a currently running ices stream to skip, rewind, or stop, or respond with some information to the user.
After this action is performed, nearly all state is lost and we wait for the next message. In this manner we can handle messages from multiple users since no user ever has exclusive control over the system except for the time it takes to parse their message and do its bidding.
overdog.pl interacts with the icecast server via the ices streamer, never directly. Overdog sends signals to the ices processes (there is one for each user that is playing somethign) to manipulate currently playing tracks. Overdog's interaction with ices processes is hacky and unnatural, as ices was not designed to be so dynamic. This is the hack that IS overdog -- essentially an extention to the playlist customizations (via perl or python) that ices allows. We have basically grafted in an AIM robot into the script that usually just asks "what is the next song?".