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 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 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 ac‐
161 tive attackers.
162 Default: May
164 This option is ignored when <protocol /> is set to HTTPS, which im‐
166 plies 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 in‐
353 put 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 el‐
359 ements. 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 al‐
395 together, 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 de‐
435 coder.
436 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 A filename extension can only be associated with one decoder.
441 Encoders block
443 <encoders />
444 This element contains all encoder blocks as child elements. Its
445 parent is the <ezstream /> element.
446 Encoder block
448 <encoder />
449 This element contains all configuration of a single encoder. Its
450 parent is the <encoders /> element.
451 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 The name is case-aware, but not case-sensitive.
458 Default: default
460 <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 <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 Metadata placeholders may be used here.
472 Example:
474 <program>oggenc -r -q 1.5 -t @M@ -</program>
475
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 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 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 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
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 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 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 @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 @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 @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 @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 @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 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 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 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 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 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 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 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 External encoders may put additional, and possibly artificial, restric‐
597 tions on valid characters in metadata.
598
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
605 ezstream-cfgmigrate(1), ezstream-file.sh(1)
606
608 ezstream was written by:
609 Ed Zaleski <oddsock@oddsock.org>
611 Moritz Grimm <mgrimm@mrsserver.net>
612 This manual was written by Moritz Grimm.
614ezstream 1.0.2 July 19, 2023 ezstream 1.0.2