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 [-hqrVv] -c configfile [-p pidfile]
8     ezstream -s file
9

DESCRIPTION

11     ezstream is a command line source client for media streams, primarily for
12     streaming to Icecast servers.
13
14     It allows the creation of media streams based on input from files or
15     standard input that is piped through an optional external de- and
16     encoder.  As every part of this chain is highly configurable, ezstream
17     can be useful in a large number of streaming setups.
18
19   Command line arguments
20     -c configfile
21             Use the XML configuration in configfile.
22
23     -h      Print a summary of available command line arguments with short
24             descriptions and exit.
25
26     -p pidfile
27             Write the ezstream process ID (a single number) to pidfile.  The
28             file will be written even when it already exists.  A file lock is
29             maintained until the main ezstream process terminates.  If the
30             file cannot be written for any reason, ezstream will log this,
31             but not consider it a fatal error.
32
33     -q      Be more quiet.  Suppress the output that external programs send
34             to standard error.
35
36     -r      Maintain a line of real-time status information about the stream
37             on standard output.  (Implies -q.)
38
39     -s file
40             Run ezstream as a line-based shuffling utility.  If a playlist
41             argument of “-” is given, a list of media file names is read from
42             standard input instead of an input file.  After successfully
43             reading the entire list, it is shuffled and printed to standard
44             output, and ezstream will exit.
45
46     -V      Print the ezstream version number and exit.
47
48     -v      Increase logging verbosity.  May be used up to three times to
49             also include debug logging output.
50
51   Runtime control
52     Ezstream offers limited runtime control via signals.  By sending a signal
53     to the ezstream process, e.g. with the kill(1) utility, a certain action
54     will be triggered.
55
56     SIGHUP
57          Rereads the playlist file after the track that is currently
58          streamed.  If the playlist is not to be shuffled, ezstream attempts
59          to find the previously streamed file and continue with the one fol‐
60          lowing it, or restarts from the beginning of the list otherwise.
61
62     SIGUSR1
63          Skips the currently playing track and moves on to the next in
64          playlist mode, or restarts the current track when streaming a single
65          file.
66
67     SIGUSR2
68          Triggers rereading of metadata for the stream by running the config‐
69          ured program or script.  This is the only meaningful signal when
70          streaming from standard input.
71

CONFIGURATION FILE SYNTAX

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

XML CONFIGURATION

85     In this section, each available element is listed and described.  Note
86     that for this purpose, elements are introduced in their short, i.e. empty
87     form.  In the configuration file, they need to be used as start tag +
88     content + end tag, like in the introductory example shown above.
89
90   Root element
91     <ezstream />
92          (Mandatory.) The configuration file's root element.  It contains all
93          other configuration elements.
94
95   Servers block
96     <servers />
97          This element contains all server blocks as child elements.  Its par‐
98          ent is the <ezstream /> element.
99
100          A configuration file may contain multiple named server configura‐
101          tions.  The stream configuration determines what server configura‐
102          tion should be used.
103
104   Server block
105     <server />
106          (Mandatory.) This element contains a complete server configuration
107          as child elements.  Its parent is the <servers /> element.
108
109   Server configuration
110     <name />
111          Set the name of the server configuration.  This may be referenced in
112          a <stream />.
113
114          The name is case-aware, but not case-sensitive.
115
116          Default: default
117
118     <protocol />
119          Transport protocol used to stream to the server:
120
121          HTTP       Plain-text HTTP.  The <tls /> option defines, if TLS via
122                     RFC2817 or RFC2818 is also attempted.
123          HTTPS      HTTP over TLS.  This option implies that <tls /> is set
124                     to "required".
125          ICY        ICY streaming protocol
126          RoarAudio  RoarAudio streaming protocol
127
128          Default: HTTP
129
130     <hostname />
131          (Mandatory.) The FQDN host name or IP address of the server.
132
133     <port />
134          Port number on which the server is listening.
135
136          Default: 8000
137
138     <user />
139          User to authenticate as on the server.
140
141          Default: source
142
143     <password />
144          (Mandatory.) Password to authenticate with on the server.
145
146     <reconnect_attempts />
147          Number of reconnect attempts in case of connection issues with the
148          server, or 0 (zero) for trying indefinitely.
149
150          Default: 0
151
152     <tls />
153          Configure the TLS encryption requirement for the server connection.
154          Possible values are:
155
156          None        No TLS encryption will be attempted.
157          May         Opportunistic TLS encryption may be used, if the server
158                      supports it
159          Required    TLS encryption is required.  This is the only setting
160                      that is providing security against both passive and
161                      active attackers.
162
163          Default: May
164
165          This option is ignored when <protocol /> is set to HTTPS, which
166          implies a value of Required.
167
168     <tls_cipher_suite />
169          Configure allowed cipher suites for TLS.
170
171          For example (modern cipher suites, PFS, TLS 1.2 or better):
172          HIGH:!RSA:!SHA:!DH:!aNULL:!eNULL:!TLSv1.
173
174          Default: libshout default cipher suite
175
176     <ca_dir />
177          Directory in which OpenSSL finds root CA certificates for validating
178          the HTTPS server identity.
179
180          Default: system default
181
182     <ca_file />
183          Path of a root CA bundle file for validating the HTTPS server iden‐
184          tity.
185
186          Default: system default
187
188     <client_cert />
189          X.503 client certificate and key (in PEM format containing both
190          certificate and key in the same file) for authentication on an HTTPS
191          server.
192
193          Default: no client certificate authentication
194
195   Streams block
196     <streams />
197          This element contains all stream blocks as child elements.  Its par‐
198          ent is the <ezstream /> element.
199
200          Note: While multiple stream configurations are supported by the file
201          format, only the one configuration with the name default will be
202          used by ezstream.
203
204   Stream block
205     <stream />
206          (Mandatory.) This element contains the entire stream configuration
207          as child elements.  Its parent is the <streams /> element.
208
209   Stream configuration
210     <name />
211          Set the name of the stream configuration.
212
213          The name is case-aware, but not case-sensitive.
214
215          Note: At this time, only the stream configuration with the default
216          name is used and must be present.
217
218          Default: default
219
220     <mountpoint />
221          (Mandatory.) Stream mountpoint on the server.
222
223     <public />
224          Boolean setting of whether the broadcast may be listed in a public
225          YP directory, or not.
226
227          0|No|False  The broadcast is private (the default).
228          1|Yes|True  The broadcast is public.
229
230     <intake />
231          Use the intake (input media) configuration with the provided sym‐
232          bolic name for this stream.
233
234          Default: default
235
236     <server />
237          Use the server configuration with the provided symbolic name for
238          this stream.
239
240          Default: default
241
242     <format />
243          (Mandatory.) The stream format.
244
245          Ogg       Ogg media format
246          MP3       MP3 audio format
247          WebM      WebM media format
248          Matroska  Matroska media format
249
250     <encoder />
251          Use the encoder configuration with the provided symbolic name (see
252          below), for (re)encoding the stream.  Not configuring an encoder
253          makes ezstream stream input media files as-is.
254
255          The configured encoder's output stream format must match what is
256          configured in <format />.
257
258     <stream_name />
259          Informational name of the broadcast.
260
261          Default: none
262
263     <stream_url />
264          Informational URL associated with the broadcast, e.g. the web site.
265
266          Default: none
267
268     <stream_genre />
269          Informational genre of the broadcast.
270
271          Default: none
272
273     <stream_description />
274          Informational description of the broadcast.
275
276          Default: none
277
278     <stream_quality />
279          Informational quality setting of the VBR broadcast.
280
281          Default: none
282
283     <stream_bitrate />
284          Informational bitrate setting of the CBR broadcast.
285
286          Default: none
287
288     <stream_samplerate />
289          Informational sample rate of the broadcast audio.
290
291          Default: none
292
293     <stream_channels />
294          Informational number of audio channels of the broadcast.
295
296          Default: none
297
298   Intakes block
299     <intakes />
300          This element contains all intake blocks as child elements.  Its par‐
301          ent is the <ezstream /> element.
302
303          A configuration file may contain multiple named intake configura‐
304          tions.  The stream configuration determines what intake (media
305          input) configuration should be used.
306
307   Intake block
308     <intake />
309          (Mandatory.) This element contains the entire input media configura‐
310          tion as child elements.  Its parent is the <intakes /> element.
311
312   Intake configuration
313     <name />
314          Set the name of the intake configuration.  This may be referenced in
315          a <stream />.
316
317          The name is case-aware, but not case-sensitive.
318
319          Default: default
320
321     <type />
322          Configure the input media type:
323
324          autodetect  Attempt to autodetect, whether the input is a playlist,
325                      or a single media file.  Playlists are detected by their
326                      “.m3u” and “.txt” file name extensions.  (This is the
327                      default.)
328          file        The input is one single media file.
329          playlist    The input is a playlist.  Playlists are a newline-delim‐
330                      ited list of media file path names.  Comments in
331                      playlists are introduced by a ‘#’ sign at the beginning
332                      of a line and ignored by ezstream.
333          program     The input is an executable “Playlist Program”.  See
334                      SCRIPTING for more information.
335          stdin       The input is read from standard input and streamed as-is
336                      without any reencoding.
337
338     <filename />
339          The input media file name; mandatory for all but the stdin type.
340
341     <shuffle />
342          Boolean setting of whether the playlist type media should be shuf‐
343          fled, or not.
344
345          0|No|False  Stream the playlist content sequentially (the default).
346          1|Yes|True  Shuffle the playlist prior to streaming its content.
347
348     <stream_once />
349          Boolean setting of whether ezstream should exit after streaming its
350          media input, or start over.
351
352          0|No|False  Attempt to start over whenever the end of the media
353                      input is reached (the default).
354          1|Yes|True  After streaming all media input, exit.
355
356   Metadata block
357     <metadata />
358          This element contains the entire metadata configuration as child
359          elements.  Its parent is the <ezstream /> element.
360
361   Metadata configuration
362     <program />
363          Set an executable “Metadata Program” to be queried for all metadata
364          on SIGUSR2 or whenever a new track begins.  See SCRIPTING for more
365          information.
366
367          Default: use metadata as contained in media files
368
369     <format_str />
370          Set the format of the string that should be used for the ‘@M@’
371          placeholder, when quering for metadata from an executable.
372
373          Default: @a@ - @t@
374
375     <refresh_interval />
376          Configure a time interval for additional metadata updates via a
377          “Metadata Program”:
378
379          -1  Do not trigger any additional metadata updates (the default).
380          0   Trigger metadata updates at the highest reasonable frequency.
381          >0  Configure the time (in seconds) in between additional metadata
382              updates.
383
384     <normalize_strings />
385          Boolean setting of whether metadata strings should have excess
386          whitespace removed, or not.
387
388          0|No|False  Use metadata strings as-is (the default).
389          1|Yes|True  Trim leading and trailing whitespace, as well as remove
390                      excess whitespace in case that there is more than one in
391                      sequence.
392
393     <no_updates />
394          Boolean setting of whether metadata updates should be suppressed
395          altogether, or not.
396
397          0|No|False  Update metadata in the usual manner (the default).
398          1|Yes|True  Disable all metadata updates, and keep existing metadata
399                      in streams untouched.
400
401   Decoders block
402     <decoders />
403          This element contains all decoder blocks as child elements.  Its
404          parent is the <ezstream /> element.
405
406   Decoder block
407     <decoder />
408          This element contains all configuration of a single decoder.  Its
409          parent is the <decoders /> element.
410
411   Decoder configuration
412     <name />
413          Set the name of the decoder configuration.
414
415          The name is case-aware, but not case-sensitive.
416
417          Default: default
418
419     <program />
420          (Mandatory.) Set the full command line to decode a media input file,
421          represented by the ‘@T@’ placeholder, into a “canonical internal
422          format” on standard output.
423
424          The canonical format should be the same for all configured decoders,
425          e.g. RAW audio with a specific signedness, bitrate, and samplerate
426          that can be consumed by encoders.
427
428          For exotic use cases, metadata placeholders may be used here.
429
430          Example:
431                <program>oggdec -R -o - @T@</program>
432
433     <file_ext />
434          (Mandatory.) Set a filename extension to be associated with this
435          decoder.
436
437          It is possible to specify more than one <file_ext /> element per
438          decoder to associate more than one file extension to the same
439          decoder.
440
441          A filename extension can only be associated with one decoder.
442
443   Encoders block
444     <encoders />
445          This element contains all encoder blocks as child elements.  Its
446          parent is the <ezstream /> element.
447
448   Encoder block
449     <encoder />
450          This element contains all configuration of a single encoder.  Its
451          parent is the <encoders /> element.
452
453   Encoder configuration
454     <name />
455          (Mandatory.) Set the name of the encoder configuration.  This may be
456          referenced in a <stream /> block in case (re)encoding is desired.
457
458          The name is case-aware, but not case-sensitive.
459
460          Default: default
461
462     <format />
463          (Mandatory.) Stream format produced by this encoder.  This must be
464          one of the available stream formats as specified for the <stream />
465          block.
466
467     <program />
468          (Mandatory.) Set the full command line to encode the “canonical
469          internal format” from standard input into a supported stream format
470          on standard output.
471
472          Metadata placeholders may be used here.
473
474          Example:
475                <program>oggenc -r -q 1.5 -t @M@ -</program>
476

SCRIPTING

478     The ezstream utility provides hooks for externally controlled playlist
479     and metadata management.  This is done by running external programs or
480     scripts that need to behave in ways explained here.
481
482   Common Rules
483     -   The program must be an executable file.
484     -   The program must write one line to standard output and exit.
485     -   The program must not require arbitrary command line options to func‐
486         tion.  A wrapper script must be used if there is no other way.
487
488   Playlist Programs
489     -   The program must return only filenames, with one filename per execu‐
490         tion.
491     -   The program should not return an empty line unless ezstream is sup‐
492         posed to know that the end of the playlist has been reached.  This is
493         significant when the <stream_once/> option is enabled.
494
495   Metadata Programs
496     -   The program must not return anything (just a newline character is
497         okay) if it is called by ezstream with a command line argument that
498         the program does not support.
499     -   When called without command line arguments, the program should return
500         a complete string that should be used for metadata.
501     -   When called with the command line argument "artist", the program
502         should return only the artist information of the metadata.
503         (Optional.)
504     -   When called with the command line argument "title", the program
505         should return only the title information of the metadata.
506         (Optional.)
507     -   The supplied metadata must be encoded in UTF-8.
508

METADATA

510     The main tool for handling metadata with ezstream is placeholders in
511     decoder and encoder commands that are replaced with real content during
512     runtime.
513
514     Note: All placeholders are replaced with content enclosed in single
515     quotes, with escaped single quote and backslash characters in between, so
516     that interpretation by the shell does not occur.  Do not add any
517     additional quoting!
518
519   Metadata Placeholders
520     @T@  Replaced with the media file name.  Required in
521          /ezstream/decoders/decoder/program.  Available in
522          /ezstream/metadata/format_str.
523
524     @M@  Replaced with a metadata string.  (See below for a detailed
525          explanation.) Available in /ezstream/decoders/decoder/program and
526          /ezstream/encoders/encoder/program.
527
528     @a@  Replaced with the artist information.  Available in
529          /ezstream/decoders/decoder/program,
530          /ezstream/encoders/encoder/program and
531          /ezstream/metadata/format_str.
532
533     @t@  Replaced with the title information.  Available in
534          /ezstream/decoders/decoder/program,
535          /ezstream/encoders/encoder/program and
536          /ezstream/metadata/format_str.
537
538     @b@  Replaced with the album information.  Available in
539          /ezstream/decoders/decoder/program,
540          /ezstream/encoders/encoder/program and
541          /ezstream/metadata/format_str.
542
543     @s@  Replaced with the string returned by /ezstream/metadata/program when
544          called without any command line arguments.  Available only in
545          /ezstream/metadata/format_str.
546
547   The @M@ Placeholder
548     While all other placeholders are simply replaced with whatever data they
549     are associated with, ‘@M@’ is context-sensitive.  The logic used by
550     ezstream is the following:
551
552           If ('@M@ is present')
553               If (/ezstream/metadata/program AND /ezstream/metadata/format_str)
554                   Replace with format string result.
555               Else
556                   If (NOT /ezstream/metadata/program AND '@t@ is present')
557                       Replace with empty string.
558                   else
559                       Replace with generated metadata string.
560                   Endif
561               Endif
562           Endif
563
564     The generated metadata string for ‘@M@’ is of the format “Artist -
565     Title”, if both artist and title information is available.  If one of the
566     two is missing, the available one is displayed without a leading or
567     trailing dash, e.g. just “Artist”.  If neither artist nor title are
568     available, the name of the media file — without its file extension — is
569     used.
570
571   Metadata Caveats
572     It is possible to generate strange results with odd combinations of
573     placeholders, external metadata programs and updates during runtime via
574     SIGUSR2.  If things start to become just confusing, simplify.
575
576     Metadata updates during runtime are done with a eccentric feature of lib‐
577     shout.  Additional metadata information that is already present in the
578     stream sent via ezstream is usually destroyed and replaced with the new
579     data.  It is not possible to properly discern between artist and title
580     information, which means that anything set with the SIGUSR2 feature will
581     continue to end up entirely in the "Title" field of a stream.
582
583     Additional limitations in Icecast may apply as well, where one historic
584     example is that of all possible Ogg-based streams, only Ogg Vorbis can
585     have its metadata manipulated.
586
587     The ID3v1 tags (relevant when streaming in MP3 format) do not specify any
588     character encoding, so ezstream operates in a manner of “best effort”.
589     In case of encoding issues, it may help to explicitly set a codeset to
590     work with via the LC_CTYPE environment variable, as ezstream assumes
591     ID3v1 tags to be in the user's current locale.  Note that, even though
592     support for different locales is provided by ezstream, Icecast itself and
593     the listening clients also have a say in the matter.  The only way to
594     ensure consistent results with metadata in non-Ogg streams is to use only
595     the characters available in the ISO-8859-1 codeset.
596
597     External encoders may put additional, and possibly artificial, restric‐
598     tions on valid characters in metadata.
599

FILES

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

SEE ALSO

606     ezstream-cfgmigrate(1), ezstream-file.sh(1)
607

AUTHORS

609     ezstream was written by:
610
611     Ed Zaleski <oddsock@oddsock.org>
612     Moritz Grimm <mgrimm@mrsserver.net>
613
614     This manual was written by Moritz Grimm.
615
616ezstream 1.0.2                 February 19, 2021                ezstream 1.0.2
Impressum