mirror of
https://gitlab.xiph.org/xiph/ezstream.git
synced 2024-11-03 04:17:18 -05:00
132 lines
4.4 KiB
Markdown
132 lines
4.4 KiB
Markdown
|
# 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/
|