mirror of
https://gitlab.xiph.org/xiph/ezstream.git
synced 2024-11-03 04:17:18 -05:00
Modern README.md
This commit is contained in:
Moritz Grimm
parent
900ab170cb
commit
d02e12dd7c
194
README
194
README
@ -1,194 +0,0 @@
|
||||
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
|
||||
131
README.md
Normal file
131
README.md
Normal file
@ -0,0 +1,131 @@
|
||||
# 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/
|
||||
Loading…
Reference in New Issue
Block a user