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 program
69 or script specified in <metadata_progname/> (see below.) This is the
70 only meaningful signal when 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 Default: default
216 <mountpoint />
218 (Mandatory.) Stream mountpoint on the server.
219 <public />
221 Boolean setting of whether the broadcast may be listed in a public
222 YP directory, or not.
223 0|No|False The broadcast is private (the default).
225 1|Yes|True The broadcast is public.
226 <intake />
228 Use the intake (input media) configuration with the provided sym‐
229 bolic name for this stream.
230 Default: default
232 <server />
234 Use the server configuration with the provided symbolic name for
235 this stream.
236 Default: default
238 <format />
240 (Mandatory.) The stream format.
241 Ogg Ogg media format
243 MP3 MP3 audio format
244 WebM WebM media format
245 Matroska Matroska media format
246 <encoder />
248 Use the encoder configuration with the provided symbolic name (see
249 below), for (re)encoding the stream. Not configuring an encoder
250 makes ezstream stream input media files as-is.
251 The configured encoder's output stream format must match what is
253 configured in <format />.
254 <stream_name />
256 Informational name of the broadcast.
257 Default: none
259 <stream_url />
261 Informational URL associated with the broadcast, e.g. the web site.
262 Default: none
264 <stream_genre />
266 Informational genre of the broadcast.
267 Default: none
269 <stream_description />
271 Informational description of the broadcast.
272 Default: none
274 <stream_quality />
276 Informational quality setting of the VBR broadcast.
277 Default: none
279 <stream_bitrate />
281 Informational bitrate setting of the CBR broadcast.
282 Default: none
284 <stream_samplerate />
286 Informational sample rate of the broadcast audio.
287 Default: none
289 <stream_channels />
291 Informational number of audio channels of the broadcast.
292 Default: none
294 Intakes block
296 <intakes />
297 This element contains all intake blocks as child elements. Its par‐
298 ent is the <ezstream /> element.
299 A configuration file may contain multiple named intake configura‐
301 tions. The stream configuration determines what intake (media
302 input) configuration should be used.
303 Intake block
305 <intake />
306 (Mandatory.) This element contains the entire input media configura‐
307 tion as child elements. Its parent is the <intakes /> element.
308 Intake configuration
310 <name />
311 Set the name of the intake configuration. This may be referenced in
312 a <stream />.
313 The name is case-aware, but not case-sensitive.
315 Default: default
317 <type />
319 Configure the input media type:
320 autodetect Attempt to autodetect, whether the input is a playlist,
322 or a single media file. Playlists are detected by their
323 “.m3u” and “.txt” file name extensions. (This is the
324 default.)
325 file The input is one single media file.
326 playlist The input is a playlist. Playlists are a newline-delim‐
327 ited list of media file path names. Comments in
328 playlists are introduced by a ‘#’ sign at the beginning
329 of a line and ignored by ezstream.
330 program The input is an executable “Playlist Program”. See
331 SCRIPTING for more information.
332 stdin The input is read from standard input.
333 <filename />
335 The input media file name; mandatory for all but the stdin type.
336 <shuffle />
338 Boolean setting of whether the playlist type media should be shuf‐
339 fled, or not.
340 0|No|False Stream the playlist content sequentially (the default).
342 1|Yes|True Shuffle the playlist prior to streaming its content.
343 <stream_once />
345 Boolean setting of whether ezstream should exit after streaming its
346 media input, or start over.
347 0|No|False Attempt to start over whenever the end of the media
349 input is reached (the default).
350 1|Yes|True After streaming all media input, exit.
351 Metadata block
353 <metadata />
354 This element contains the entire metadata configuration as child
355 elements. Its parent is the <ezstream /> element.
356 Metadata configuration
358 <program />
359 Set an executable “Metadata Program” to be queried for all metadata
360 on SIGUSR2 or whenever a new track begins. See SCRIPTING for more
361 information.
362 Default: use metadata as contained in media files
364 <format_str />
366 Set the format of the string that should be used for the ‘@M@’
367 placeholder, when quering for metadata from an executable.
368 Default: @a@ - @t@
370 <refresh_interval />
372 Configure a time interval for additional metadata updates via a
373 “Metadata Program”:
374 -1 Do not trigger any additional metadata updates (the default).
376 0 Trigger metadata updates at the highest reasonable frequency.
377 >0 Configure the time (in seconds) in between additional metadata
378 updates.
379 <normalize_strings />
381 Boolean setting of whether metadata strings should have excess
382 whitespace removed, or not.
383 0|No|False Use metadata strings as-is (the default).
385 1|Yes|True Trim leading and trailing whitespace, as well as remove
386 excess whitespace in case that there is more than one in
387 sequence.
388 <no_updates />
390 Boolean setting of whether metadata updates should be suppressed
391 altogether, or not.
392 0|No|False Update metadata in the usual manner (the default).
394 1|Yes|True Disable all metadata updates, and keep existing metadata
395 in streams untouched.
396 Decoders block
398 <decoders />
399 This element contains all decoder blocks as child elements. Its
400 parent is the <ezstream /> element.
401 Decoder block
403 <decoder />
404 This element contains all configuration of a single decoder. Its
405 parent is the <decoders /> element.
406 Decoder configuration
408 <name />
409 Set the name of the decoder configuration.
410 The name is case-aware, but not case-sensitive.
412 Default: default
414 <program />
416 (Mandatory.) Set the full command line to decode a media input file,
417 represented by the ‘@T@’ placeholder, into a “canonical internal
418 format” on standard output.
419 The canonical format should be the same for all configured decoders,
421 e.g. RAW audio with a specific signedness, bitrate, and samplerate
422 that can be consumed by encoders.
423 For exotic use cases, metadata placeholders may be used here.
425 Example:
427 <program>oggdec -R -o - @T@</program>
428 <file_ext />
430 (Mandatory.) Set a filename extension to be associated with this
431 decoder.
432 It is possible to specify more than one <file_ext /> element per
434 decoder to associate more than one file extension to the same
435 decoder.
436 A filename extension can only be associated with one decoder.
438 Encoders block
440 <encoders />
441 This element contains all encoder blocks as child elements. Its
442 parent is the <ezstream /> element.
443 Encoder block
445 <encoder />
446 This element contains all configuration of a single encoder. Its
447 parent is the <encoders /> element.
448 Encoder configuration
450 <name />
451 (Mandatory.) Set the name of the encoder configuration. This may be
452 referenced in a <stream /> block in case (re)encoding is desired.
453 The name is case-aware, but not case-sensitive.
455 Default: default
457 <format />
459 (Mandatory.) Stream format produced by this encoder. This must be
460 one of the available stream formats as specified for the <stream />
461 block.
462 <program />
464 (Mandatory.) Set the full command line to encode the “canonical
465 internal format” from standard input into a supported stream format
466 on standard output.
467 Metadata placeholders may be used here.
469 Example:
471 <program>oggenc -r -q 1.5 -t @M@ -</program>
472
474 The ezstream utility provides hooks for externally controlled playlist
475 and metadata management. This is done by running external programs or
476 scripts that need to behave in ways explained here.
477 Common Rules
479 - The program must be an executable file.
480 - The program must write one line to standard output and exit.
481 - The program must not require arbitrary command line options to func‐
482 tion. A wrapper script must be used if there is no other way.
483 Playlist Programs
485 - The program must return only filenames, with one filename per execu‐
486 tion.
487 - The program should not return an empty line unless ezstream is sup‐
488 posed to know that the end of the playlist has been reached. This is
489 significant when the <stream_once/> option is enabled.
490 Metadata Programs
492 - The program must not return anything (just a newline character is
493 okay) if it is called by ezstream with a command line argument that
494 the program does not support.
495 - When called without command line arguments, the program should return
496 a complete string that should be used for metadata.
497 - When called with the command line argument "artist", the program
498 should return only the artist information of the metadata.
499 (Optional.)
500 - When called with the command line argument "title", the program
501 should return only the title information of the metadata.
502 (Optional.)
503 - The supplied metadata must be encoded in UTF-8.
504
506 The main tool for handling metadata with ezstream is placeholders in
507 decoder and encoder commands that are replaced with real content during
508 runtime.
509 Note: All placeholders are replaced with content enclosed in single
511 quotes, with escaped single quote and backslash characters in between, so
512 that interpretation by the shell does not occur. Do not add any
513 additional quoting!
514 Metadata Placeholders
516 @T@ Replaced with the media file name. Required in
517 /ezstream/decoders/decoder/program. Available in
518 /ezstream/metadata/format_str.
519 @M@ Replaced with a metadata string. (See below for a detailed
521 explanation.) Available in /ezstream/decoders/decoder/program and
522 /ezstream/encoders/encoder/program.
523 @a@ Replaced with the artist information. Available in
525 /ezstream/decoders/decoder/program,
526 /ezstream/encoders/encoder/program and
527 /ezstream/metadata/format_str.
528 @t@ Replaced with the title information. Available in
530 /ezstream/decoders/decoder/program,
531 /ezstream/encoders/encoder/program and
532 /ezstream/metadata/format_str.
533 @b@ Replaced with the album information. Available in
535 /ezstream/decoders/decoder/program,
536 /ezstream/encoders/encoder/program and
537 /ezstream/metadata/format_str.
538 @s@ Replaced with the string returned by /ezstream/metadata/program when
540 called without any command line arguments. Available only in
541 /ezstream/metadata/format_str.
542 The @M@ Placeholder
544 While all other placeholders are simply replaced with whatever data they
545 are associated with, ‘@M@’ is context-sensitive. The logic used by
546 ezstream is the following:
547 If ('@M@ is present')
549 If (/ezstream/metadata/program AND /ezstream/metadata/format_str)
550 Replace with format string result.
551 Else
552 If (NOT /ezstream/metadata/program AND '@t@ is present')
553 Replace with empty string.
554 else
555 Replace with generated metadata string.
556 Endif
557 Endif
558 Endif
559 The generated metadata string for ‘@M@’ is of the format “Artist -
561 Title”, if both artist and title information is available. If one of the
562 two is missing, the available one is displayed without a leading or
563 trailing dash, e.g. just “Artist”. If neither artist nor title are
564 available, the name of the media file — without its file extension — is
565 used.
566 Metadata Caveats
568 It is possible to generate strange results with odd combinations of
569 placeholders, external metadata programs and updates during runtime via
570 SIGUSR2. If things start to become just confusing, simplify.
571 Metadata updates during runtime are done with a eccentric feature of lib‐
573 shout. Additional metadata information that is already present in the
574 stream sent via ezstream is usually destroyed and replaced with the new
575 data. It is not possible to properly discern between artist and title
576 information, which means that anything set with the SIGUSR2 feature will
577 continue to end up entirely in the "Title" field of a stream.
578 Additional limitations in Icecast may apply as well, where one historic
580 example is that of all possible Ogg-based streams, only Ogg Vorbis can
581 have its metadata manipulated.
582 The ID3v1 tags (relevant when streaming in MP3 format) do not specify any
584 character encoding, so ezstream operates in a manner of “best effort”.
585 In case of encoding issues, it may help to explicitly set a codeset to
586 work with via the LC_CTYPE environment variable, as ezstream assumes
587 ID3v1 tags to be in the user's current locale. Note that, even though
588 support for different locales is provided by ezstream, Icecast itself and
589 the listening clients also have a say in the matter. The only way to
590 ensure consistent results with metadata in non-Ogg streams is to use only
591 the characters available in the ISO-8859-1 codeset.
592 External encoders may put additional, and possibly artificial, restric‐
594 tions on valid characters in metadata.
595
597 /usr/share/examples/ezstream Directory containing example configuration
598 files for various uses of ezstream, as well
599 as example playlist and metadata scripts.
600
602 ezstream-cfgmigrate(1), ezstream-file.sh(1)
603
605 ezstream was written by:
606 Ed Zaleski <oddsock@oddsock.org>
608 Moritz Grimm <mgrimm@mrsserver.net>
609 This manual was written by Moritz Grimm.
611ezstream 1.0.1 February 24, 2020 ezstream 1.0.1