mirror of
https://gitlab.xiph.org/xiph/ezstream.git
synced 2024-12-04 14:46:31 -05:00
194 lines
7.0 KiB
Plaintext
194 lines
7.0 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.x
|
|
(http://www.icecast.org/)
|
|
* libxml 2.x
|
|
(http://xmlsoft.org/)
|
|
* TagLib 1.x (1.4 or newer recommended, will be used via the libtag_c
|
|
wrapper)
|
|
(https://taglib.github.io/)
|
|
* Check Unit testing framework for C
|
|
(https://libcheck.github.io/check)
|
|
|
|
Ezstream optionally uses:
|
|
- For basic non-ASCII charset support in metadata and filenames:
|
|
* Libiconv, if iconv() is not available in the system libc.
|
|
(https://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.
|
|
|
|
To bootstrap a fresh checkout from source control, run the `autogen.sh`
|
|
script.
|
|
|
|
|
|
|
|
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/)
|
|
|
|
|
|
|
|
DEVELOPMENT
|
|
:::::::::::::
|
|
|
|
|
|
* GitHub mirror: https://github.com/xiph/ezstream
|
|
|
|
* Travis CI: https://travis-ci.org/xiph/ezstream
|
|
|
|
* CircleCI: https://circleci.com/gh/xiph/ezstream
|
|
|
|
* Codecov: https://codecov.io/gh/xiph/ezstream
|
|
|
|
* Codacy: https://www.codacy.com/app/mgrimm/ezstream
|