1EZSTREAM(1)               BSD General Commands Manual              EZSTREAM(1)
2

NAME

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

SYNOPSIS

7     ezstream [-hmnqVv] -c configfile
8     ezstream -s [playlist]
9

DESCRIPTION

11     The ezstream utility is a source client for the Icecast media streaming
12     server.  In its basic mode of operation, it streams media files and data
13     from standard input "as-is" — such as Ogg Vorbis, Ogg Theora and MP3 — to
14     a server.  It can also use various external decoders and encoders to re-
15     encode from one format to another, and stream the result.  The only
16     requirement is that the external programs support writing to or reading
17     from standard input, and can be used from the command line.
18
19   Command line parameters
20     -c configfile
21             Use the XML configuration in configfile.
22
23     -h      Print a summary of available command line parameters with short
24             descriptions and exit.
25
26     -m      Disable all metadata updates and keep existing metadata in
27             streams untouched.
28
29     -n      Normalize metadata strings by removing excess whitespaces.
30
31     -q      Be more quiet.  Suppress the output that external programs send
32             to standard error.
33
34     -s [playlist]
35             Run ezstream as a line-based shuffling utility.  If no playlist
36             argument is given, a list of media file names is read from stan‐
37             dard input instead of an input file.  After successfully reading
38             the entire list, it is shuffled and printed to standard output,
39             and ezstream will exit.
40
41     -V      Print the ezstream version number and exit.
42
43     -v      Produce more verbose output from ezstream.  Use twice for even
44             more verbose output.
45
46     When the -q and -v parameters are provided simultaneously, an additional
47     line of information about the currently streamed file — playlist posi‐
48     tion, approximate playing time and bit rate — is displayed.
49
50   Runtime control
51     On POSIX systems, ezstream offers limited runtime control via signals.
52     By sending a signal to the ezstream process, e.g. with the kill(1) util‐
53     ity, a certain action will be triggered.
54
55     SIGHUP
56          Rereads the playlist file after the track that is currently
57          streamed.  If the playlist is not to be shuffled, ezstream attempts
58          to find the previously streamed file and continue with the one fol‐
59          lowing it, or restarts from the beginning of the list otherwise.
60
61     SIGUSR1
62          Skips the currently playing track and moves on to the next in
63          playlist mode, or restarts the current track when streaming a single
64          file.
65
66     SIGUSR2
67          Triggers rereading of metadata for the stream by running the program
68          or script specified in <metadata_progname/> (see below.) This is the
69          only meaningful signal when streaming from standard input.
70

CONFIGURATION FILE SYNTAX

72     The ezstream utility uses a simple XML configuration file format.  It has
73     a tree-like structure and is made up of XML elements.  Of all the possi‐
74     ble XML features, only regular elements that contain text or other ele‐
75     ments, and comments, appear in an ezstream configuration file.
76
77     Each element in the configuration file consists of a start tag, its con‐
78     tent and an end tag.  For example:
79
80           <filename>playlist.m3u</filename>
81           <!-- XML comments look like this. -->
82

XML CONFIGURATION

84     In this section, each available element is listed and described.  Note
85     that for this purpose, elements are introduced in their short, i.e. empty
86     form.  In the configuration file, they need to be used as start tag +
87     content + end tag, like in the introductory example shown above.
88
89   Root element
90     <ezstream />
91          (Mandatory.) The configuration file's root element.  It contains all
92          other configuration elements.
93
94   Global configuration elements
95     Each of the global configuration elements have the <ezstream/> element as
96     their parent.
97
98     <url />
99          (Mandatory.) Specifies the location and mount point of the Icecast
100          server, to which the stream will be sent.  The content must be of
101          the form http://server:port/mountpoint For example:
102
103                <url>http://example.com:8000/stream.ogg</url>
104
105     <sourceuser />
106          (Optional.) Sets the source username for authentication with the
107          Icecast server.  The default user (usually “source”) is used if this
108          element is not provided.
109
110     <sourcepassword />
111          (Mandatory.) Sets the source password for authentication with the
112          Icecast server.
113
114     <format />
115          (Mandatory.) This element has two different meanings, depending on
116          whether re-encoding is enabled or not.  It specifies the output
117          format of the stream if re-encoding is enabled.  Otherwise, it spec‐
118          ifies the input format of all input files.  Recognized and supported
119          values for output stream formats are VORBIS, MP3 and THEORA.  Other
120          values will be ignored and cause ezstream to simply pass through the
121          data, which may or may not work.
122
123     <filename />
124          (Mandatory.) Set the path and name of a single media file, a
125          playlist, the name of an external program (see below), or the key‐
126          word stdin for streaming from standard input.  Playlists are recog‐
127          nized by their filename extension and end with either .m3u or .txt.
128
129          A playlist consists of filenames, one entry per line.  Comments in
130          playlists are introduced by a ‘#’ sign at the beginning of a line
131          and ignored by ezstream.
132
133     <playlist_program />
134          (Optional.) Set to 1 (one) to indicate that the file in <filename/>
135          is actually an executable program or script.  If set to 0 (zero),
136          <filename/> content is assumed to be a media file, playlist file or
137          the keyword stdin (the default).
138
139          See the SCRIPTING section for details on how the playlist program
140          must behave.
141
142     <shuffle />
143          (Optional.) Set to 1 (one) to randomly shuffle the entries of the
144          playlist specified in <filename/>.  Files are played sequentially if
145          set to 0 (zero) or when the <shuffle/> element is absent.  This
146          option will be ignored if <playlist_program/> is set to 1 (one.)
147
148     <metadata_progname />
149          (Optional.) Set the path and name of an executable program or script
150          that should be used by ezstream to set the metadata of the stream.
151          The program is automatically queried when a new track is streamed,
152          or whenever the SIGUSR2 signal is received.
153
154          If the <metadata_progname/> element is present in the configuration,
155          no attempts will be made to read metadata from files that are being
156          streamed.  If this behavior is not desired, it should be removed or
157          commented out in the configuration file.
158
159          See the SCRIPTING section for details on how the metadata program
160          must behave.
161
162     <metadata_format />
163          (Optional.) Set the format of the string that should be used for the
164          ‘@M@’ placeholder when setting metadata with an external program or
165          script via <metadata_progname/>.
166
167          See the METADATA section for details on how metadata is handled by
168          ezstream.
169
170     <metadata_refreshinterval />
171          (Optional.) Configures the time (in seconds) inbetween additional
172          metadata updates via <metadata_progname/>.  A value of 0 (zero)
173          triggers updates as fast as possible, while a value of -1 (minus
174          one) or the absence of this configuration element disables this fea‐
175          ture.
176
177     <stream_once />
178          Set to 1 (one) in order to stream the content of <filename/> only
179          once, and to 0 (zero) for continuous streaming (the default).
180
181     <reconnect_tries />
182          Set how many attempts should be made to reconnect to the Icecast
183          server in case the connection is interrupted.  The default is to try
184          indefinitely, which is equal to setting this configuration option to
185          0 (zero).
186
187     <svrinfoname />
188          (Optional.) Set the name of the broadcast.  Informational only.
189
190     <svrinfourl />
191          (Optional.) Set the URL of the web site associated with the broad‐
192          cast.  Informational only.
193
194     <svrinfogenre />
195          (Optional.) Set the genre of the broadcast.  Informational only,
196          used for YP.
197
198     <svrinfodescription />
199          (Optional.) Set the description of the broadcast.  Informational
200          only, used for YP.
201
202     <svrinfobitrate />
203          (Optional.) Set the bit rate of the broadcast.  This setting is also
204          purely informational and only used for YP.  The value is set by the
205          user and not ezstream, and should match the bit rate of the stream.
206
207     <svrinfoquality />
208          (Optional.) Set the quality setting of an Ogg Vorbis broadcast.
209          Informational only and needs to be set by the user, used for YP.
210
211     <svrinfochannels />
212          (Optional.) Set the number of audio channels in the broadcast, e.g.
213          1 (one) for mono or 2 for stereo.  Informational only and needs to
214          be set by the user, used for YP.
215
216     <svrinfosamplerate />
217          (Optional.) Set the sample rate of the broadcast.  Informational
218          only and needs to be set by the user, used for YP.
219
220     <svrinfopublic />
221          (Optional.) Set to 1 (one) if the broadcast may be listed in a pub‐
222          lic YP directory.  If set to 0 (zero), the Icecast server will not
223          submit this stream to a YP directory, which is also the default if
224          the <svrinfopublic/> element is absent.
225
226     <reencode />
227          (Optional.) Element that contains child elements, which specify if
228          and how re-encoding should be done.
229
230   Re-encoding settings
231     Each of the re-encoding configuration elements have the <reencode/> ele‐
232     ment as their parent.
233
234     <enable />
235          Set to 1 (one) to enable re-encoding.  If set to 0 (zero), no re-
236          encoding will be done, which is also the default if the <enable/>
237          element is absent.
238
239     <encdec />
240          Element that contains child elements, which specify how to decode
241          and encode a certain media file format for streaming.  Each format
242          is described by a separate <encdec/> element.
243
244   Decoder/Encoder settings
245     Each of the decoder/encoder configuration elements have the <encdec/>
246     element as their parent.
247
248     <format />
249          This element is used by ezstream to find the appropriate encoder for
250          the output stream format specified in the <format/> element inside
251          the global configuration.  For consistency reasons, it is recom‐
252          mended that this element is always supplied, even for currently
253          unsupported output formats, with content such as VORBIS, MP3,
254          THEORA, FLAC, et cetera.
255
256     <match />
257          Set the filename extension used to identify a given media file for‐
258          mat.  This allows ezstream to find the appropriate decoder for a
259          given file.  Should be set to .mp3 for MP3, .flac for FLAC, .ogg for
260          Ogg Vorbis, and so on.
261
262     <decode />
263          Set the command to decode the specified media file format to raw
264          data and send it to standard output.  During runtime, the place‐
265          holder ‘@T@’ is replaced with the name of the media file, as it is
266          specified in the <filename/> element or contained in a playlist
267          file.  It should always be enclosed in quotes, to prevent problems
268          with filenames that contain whitespaces.
269
270          Metadata placeholders can be used in the <decode/> element as well,
271          for combined de-/encoder programs that produce data that can be
272          streamed.  See the METADATA section for details on how metadata is
273          handled by ezstream.
274
275          For example, to decode Ogg Vorbis files using the oggdec utility:
276
277                <decode>oggdec -R -o - @T@</decode>
278
279     <encode />
280          Set the command to encode raw data, received from standard input, to
281          the specified stream format.
282
283          Metadata placeholders can be used in the <encode/> element.  For
284          details about using metadata in ezstream, see below in the METADATA
285          section.
286
287          For example, to encode an Ogg Vorbis stream using the quality set‐
288          ting 1.5 with the oggenc utility:
289
290                <encode>oggenc -r -q 1.5 -t @M@ -</encode>
291

SCRIPTING

293     The ezstream utility provides hooks for externally controlled playlist
294     and metadata management.  This is done by running external programs or
295     scripts that need to behave in ways explained here.
296
297   Common Rules
298     -   The program must be an executable file.
299     -   The program must write one line to standard output and exit.
300     -   The program must not require arbitrary command line options to func‐
301         tion.  A wrapper script must be used if there is no other way.
302
303   Playlist Programs
304     -   The program must return only filenames, with one filename per execu‐
305         tion.
306     -   The program should not return an empty line unless ezstream is sup‐
307         posed to know that the end of the playlist has been reached.  This is
308         significant when the <stream_once/> option is enabled.
309
310   Metadata Programs
311     -   The program must not return anything (just a newline character is
312         okay) if it is called by ezstream with a command line parameter that
313         the program does not support.
314     -   When called without command line parameters, the program should
315         return a complete string that should be used for metadata.
316     -   When called with the command line parameter "artist", the program
317         should return only the artist information of the metadata.
318         (Optional.)
319     -   When called with the command line parameter "title", the program
320         should return only the title information of the metadata.
321         (Optional.)
322     -   The supplied metadata must be encoded in UTF-8.
323

METADATA

325     The main tool for handling metadata with ezstream is placeholders in
326     decoder and encoder commands that are replaced with real content during
327     runtime.
328
329     Note: To prevent malicious shell script in metadata (such as artist and
330     title tags) from being executed, all metadata content is automatically
331     enclosed in single quotes, with escaped single quote and backslash char‐
332     acters inbetween.  To prevent this from causing unwanted side-effects (or
333     introducting security risk), placeholders must not be quoted any further.
334
335   Metadata Placeholders
336     @T@  Replaced with the media file name.  Required in <decode/> and is
337          available in <metadata_format/>.
338
339     @M@  Replaced with a metadata string.  See below for a detailed explana‐
340          tion.  Available in <decode/> and <encode/>.
341
342     @a@  Replaced with the artist information.  Available in <decode/>,
343          <encode/> and <metadata_format/>.
344
345     @t@  Replaced with the title information.  Available in <decode/>,
346          <encode/> and <metadata_format/>.
347
348     @s@  Replaced with the string returned by <metadata_progname/> when
349          called without any command line parameters.  Available only in
350          <metadata_format/>.
351
352   The @M@ Placeholder
353     While all other placeholders are simply replaced with whatever data they
354     are associated with, ‘@M@’ is context-sensitive.  The logic used by
355     ezstream is the following:
356
357           If ('@M@ is present')
358               If ('<metadata_progname/>' AND '<metadata_format/>')
359                   Replace with format string result.
360               Else
361                   If (NOT '<metadata_progname/>' AND '@t@ is present')
362                       Replace with empty string.
363                   else
364                       Replace with generated metadata string.
365                   Endif
366               Endif
367           Endif
368
369     The generated metadata string for ‘@M@’ is of the format “Artist -
370     Title”, if both artist and title information is available.  If one of the
371     two is missing, the available one is displayed without a leading or
372     trailing dash, e.g. just “Artist”.  If neither artist nor title are
373     available, the name of the media file — without its file extension — is
374     used.
375
376   Metadata Caveats
377     It is possible to generate strange results with odd combinations of
378     placeholders, external metadata programs and updates during runtime via
379     SIGUSR2.  If things start to become just confusing, simplify.
380
381     Metadata updates during runtime are done with a relatively broken feature
382     of libshout.  Additional metadata information that is already present in
383     the stream sent via ezstream is usually destroyed and replaced with the
384     new data.  It is not possible to properly discern between artist and
385     title information, which means that anything set with the SIGUSR2 feature
386     will continue to end up entirely in the "Title" field of a stream.
387
388     Of all possible Ogg-based streams, only Ogg Vorbis can have its metadata
389     manipulated by Icecast.  Any attempt of ezstream to update other Ogg
390     metadata is actually a no-op.
391
392     While ezstream tries to do its best with relaying metadata accurately to
393     Icecast, and subsequently the listeners, different codesets and locales
394     can pose a problem.  Especially when streaming MP3 files, it may help to
395     explicitly set a codeset to work with via the LC_CTYPE environment vari‐
396     able, as ezstream assumes ID3v1 tags to be in the user's current locale.
397     Note that, even though support for different locales is provided by
398     ezstream, Icecast itself and the listening clients also have a say in the
399     matter.  The only way to ensure consistent results with metadata in non-
400     Ogg streams is to use the characters available in the ISO-8859-1 codeset.
401
402     External encoders may put additional, and possibly artificial, restric‐
403     tions on valid characters in metadata.
404

FILES

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

SEE ALSO

411     ezstream-file.sh(1)
412

AUTHORS

414     ezstream was written by:
415
416     Ed Zaleski <oddsock@oddsock.org>
417     Moritz Grimm <mgrimm@mrsserver.net>
418
419     This manual was written by Moritz Grimm.
420
421ezstream 0.6.0                   July 25, 2019                  ezstream 0.6.0
Impressum