README.md 4.4 KB
Newer Older
Moritz Grimm's avatar
Moritz Grimm committed
1 2 3
# About

Ezstream is a command line source client for media streams, primarily for
Moritz Grimm's avatar
Moritz Grimm committed
4
streaming to Icecast servers.
Moritz Grimm's avatar
Moritz Grimm committed
5 6 7 8 9 10

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.

Moritz Grimm's avatar
Moritz Grimm committed
11 12 13 14
It uses libshout 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.
Moritz Grimm's avatar
Moritz Grimm committed
15 16

Ezstream is free software and licensed under the GNU General Public License.
Moritz Grimm's avatar
Moritz Grimm committed
17
See the `COPYING` file for details.
Moritz Grimm's avatar
Moritz Grimm committed
18 19


Moritz Grimm's avatar
Moritz Grimm committed
20
# Dependencies
Moritz Grimm's avatar
Moritz Grimm committed
21 22

Ezstream depends on:
Moritz Grimm's avatar
Moritz Grimm committed
23 24 25 26 27

 - [libshout](https://www.icecast.org/download/) version 2.2.x or newer
 - [libxml](http://xmlsoft.org/) version 2.x
 - [TagLib](https://taglib.github.io/) for C version 1.x (1.4 or newer
   recommended)
Moritz Grimm's avatar
Moritz Grimm committed
28 29 30

Ezstream optionally uses:

Moritz Grimm's avatar
Moritz Grimm committed
31 32 33 34 35 36 37
 - [libiconv](https://www.gnu.org/software/libiconv/) on systems where
   `iconv()` is not available in libc, for basic non-ASCII charset support in
   metadata and filenames

Building ezstream depends on:

 - [check](https://libcheck.github.io/check) unit testing framework for C
Moritz Grimm's avatar
Moritz Grimm committed
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106

# 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:

Moritz Grimm's avatar
Moritz Grimm committed
107
 - MP3
Moritz Grimm's avatar
Moritz Grimm committed
108 109 110
   - Decoder: madplay (https://www.underbit.com/products/mad/)
   - Encoder: lame (https://lame.sourceforge.io/)

Moritz Grimm's avatar
Moritz Grimm committed
111
 - Ogg Vorbis (https://xiph.org/vorbis/):
Moritz Grimm's avatar
Moritz Grimm committed
112 113 114
   - Decoder: oggdec
   - Encoder: oggenc

Moritz Grimm's avatar
Moritz Grimm committed
115
 - FLAC (https://xiph.org/flac/):
Moritz Grimm's avatar
Moritz Grimm committed
116 117 118
   - Decoder: flac
   - Encoder: flac (requires Ogg FLAC output)

Moritz Grimm's avatar
Moritz Grimm committed
119
 - Ogg Theora:
Moritz Grimm's avatar
Moritz Grimm committed
120 121 122 123 124
   - Decoder/Encoder: ffmpeg2theora (http://v2v.cc/~j/ffmpeg2theora/)


# Development

Moritz Grimm's avatar
Moritz Grimm committed
125 126 127 128 129 130
 - 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/
 - Coverity: https://scan.coverity.com/projects/xiph-ezstream/