Download

Version 0.2.0 is available at ezstream-0.2.0.tar.gz

A windows binary is available as well at ezstream_win32_0.2.0_setup.exe

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 and ogg vorbis 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.

How to use it ?

ezstream is XML config file based. Configuration is done by editing the config file to suit your needs..The following is an example config file :

<ezstream>
   <url>http://localhost:8000/testmount.ogg</url>
   <sourcepassword>hackme</sourcepassword>
   <format>OGGVORBIS</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>
</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 or OGGVORBIS, you must specify which format you input files are in.

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.

Re-encoding

ezstream now supports 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.