ezstream/README

ezstream README
------------------------------

WHAT IS IT ?
::::::::::::

ezstream is a command line utility which is a improved version of the old 
"shout" utility.  It enables you to stream mp3 or vorbis files to an icecast 
server without reencoding and thus requires very little CPU.  ezstream is 
controlled via a XML config file (a few examples are provided in the conf
directory).

ezstream can stream mp3, ogg vorbis, and ogg theora files as well as reading from stdin.
ID3v1 tags are supported in mp3 files and all ogg vorbis tags are propagated
as metadata as well.

CONFIG FILE
:::::::::::

The following is an example config file :

<ezstream>
    <url>http://localhost:8000/testmount.ogg</url>
    <sourcepassword>hackme</sourcepassword>
    <format>VORBIS</format>
    <filename>sunking.ogg</filename>
    <svrinfoname>My Stream</svrinfoname>    
    <svrinfourl>http://www.oddsock.org</svrinfourl> 
    <svrinfogenre>RockNRoll</svrinfogenre>
    <svrinfodescription>This is a stream description</svrinfodescription>
    <svrinfobitrate>192</svrinfobitrate>    
    <svrinfoquality>4.0</svrinfoquality>    
    <svrinfochannels>2</svrinfochannels>
    <svrinfosamplerate>44100</svrinfosamplerate>
    <svrinfopublic>1</svrinfopublic>    
    <reencode>
	<enable>0</enable>
    </reencode>
</ezstream>

URL - this URL specified the location and mountpoint of the icecast server 
	  to which the stream will be sent.
SOURCEPASSWORD - the source password for the icecast server
FORMAT - either MP3, VORBIS or THEORA, This is the output format of your stream.
         If you are not reencoding, then this also must be the same format as your
	 input files.
FILENAME - This can be a single file (in which ezstream will stream that
           file over and over continuously) or can be a .m3u file which
           is a playlist of files.  currently, ezstream will go through 
           the files sequentially.  If you specify "stdin" as the filename
           then ezstream will read the input from stdin.
SVRINFONAME - Broadcast name (informational only)
SVRINFOURL - Website associated with the broadcast (informational only)
SVRINFOGENRE - Genre of broadcast (informational only) (used for YP)
SVRINFODESCRIPTION - Description of broadcast (informational only) (used for YP)
SVRINFOBITRATE - Bitrate of broadcast (informational only) (used for YP)
                 It is YOUR responsibility to ensure that the bitrate specified
                 here matches up with your input.  Note that this info is not
                 for anything OTHER than YP listing info.
SVRINFOQUALITY - Used only for OggVorbis streams, similar to the bitrate
                 in that it is used only for informational and YP purposes.
SVRINFOCHANNELS - 1 = MONO, 2 = STEREO (informational only) (used for YP)
SVRINFOSAMPLERATE - (informational only) (used for YP)
SVRINFOPUBLIC - Indicates wether to list this stream in a public YP.
         

REENCODING
:::::::::::::::
ezstream now support reencoding.  This means that your output stream need not
be the same bitrate/samplerate or even format as your input files.

Reencoding is supported via the use of external programs.  When you enable reencoding
you need to make sure of a few things :

1. You define a "decoder" for each type of input file.
2. You define a "encoder" for each possible type of output stream.

So if you had a mixture of mp3 and vorbis files in your playlist, you will need to make
sure that a decoder is provided for each type.  Ezstream will take the output of the 
decoder and send it directly to the specific encoder.  All output of the decoder should
be written to stdout and should be in raw form.  Most decoder support this mode.  Encoders
should all be configured also with raw input and should read it from stdin.

The following decoder/encoders can be used :

For MP3 :
decoder : madplay
encoder : lame

For Vorbis :
decoder : oggdec
encoder : oggenc

For FLAC :
decoder : FLAC
encoder : not yet supported by libshout, and thus not by ezstream.

Additional decoders and encoders may be used, as long as they follow the rules defined above.

The following config file section defines the reencoding parameters :

<reencode>
	<enable>1</enable>
	<encdec>
	<!-- Support for FLAC decoding (input files) -->
		<format>FLAC</format> <!-- format = output stream format -->
		<match>.flac</match>  <!-- match = input file format -->
		<decode>flac -s -d --force-raw-format --sign=signed --endian=little @T@ -o -</decode>
		<encode>Not supported Yet</encode>
	</encdec>
	<encdec>
	<!-- Support for MP3 decoding via madplay, and encoding via LAME -->
		<format>MP3</format>
		<match>.mp3</match>
		<decode>madplay -o raw:- @T@ 2>/dev/null</decode>
		<encode>lame -r -x -b 56 -s 44.1 --resample 22.05 -a - - 2>/dev/null</encode>
	</encdec>
	<encdec>
	<!-- Support for Vorbis decoding via oggdec, and encoding via oggenc -->
		<format>VORBIS</format>
		<match>.ogg</match>
		<decode>oggdec --raw=1 @T@ -o - 2>/dev/null</decode>
		<encode>oggenc -Q -r -q 0 --resample=44100 --downmix -t "@M@" -c STREAMER=ezstream -</encode>
	</encdec>
</reencode>


Note that the following keywords can be used :

@T@ = The fully qualified name of the track being played in the playlist
@M@ = The metadata for the current track

All encoding options (bitrate/samplerate/channels/quality) are set as command line options of
each of the encoders.  Each encoder has slightly different options that control these values.
The examples here can be used as a guide, but please make sure you check the manual for each
encoder for the correct encoding options.  In all cases, the encoder should be configured to
read RAW audio data from stdin.