ezstream/README

   1 ezstream README
   2 ---------------------------------------
   3
   4
   5
   6 ABOUT EZSTREAM
   7 ::::::::::::::::
   8
   9
  10 Ezstream is a command line source client for Icecast media streaming servers.
  11 It began as the successor of the old "shout" utility, and has since gained a
  12 lot of useful features.
  13
  14 In its basic mode of operation, it streams media files or data from standard
  15 input without re-encoding and thus requires only very little CPU resources. It
  16 can also use various external decoders and encoders to re-encode from one
  17 format to another, and stream the result to an Icecast server. With re-
  18 encoding enabled, ezstream is a very flexible source client.
  19
  20 Supported media formats for streaming are MP3, Ogg Vorbis and Ogg Theora.
  21 Ezstream natively supports metadata in MP3 (ID3v1 only) and Ogg Vorbis, or
  22 many more formats when it is built with the TagLib option.
  23
  24 Ezstream is free software and licensed under the GNU General Public License.
  25 See the COPYING file for details.
  26
  27
  28
  29 PREREQUISITES
  30 :::::::::::::::
  31
  32
  33 Ezstream depends on:
  34  * libshout 2.2.x (http://www.icecast.org/)
  35  * libshout dependencies, such as libogg, libvorbis, libtheora, etc.
  36    (http://www.vorbis.com/ and http://www.theora.org/)
  37  * libxml 2.x (http://xmlsoft.org/)
  38
  39 Ezstream optionally uses:
  40  * TagLib 1.x (1.4 or newer recommended, will be used via the libtag_c
  41    wrapper)
  42    (http://developer.kde.org/~wheeler/taglib.html)
  43  * Libiconv, if iconv() is not available in the system libc.
  44    (http://www.gnu.org/software/libiconv/)
  45
  46
  47
  48 INSTALLATION
  49 ::::::::::::::
  50
  51
  52 The ezstream software uses the GNU auto-tools to configure, build and install
  53 on a variety of systems. Aside from the standard autoconf options of the
  54 configure script, a couple of additional options are available:
  55
  56   --enable-examplesdir=DIR
  57                           example configuration files installation directory
  58                           (default: DATADIR/examples/ezstream)
  59   --enable-debug          enable memory debugging (default: no)
  60   --with-libiconv-prefix[=DIR]
  61                           search for libiconv in DIR/include and DIR/lib
  62   --without-libiconv-prefix
  63                           don't search for libiconv in includedir and libdir
  64   --with-taglib=PREFIX    Prefix where TagLib is installed (default:
  65                           autodetect)
  66   --with-ogg=PREFIX       Prefix where libogg is installed (optional)
  67   --with-vorbis=PREFIX    Prefix where libvorbis is installed (optional)
  68   --with-xml-config=PATH  use xml-config in PATH to find libxml
  69
  70 The compilation and installation process boils down to the usual
  71
  72     $ ./configure --help | less         # Skim over the available options
  73     $ ./configure [options] && make && [sudo] make install
  74                                         # Configure, build and install
  75                                         # [as root] the software
  76
  77 If this procedure is unfamiliar to you, please consult the INSTALL file for
  78 more detailed instructions.
  79
  80
  81
  82 USAGE
  83 :::::::
  84
  85
  86 Once ezstream is successfully installed, type "man ezstream" (without quotes)
  87 on the command line for a comprehensive manual. This distribution package also
  88 comes with example configuration files that can be used as a guide to
  89 configure ezstream.
  90
  91 Note that all by itself, ezstream is not particularly useful. It requires a
  92 running Icecast server to stream to, which then relays the stream to many
  93 listeners. If this comes as a surprise, browse to http://www.icecast.org/ for
  94 a lot more information, resources, and other source clients.
  95
  96
  97
  98 EXTERNAL DECODERS/ENCODERS
  99 ::::::::::::::::::::::::::::
 100
 101
 102 Ezstream should be able to work with any media decoder and encoder that
 103 fulfills the following requirements:
 104
 105  1. It needs to be executable on the command line and not require a graphical
 106     display to function.
 107  2.1. A decoder needs to be capable of sending RAW data to standard output.
 108  2.2. An encoder needs to be capable of reading RAW data from standard input.
 109  2.3. A combined de-/encoder needs to be capable of sending media data that
 110       can be streamed to standard output.
 111
 112 Media formats that ezstream does not support directly are passed through
 113 unaltered. Whether they work or not depends on the level of support offered by
 114 the version of libshout ezstream is linked with.
 115
 116 The following incomplete list of programs shows a few that are known to work.
 117 These are also used in the example configuration files:
 118
 119  * MP3
 120    - Decoder: madplay (http://mad.sf.net/)
 121    - Encoder: lame (http://lame.sf.net/)
 122
 123  * Ogg Vorbis:
 124    - Decoder: oggdec
 125    - Encoder: oggenc
 126    Both utilities are in the vorbis-tools package (http://www.vorbis.com/).
 127
 128  * FLAC:
 129    - Decoder: flac (http://flac.sf.net/)
 130    - Encoder: (None. Not supported by libshout at the time of writing, and
 131               thus cannot be used by ezstream.)
 132
 133  * Ogg Theora:
 134    - Decoder/Encoder: ffmpeg2theora (http://v2v.cc/~j/ffmpeg2theora/)
 135
 136
 137
 138 OPERATING SYSTEM SPECIFIC NOTES
 139 :::::::::::::::::::::::::::::::::
 140
 141
 142  * Ezstream and SunPRO cc/c99 on Solaris:
 143
 144    Ezstream may not build with SunPRO cc/c99 "out of the box" if a threaded
 145    libshout was built with gcc. This known issue results in the following
 146    error message from the linker:
 147
 148      ld: fatal: option -h and building a dynamic executable are incompatible
 149
 150    This is related to gcc and GNU ld using different compiler/linker flags,
 151    related to POSIX threads, than the SunPRO compilers. These are being passed
 152    on to ezstream, where cc or c99 ultimately chokes on them.
 153
 154    Ezstream compiles with both cc/c99 and gcc if libshout was built with Sun's
 155    compiler. If libshout was built with gcc, compile ezstream with gcc as
 156    well.