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 en‐
16     coder.  As every part of this chain is highly configurable, ezstream can
17     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 ac‐
161                      tive attackers.
162
163          Default: May
164
165          This option is ignored when <protocol /> is set to HTTPS, which im‐
166          plies 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 in‐
353                      put 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 el‐
359          ements.  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 al‐
395          together, 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 de‐
435          coder.
436
437          It is possible to specify more than one <file_ext /> element per de‐
438          coder to associate more than one file extension to the same decoder.
439
440          A filename extension can only be associated with one decoder.
441
442   Encoders block
443     <encoders />
444          This element contains all encoder blocks as child elements.  Its
445          parent is the <ezstream /> element.
446
447   Encoder block
448     <encoder />
449          This element contains all configuration of a single encoder.  Its
450          parent is the <encoders /> element.
451
452   Encoder configuration
453     <name />
454          (Mandatory.) Set the name of the encoder configuration.  This may be
455          referenced in a <stream /> block in case (re)encoding is desired.
456
457          The name is case-aware, but not case-sensitive.
458
459          Default: default
460
461     <format />
462          (Mandatory.) Stream format produced by this encoder.  This must be
463          one of the available stream formats as specified for the <stream />
464          block.
465
466     <program />
467          (Mandatory.) Set the full command line to encode the “canonical
468          internal format” from standard input into a supported stream format
469          on standard output.
470
471          Metadata placeholders may be used here.
472
473          Example:
474                <program>oggenc -r -q 1.5 -t @M@ -</program>
475

SCRIPTING

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

METADATA

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

FILES

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

SEE ALSO

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

AUTHORS

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