STREAMCAST - 0.8


DESCRIPTION

Streamcast is a advanced MP3 file streamer for icecast/shoutcast servers. See
http://www.icecast.org for more info on streaming MP3's. This is only a streamer, 
you will need a working icecast/shoutcast server to use this.

The latest version of streamcast can always be gotten at
ftp.cheapnet.net/pub/streamcast


FEATURES

reencodes via lame
random playlists
remote admin console
nativly supports multiple requests
uses ID3 tags
updates metadata to server (for titlestreaming)
uses libshout
supports mountpoints
skip currently playing song, without using signals (ie. kill)
includes web interface to control admin console


REQUIREMENTS

MP3::Info - Retrievable from CPAN and mirrors (http://www.cpan.org)
libshout-perl - Find at http://cvs.icecast.org
libshout - Same place as libshout-perl


INSTALLATION

1: Open streamcast.pl and set $adminport to the TCP port you want to telnet to.
WARNING: There is currently NO password protection for controlling the playlist
2: Simply copy streamcast.pl to any directory in your path.


USAGE

example:
# streamcast.pl -s localhost -p hackme -n "My Stream" -m /rock -u http://www.mymusic.com -l /home/bob/mp3/playlist -g rock -r

This would connect to a local icecast server using the password 'hackme' and
register itself as "My Stream" using genre 'rock' and on mountpoint /rock. It
would also play the songs in the playlist in a random order.


PLAYLISTS

Playlists consist of a file with one filename per line of the songs to stream.
An optional number before each line will tell streamcast what rate to stream file.
If the rate you put, is different than the rate the file is currently encoded at
(and you have lame installed) it will reencode the file to that rate.

comment lines start with #

example entry:
# If this file is at 128, it will reencode it down to 64 (if -R is set)
64 /mnt/songs/tool/Tool - Opiate.mp3

You can include other playlists into your main playlist by using the !include option.
An example entry would be:

#include joe's playlist
!include /home/joe/mp3/playlist


ADMIN CONSOLE

Telnet to the machine running streamcast on the port defined my $adminport in
streamcast.pl. Type 'help' to get a command summary. All places with <n> should
be replaced with the song number.


ADMIN CGI

Copy the streamcast.cgi to your servers cgi-bin and set the settings at the top of
that file to point to your machine running streamcast.pl. Run 'chmod 755 streamcast.cgi'
and you should be all set! This CGI is limited for now, but will gain features (and
a better look) soon. It does everything you can do on the admin console.


HOW IT WORKS (For those who care...)

Streamcast is revloutionary in how it internally handles playlists. When streamcast
starts, it forks into two process; the stream and the playlist process. These two
processes then open a unix domain socket between them for communication. The stream
process has no concept of a playlist. It simply requests which file to play next to
the playlist process and plays it. The playlist process, in addition to opening a
socket to the stream process, also listens for connections on its own TCP port. Once
connected the playlist process multiplexes the sockets to see if there are any commands.
The playlist has two arrays of songs; one is the playlist loaded from a file, the other
is the request array. As songs are requested it places the songs into this array, and
when the stream requests a song, it shifts off the next song in the request queue. If
there are no songs, it goes back to the playlist queue. In random mode, when there are
no requests, it simply returns a random element from the playlist array.

The streamer uses Shout.pm, which uses XS to link to the libshout code. This makes the
streamer fast to prototype and code, while still having the benifits of the speed of
C in sending the raw MP3 streams to the server.

The cool part about spitting the playlist and the stream process, it the stream process
will play any song the playlist tells it to. This allows some cool things to be done
with the playlist process and not having to worry about the internals of the streamer.
The text output of the admin console was designed to be easily read as well as easily
parsed. This allows front end programs such as the CGI to easily implement their own
look and flow, yet easily control the streamer.


AUTHOR

Mike Machado
mike@innercite.com