ezstream README --------------------------------------- ABOUT EZSTREAM :::::::::::::::: Ezstream is a command line source client for Icecast media streaming servers. It began as the successor of the old "shout" utility, and has since gained a lot of useful features. In its basic mode of operation, it streams media files or data from standard input without re-encoding and thus requires only very little CPU resources. It can also use various external decoders and encoders to re-encode from one format to another, and stream the result to an Icecast server. With re- encoding enabled, ezstream is a very flexible source client. Supported media formats for streaming are MP3, Ogg Vorbis and Ogg Theora. Ezstream natively supports metadata in MP3 (ID3v1 only) and Ogg Vorbis, or many more formats when it is built with the TagLib option. Ezstream is free software and licensed under the GNU General Public License. See the COPYING file for details. PREREQUISITES ::::::::::::::: Ezstream depends on: * libshout 2.2.x (http://www.icecast.org/) * libxml 2.x (http://xmlsoft.org/) Ezstream optionally uses: - For reading metadata from Ogg Vorbis files: * TagLib 1.x (1.4 or newer recommended, will be used via the libtag_c wrapper) (http://developer.kde.org/~wheeler/taglib.html) OR: * libvorbis 1.x (http://www.vorbis.com) Using TagLib is recommended, as it allows ezstream to read metadata from many additional media file types. - For basic non-ASCII charset support in metadata and filenames: * Libiconv, if iconv() is not available in the system libc. (http://www.gnu.org/software/libiconv/) INSTALLATION :::::::::::::: The ezstream software uses the GNU auto-tools to configure, build and install on a variety of systems. Aside from the standard autoconf options of the configure script, a couple of additional options are available: --enable-examplesdir=DIR example configuration files installation directory (default: DATADIR/examples/ezstream) --enable-debug enable memory debugging (default: no) --with-libshout=PFX prefix where the libshout header files and library are installed (default: autodetect) --with-libshout-includes=DIR directory where libshout header files are installed (optional) --with-libshout-libs=DIR directory where libshout is installed (optional) --with-libxml2=PFX prefix where the libxml2 header files and library are installed (default: autodetect) --with-libxml2-includes=DIR directory where libxml2 header files are installed (optional) --with-libxml2-libs=DIR directory where libxml2 is installed (optional) --with-taglib=PFX prefix where the TagLib header files and library are installed (default: autodetect) --with-taglib-includes=DIR directory where TagLib header files are installed (optional) --with-taglib-libs=DIR directory where TagLib is installed (optional) --with-libvorbis=PFX prefix where the Vorbis library header files and library are installed (default: autodetect) --with-libvorbis-includes=DIR directory where Vorbis library header files are installed (optional) --with-libvorbis-libs=DIR directory where the Vorbis libraries are installed (optional) --with-libiconv-prefix[=DIR] search for libiconv in DIR/include and DIR/lib --without-libiconv-prefix don't search for libiconv in includedir and libdir The compilation and installation process then boils down to the usual $ ./configure --help | less # Skim over the available options $ ./configure [options] && make && [sudo] make install # Configure, build and install # [as root] the software If this procedure is unfamiliar to you, please consult the INSTALL file for more detailed instructions. On systems where the libshout installation does not include the required shout.pc file for pkg-config(1), the non-standard ``shout-config'' utility is available. However, the ezstream build system does not support the latter. If this is an issue, configure ezstream with $ ./configure \ LIBSHOUT_CPPFLAGS="$(shout-config --cppflags)" \ LIBSHOUT_CFLAGS="$(shout-config --cflags-only)" \ LIBSHOUT_LIBS="$(shout-config --libs)" When the configuration keeps failing despite having all dependencies installed, take note of the more verbose error messages in config.log. If necessary, it is possible to further customize many build flags through environment variables. See the "influential environment variables" list in the --help output. USAGE ::::::: Once ezstream is successfully installed, type "man ezstream" (without quotes) on the command line for a comprehensive manual. This distribution package also comes with example configuration files that can be used as a guide to configure ezstream. Note that all by itself, ezstream is not particularly useful. It requires a running Icecast server to stream to, which then relays the stream to many listeners. If this comes as a surprise, browse to http://www.icecast.org/ for a lot more information, resources, and other source clients. EXTERNAL DECODERS/ENCODERS :::::::::::::::::::::::::::: Ezstream should be able to work with any media decoder and encoder that fulfills the following requirements: 1. It needs to be executable on the command line and not require a graphical display to function. 2.1. A decoder needs to be capable of sending RAW data to standard output. 2.2. An encoder needs to be capable of reading RAW data from standard input. 2.3. A combined de-/encoder needs to be capable of sending media data that can be streamed to standard output. Media formats that ezstream does not support directly are passed through unaltered. Whether they work or not depends on the level of support offered by the version of libshout ezstream is linked with. The following incomplete list of programs shows a few that are known to work. These are also used in the example configuration files: * MP3 - Decoder: madplay (http://mad.sf.net/) - Encoder: lame (http://lame.sf.net/) * Ogg Vorbis: - Decoder: oggdec - Encoder: oggenc Both utilities are in the vorbis-tools package (http://www.vorbis.com/). * FLAC: - Decoder: flac (http://flac.sf.net/) - Encoder: (None. Not supported by libshout at the time of writing, and thus cannot be used by ezstream.) * Ogg Theora: - Decoder/Encoder: ffmpeg2theora (http://v2v.cc/~j/ffmpeg2theora/) OPERATING SYSTEM SPECIFIC NOTES ::::::::::::::::::::::::::::::::: * Ezstream and SunPRO cc/c99 on Solaris: Ezstream may not build with SunPRO cc/c99 "out of the box" if a threaded libshout was built with gcc. This known issue results in the following error message from the linker: ld: fatal: option -h and building a dynamic executable are incompatible This is related to gcc and GNU ld using different compiler/linker flags, related to POSIX threads, than the SunPRO compilers. These are being passed on to ezstream, where cc or c99 ultimately chokes on them. Ezstream compiles with both cc/c99 and gcc if libshout was built with Sun's compiler. If libshout was built with gcc, compile ezstream with gcc as well.