mirror of
https://gitlab.xiph.org/xiph/ezstream.git
synced 2024-12-04 14:46:31 -05:00
7005fde65c
git-svn-id: https://svn.xiph.org/trunk/ezstream@15787 0101bb08-14d6-0310-b084-bc0e0c8e3800
175 lines
6.2 KiB
Plaintext
175 lines
6.2 KiB
Plaintext
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-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-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)
|
|
|
|
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.
|
|
|
|
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 directly 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.
|