1EZSTREAM(1) BSD General Commands Manual EZSTREAM(1)
2
4 ezstream — source client for Icecast with external de-/encoder support
5
7 ezstream [-hqrVv] -c configfile [-p pidfile]
8 ezstream -s file
9
11 ezstream is a command line source client for media streams, primarily for
12 streaming to Icecast servers.
13 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 Command line arguments
20 -c configfile
21 Use the XML configuration in configfile.
22 -h Print a summary of available command line arguments with short
24 descriptions and exit.
25 -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 -q Be more quiet. Suppress the output that external programs send
34 to standard error.
35 -r Maintain a line of real-time status information about the stream
37 on standard output. (Implies -q.)
38 -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 -V Print the ezstream version number and exit.
47 -v Increase logging verbosity. May be used up to three times to
49 also include debug logging output.
50 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 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 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 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
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 Each element in the configuration file consists of a start tag, its con‐
79 tent, and an end tag. For example:
80 <filename>playlist.m3u</filename>
82 <!-- XML comments look like this. -->
83
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 Root element
91 <ezstream />
92 (Mandatory.) The configuration file's root element. It contains all
93 other configuration elements.
94 Servers block
96 <servers />
97 This element contains all server blocks as child elements. Its par‐
98 ent is the <ezstream /> element.
99 A configuration file may contain multiple named server configura‐
101 tions. The stream configuration determines what server configura‐
102 tion should be used.
103 Server block
105 <server />
106 (Mandatory.) This element contains a complete server configuration
107 as child elements. Its parent is the <servers /> element.
108 Server configuration
110 <name />
111 Set the name of the server configuration. This may be referenced in
112 a <stream />.
113 The name is case-aware, but not case-sensitive.
115 Default: default
117 <protocol />
119 Transport protocol used to stream to the server:
120 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 Default: HTTP
129 <hostname />
131 (Mandatory.) The FQDN host name or IP address of the server.
132 <port />
134 Port number on which the server is listening.
135 Default: 8000
137 <user />
139 User to authenticate as on the server.
140 Default: source
142 <password />
144 (Mandatory.) Password to authenticate with on the server.
145 <reconnect_attempts />
147 Number of reconnect attempts in case of connection issues with the
148 server, or 0 (zero) for trying indefinitely.
149 Default: 0
151 <tls />
153 Configure the TLS encryption requirement for the server connection.
154 Possible values are:
155 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 Default: May
164 This option is ignored when <protocol /> is set to HTTPS, which
166 implies a value of Required.
167 <tls_cipher_suite />
169 Configure allowed cipher suites for TLS.
170 For example (modern cipher suites, PFS, TLS 1.2 or better):
172 HIGH:!RSA:!SHA:!DH:!aNULL:!eNULL:!TLSv1.
173 Default: libshout default cipher suite
175 <ca_dir />
177 Directory in which OpenSSL finds root CA certificates for validating
178 the HTTPS server identity.
179 Default: system default
181 <ca_file />
183 Path of a root CA bundle file for validating the HTTPS server iden‐
184 tity.
185 Default: system default
187 <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 Default: no client certificate authentication
194 Streams block
196 <streams />
197 This element contains all stream blocks as child elements. Its par‐
198 ent is the <ezstream /> element.
199 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 Stream block
205 <stream />
206 (Mandatory.) This element contains the entire stream configuration
207 as child elements. Its parent is the <streams /> element.
208 Stream configuration
210 <name />
211 Set the name of the stream configuration.
212 The name is case-aware, but not case-sensitive.
214 Note: At this time, only the stream configuration with the default
216 name is used and must be present.
217 Default: default
219 <mountpoint />
221 (Mandatory.) Stream mountpoint on the server.
222 <public />
224 Boolean setting of whether the broadcast may be listed in a public
225 YP directory, or not.
226 0|No|False The broadcast is private (the default).
228 1|Yes|True The broadcast is public.
229 <intake />
231 Use the intake (input media) configuration with the provided sym‐
232 bolic name for this stream.
233 Default: default
235 <server />
237 Use the server configuration with the provided symbolic name for
238 this stream.
239 Default: default
241 <format />
243 (Mandatory.) The stream format.
244 Ogg Ogg media format
246 MP3 MP3 audio format
247 WebM WebM media format
248 Matroska Matroska media format
249 <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 The configured encoder's output stream format must match what is
256 configured in <format />.
257 <stream_name />
259 Informational name of the broadcast.
260 Default: none
262 <stream_url />
264 Informational URL associated with the broadcast, e.g. the web site.
265 Default: none
267 <stream_genre />
269 Informational genre of the broadcast.
270 Default: none
272 <stream_description />
274 Informational description of the broadcast.
275 Default: none
277 <stream_quality />
279 Informational quality setting of the VBR broadcast.
280 Default: none
282 <stream_bitrate />
284 Informational bitrate setting of the CBR broadcast.
285 Default: none
287 <stream_samplerate />
289 Informational sample rate of the broadcast audio.
290 Default: none
292 <stream_channels />
294 Informational number of audio channels of the broadcast.
295 Default: none
297 Intakes block
299 <intakes />
300 This element contains all intake blocks as child elements. Its par‐
301 ent is the <ezstream /> element.
302 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 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 Intake configuration
313 <name />
314 Set the name of the intake configuration. This may be referenced in
315 a <stream />.
316 The name is case-aware, but not case-sensitive.
318 Default: default
320 <type />
322 Configure the input media type:
323 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 <filename />
339 The input media file name; mandatory for all but the stdin type.
340 <shuffle />
342 Boolean setting of whether the playlist type media should be shuf‐
343 fled, or not.
344 0|No|False Stream the playlist content sequentially (the default).
346 1|Yes|True Shuffle the playlist prior to streaming its content.
347 <stream_once />
349 Boolean setting of whether ezstream should exit after streaming its
350 media input, or start over.
351 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 Metadata block
357 <metadata />
358 This element contains the entire metadata configuration as child
359 elements. Its parent is the <ezstream /> element.
360 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 Default: use metadata as contained in media files
368 <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 Default: @a@ - @t@
374 <refresh_interval />
376 Configure a time interval for additional metadata updates via a
377 “Metadata Program”:
378 -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 <normalize_strings />
385 Boolean setting of whether metadata strings should have excess
386 whitespace removed, or not.
387 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 <no_updates />
394 Boolean setting of whether metadata updates should be suppressed
395 altogether, or not.
396 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 Decoders block
402 <decoders />
403 This element contains all decoder blocks as child elements. Its
404 parent is the <ezstream /> element.
405 Decoder block
407 <decoder />
408 This element contains all configuration of a single decoder. Its
409 parent is the <decoders /> element.
410 Decoder configuration
412 <name />
413 Set the name of the decoder configuration.
414 The name is case-aware, but not case-sensitive.
416 Default: default
418 <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 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 For exotic use cases, metadata placeholders may be used here.
429 Example:
431 <program>oggdec -R -o - @T@</program>
432 <file_ext />
434 (Mandatory.) Set a filename extension to be associated with this
435 decoder.
436 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 A filename extension can only be associated with one decoder.
442 Encoders block
444 <encoders />
445 This element contains all encoder blocks as child elements. Its
446 parent is the <ezstream /> element.
447 Encoder block
449 <encoder />
450 This element contains all configuration of a single encoder. Its
451 parent is the <encoders /> element.
452 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 The name is case-aware, but not case-sensitive.
459 Default: default
461 <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 <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 Metadata placeholders may be used here.
473 Example:
475 <program>oggenc -r -q 1.5 -t @M@ -</program>
476
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 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 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 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
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 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 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 @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 @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 @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 @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 @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 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 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 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 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 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 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 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 External encoders may put additional, and possibly artificial, restric‐
598 tions on valid characters in metadata.
599
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
606 ezstream-cfgmigrate(1), ezstream-file.sh(1)
607
609 ezstream was written by:
610 Ed Zaleski <oddsock@oddsock.org>
612 Moritz Grimm <mgrimm@mrsserver.net>
613 This manual was written by Moritz Grimm.
615ezstream 1.0.2 February 19, 2021 ezstream 1.0.2