Provided by: ezstream_0.5.6~dfsg-1.1_amd64 bug


     ezstream — source client for Icecast with external de-/encoder support


     ezstream [-hnqVv] -c configfile
     ezstream -s [playlist]


     The ezstream utility is a source client for the Icecast media streaming server.  In its
     basic mode of operation, it streams media files and data from standard input "as-is" — such
     as Ogg Vorbis, Ogg Theora and MP3 — to a server.  It can also use various external decoders
     and encoders to re-encode from one format to another, and stream the result.  The only
     requirement is that the external programs support writing to or reading from standard input,
     and can be used from the command line.

   Command line parameters
     -c configfile
             Use the XML configuration in configfile.

     -h      Print a summary of available command line parameters with short descriptions and

     -n      Normalize metadata strings by removing excess whitespaces.

     -q      Be more quiet.  Suppress the output that external programs send to standard error.

     -s [playlist]
             Run ezstream as a line-based shuffling utility.  If no playlist argument is given, a
             list of media file names is read from standard input instead of an input file.
             After successfully reading the entire list, it is shuffled and printed to standard
             output, and ezstream will exit.

     -V      Print the ezstream version number and exit.

     -v      Produce more verbose output from ezstream.  Use twice for even more verbose output.

     When the -q and -v parameters are provided simultaneously, an additional line of information
     about the currently streamed file — playlist position, approximate playing time and bit rate
     — is displayed.

   Runtime control
     On POSIX systems, ezstream offers limited runtime control via signals.  By sending a signal
     to the ezstream process, e.g. with the kill(1) utility, a certain action will be triggered.

          Rereads the playlist file after the track that is currently streamed.  If the playlist
          is not to be shuffled, ezstream attempts to find the previously streamed file and
          continue with the one following it, or restarts from the beginning of the list

          Skips the currently playing track and moves on to the next in playlist mode, or
          restarts the current track when streaming a single file.

          Triggers rereading of metadata for the stream by running the program or script
          specified in <metadata_progname/> (see below.) This is the only meaningful signal when
          streaming from standard input.


     The ezstream utility uses a simple XML configuration file format.  It has a tree-like
     structure and is made up of XML elements.  Of all the possible XML features, only regular
     elements that contain text or other elements, and comments, appear in an ezstream
     configuration file.

     Each element in the configuration file consists of a start tag, its content and an end tag.
     For example:

           <!-- XML comments look like this. -->


     In this section, each available element is listed and described.  Note that for this
     purpose, elements are introduced in their short, i.e. empty form.  In the configuration
     file, they need to be used as start tag + content + end tag, like in the introductory
     example shown above.

   Root element
     <ezstream />
          (Mandatory.) The configuration file's root element.  It contains all other
          configuration elements.

   Global configuration elements
     Each of the global configuration elements have the <ezstream/> element as their parent.

     <url />
          (Mandatory.) Specifies the location and mount point of the Icecast server, to which the
          stream will be sent.  The content must be of the form http://server:port/mountpoint For


     <sourceuser />
          (Optional.) Sets the source username for authentication with the Icecast server.  The
          default user (usually “source”) is used if this element is not provided.

     <sourcepassword />
          (Mandatory.) Sets the source password for authentication with the Icecast server.

     <format />
          (Mandatory.) This element has two different meanings, depending on whether re-encoding
          is enabled or not.  It specifies the output format of the stream if re-encoding is
          enabled.  Otherwise, it specifies the input format of all input files.  Recognized and
          supported values for output stream formats are VORBIS, MP3 and THEORA.  Other values
          will be ignored and cause ezstream to simply pass through the data, which may or may
          not work.

     <filename />
          (Mandatory.) Set the path and name of a single media file, a playlist, the name of an
          external program (see below), or the keyword stdin for streaming from standard input.
          Playlists are recognized by their filename extension and end with either .m3u or .txt.

          A playlist consists of filenames, one entry per line.  Comments in playlists are
          introduced by a ‘#’ sign at the beginning of a line and ignored by ezstream.

     <playlist_program />
          (Optional.) Set to 1 (one) to indicate that the file in <filename/> is actually an
          executable program or script.  If set to 0 (zero), <filename/> content is assumed to be
          a media file, playlist file or the keyword stdin (the default).

          See the SCRIPTING section for details on how the playlist program must behave.

     <shuffle />
          (Optional.) Set to 1 (one) to randomly shuffle the entries of the playlist specified in
          <filename/>.  Files are played sequentially if set to 0 (zero) or when the <shuffle/>
          element is absent.  This option will be ignored if <playlist_program/> is set to 1

     <metadata_progname />
          (Optional.) Set the path and name of an executable program or script that should be
          used by ezstream to set the metadata of the stream.  The program is automatically
          queried when a new track is streamed, or whenever the SIGUSR2 signal is received.

          If the <metadata_progname/> element is present in the configuration, no attempts will
          be made to read metadata from files that are being streamed.  If this behavior is not
          desired, it should be removed or commented out in the configuration file.

          See the SCRIPTING section for details on how the metadata program must behave.

     <metadata_format />
          (Optional.) Set the format of the string that should be used for the ‘@M@’ placeholder
          when setting metadata with an external program or script via <metadata_progname/>.

          See the METADATA section for details on how metadata is handled by ezstream.

     <stream_once />
          Set to 1 (one) in order to stream the content of <filename/> only once, and to 0 (zero)
          for continuous streaming (the default).

     <reconnect_tries />
          Set how many attempts should be made to reconnect to the Icecast server in case the
          connection is interrupted.  The default is to try indefinitely, which is equal to
          setting this configuration option to 0 (zero).

     <svrinfoname />
          (Optional.) Set the name of the broadcast.  Informational only.

     <svrinfourl />
          (Optional.) Set the URL of the web site associated with the broadcast.  Informational

     <svrinfogenre />
          (Optional.) Set the genre of the broadcast.  Informational only, used for YP.

     <svrinfodescription />
          (Optional.) Set the description of the broadcast.  Informational only, used for YP.

     <svrinfobitrate />
          (Optional.) Set the bit rate of the broadcast.  This setting is also purely
          informational and only used for YP.  The value is set by the user and not ezstream, and
          should match the bit rate of the stream.

     <svrinfoquality />
          (Optional.) Set the quality setting of an Ogg Vorbis broadcast.  Informational only and
          needs to be set by the user, used for YP.

     <svrinfochannels />
          (Optional.) Set the number of audio channels in the broadcast, e.g.  1 (one) for mono
          or 2 for stereo.  Informational only and needs to be set by the user, used for YP.

     <svrinfosamplerate />
          (Optional.) Set the sample rate of the broadcast.  Informational only and needs to be
          set by the user, used for YP.

     <svrinfopublic />
          (Optional.) Set to 1 (one) if the broadcast may be listed in a public YP directory.  If
          set to 0 (zero), the Icecast server will not submit this stream to a YP directory,
          which is also the default if the <svrinfopublic/> element is absent.

     <reencode />
          (Optional.) Element that contains child elements, which specify if and how re-encoding
          should be done.

   Re-encoding settings
     Each of the re-encoding configuration elements have the <reencode/> element as their parent.

     <enable />
          Set to 1 (one) to enable re-encoding.  If set to 0 (zero), no re-encoding will be done,
          which is also the default if the <enable/> element is absent.

     <encdec />
          Element that contains child elements, which specify how to decode and encode a certain
          media file format for streaming.  Each format is described by a separate <encdec/>

   Decoder/Encoder settings
     Each of the decoder/encoder configuration elements have the <encdec/> element as their

     <format />
          This element is used by ezstream to find the appropriate encoder for the output stream
          format specified in the <format/> element inside the global configuration.  For
          consistency reasons, it is recommended that this element is always supplied, even for
          currently unsupported output formats, with content such as VORBIS, MP3, THEORA, FLAC,
          et cetera.

     <match />
          Set the filename extension used to identify a given media file format.  This allows
          ezstream to find the appropriate decoder for a given file.  Should be set to .mp3 for
          MP3, .flac for FLAC, .ogg for Ogg Vorbis, and so on.

     <decode />
          Set the command to decode the specified media file format to raw data and send it to
          standard output.  During runtime, the placeholder ‘@T@’ is replaced with the name of
          the media file, as it is specified in the <filename/> element or contained in a
          playlist file.  It should always be enclosed in quotes, to prevent problems with
          filenames that contain whitespaces.

          Metadata placeholders can be used in the <decode/> element as well, for combined
          de-/encoder programs that produce data that can be streamed.  See the METADATA section
          for details on how metadata is handled by ezstream.

          For example, to decode Ogg Vorbis files using the oggdec utility:

                <decode>oggdec -R -o - "@T@"</decode>

     <encode />
          Set the command to encode raw data, received from standard input, to the specified
          stream format.

          Metadata placeholders can be used in the <encode/> element.  For details about using
          metadata in ezstream, see below in the METADATA section.

          For example, to encode an Ogg Vorbis stream using the quality setting 1.5 with the
          oggenc utility:

                <encode>oggenc -r -q 1.5 -t "@M@" -</encode>


     The ezstream utility provides hooks for externally controlled playlist and metadata
     management.  This is done by running external programs or scripts that need to behave in
     ways explained here.

   Common Rules
     -   The program must be an executable file.
     -   The program must write one line to standard output and exit.
     -   The program must not require arbitrary command line options to function.  A wrapper
         script must be used if there is no other way.

   Playlist Programs
     -   The program must return only filenames, with one filename per execution.
     -   The program should not return an empty line unless ezstream is supposed to know that the
         end of the playlist has been reached.  This is significant when the <stream_once/>
         option is enabled.

   Metadata Programs
     -   The program must not return anything (just a newline character is okay) if it is called
         by ezstream with a command line parameter that the program does not support.
     -   When called without command line parameters, the program should return a complete string
         that should be used for metadata.
     -   When called with the command line parameter "artist", the program should return only the
         artist information of the metadata.  (Optional.)
     -   When called with the command line parameter "title", the program should return only the
         title information of the metadata.  (Optional.)
     -   The supplied metadata must be encoded in UTF-8.


     The main tool for handling metadata with ezstream is placeholders in decoder and encoder
     commands that are replaced with real content during runtime.  The tricky part is that one of
     the placeholders has to be handled differently, depending on where the metadata comes from.
     This section will explain each possible scenario.

   Metadata Placeholders
     @T@  Replaced with the media file name.  Required in <decode/> and is available in

     @M@  Replaced with a metadata string.  See below for a detailed explanation.  Available in
          <decode/> and <encode/>.

     @a@  Replaced with the artist information.  Available in <decode/>, <encode/> and

     @t@  Replaced with the title information.  Available in <decode/>, <encode/> and

     @s@  Replaced with the string returned by <metadata_progname/> when called without any
          command line parameters.  Available only in <metadata_format/>.

   The @M@ Placeholder
     While all other placeholders are simply replaced with whatever data they are associated
     with, ‘@M@’ is context-sensitive.  The logic used by ezstream is the following:

           If ('@M@ is present')
               If ('<metadata_progname/>' AND '<metadata_format/>')
                   Replace with format string result.
                   If (NOT '<metadata_progname/>' AND '@t@ is present')
                       Replace with empty string.
                       Replace with generated metadata string.

     The generated metadata string for ‘@M@’ is of the format “Artist - Title”, if both artist
     and title information is available.  If one of the two is missing, the available one is
     displayed without a leading or trailing dash, e.g. just “Artist”.  If neither artist nor
     title are available, the name of the media file — without its file extension — is used.

   Metadata Caveats
     It is possible to generate strange results with odd combinations of placeholders, external
     metadata programs and updates during runtime via SIGUSR2.  If things start to become just
     confusing, simplify.

     Metadata updates during runtime are done with a relatively broken feature of libshout.
     Additional metadata information that is already present in the stream sent via ezstream is
     usually destroyed and replaced with the new data.  It is not possible to properly discern
     between artist and title information, which means that anything set with the SIGUSR2 feature
     will continue to end up entirely in the "Title" field of a stream.

     Of all possible Ogg-based streams, only Ogg Vorbis can have its metadata manipulated by
     Icecast.  Any attempt of ezstream to update other Ogg metadata is actually a no-op.

     While ezstream tries to do its best with relaying metadata accurately to Icecast, and
     subsequently the listeners, different codesets and locales can pose a problem.  Especially
     when streaming MP3 files, it may help to explicitly set a codeset to work with via the
     LC_CTYPE environment variable, as ezstream assumes ID3v1 tags to be in the user's current
     locale.  Note that, even though support for different locales is provided by ezstream,
     Icecast itself and the listening clients also have a say in the matter.  The only way to
     ensure consistent results with metadata in non-Ogg streams is to use the characters
     available in the ISO-8859-1 codeset.

     External encoders may put additional, and possibly artificial, restrictions on valid
     characters in metadata.


     /usr/share/doc/ezstream/examples  Directory containing example configuration files for
                                       various uses of ezstream, as well as example playlist and
                                       metadata scripts.



     ezstream was written by:

     Ed Zaleski <>
     Moritz Grimm <>

     This manual was written by Moritz Grimm.