Commit d02e12dd authored by Moritz Grimm's avatar Moritz Grimm
Browse files

Modern README.md

parent 900ab170
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 Ogg, MP3, WebM, and Matroska.
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)
--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
* Coverity: https://scan.coverity.com/projects/xiph-ezstream
# About
Ezstream is a command line source client for media streams, primarily for
Icecast servers.
It allows the creation of media streams based on input from files or standard
input that is piped through an optional external de- and encoder. As every
part of this chain is highly configurable, ezstream can be useful in a large
number of streaming setups.
It uses the libshout library to communicate with streaming servers and
currently supports Ogg, MP3, WebM, and Matroska streams using the HTTP, ICY,
and RoarAudio protocols. It uses TagLib to read and manage metadata in
numerous media files.
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
(https://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. Several (additional) configuration options
are available.
Run `./configure --help` to get an overview.
The compilation and installation process then boils down to the usual
```console
$ ./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
```console
$ ./configure \
LIBSHOUT_CPPFLAGS="$(shout-config --cppflags)" \
LIBSHOUT_CFLAGS="$(shout-config --cflags-only)" \
LIBSHOUT_LIBS="$(shout-config --libs)"
```
If needed, verbose configuration error messages can be found in the
`config.log` file.
When working on a fresh checkout from source control, the `autogen.sh` script
must be run first. It requires automake, autoconf, libtool, and gettext.
# Usage
Once ezstream is installed successfully, type `man ezstream` 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.
As ezstream is a source client, a media streaming server like Icecast
must be available to distribute the stream to listening clients. See
(https://www.icecast.org/) for more information and resources.
# External Decoders/Encoders
Ezstream should be able to work with any media decoder and encoder that
fulfills the following requirements:
1. Must be an executable that can be run from the command line without the
need for a graphical display or terminal
2. Decoding software must be able to either
1. write raw audio data to standard output, or
2. write a properly encoded stream ready for distribution to standard
output
3. Encoding software must be able to read raw audio data from standard input
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 (https://www.underbit.com/products/mad/)
- Encoder: lame (https://lame.sourceforge.io/)
* Ogg Vorbis (https://xiph.org/vorbis/):
- Decoder: oggdec
- Encoder: oggenc
* FLAC (https://xiph.org/flac/):
- Decoder: flac
- Encoder: flac (requires Ogg FLAC output)
* Ogg Theora:
- Decoder/Encoder: ffmpeg2theora (http://v2v.cc/~j/ffmpeg2theora/)
# Development
* Xiph.org Gitlab: https://gitlab.xiph.org/xiph/ezstream/
* 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/
* Coverity: https://scan.coverity.com/projects/xiph-ezstream/
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment