1EZSTREAM(1) BSD General Commands Manual EZSTREAM(1)
2
4 ezstream — source client for Icecast with external de-/encoder support
5
7 ezstream [-hmnqVv] -c configfile
8 ezstream -s [playlist]
9
11 The ezstream utility is a source client for the Icecast media streaming
12 server. In its basic mode of operation, it streams media files and data
13 from standard input "as-is" — such as Ogg Vorbis, Ogg Theora and MP3 — to
14 a server. It can also use various external decoders and encoders to re-
15 encode from one format to another, and stream the result. The only
16 requirement is that the external programs support writing to or reading
17 from standard input, and can be used from the command line.
18 Command line parameters
20 -c configfile
21 Use the XML configuration in configfile.
22 -h Print a summary of available command line parameters with short
24 descriptions and exit.
25 -m Disable all metadata updates and keep existing metadata in
27 streams untouched.
28 -n Normalize metadata strings by removing excess whitespaces.
30 -q Be more quiet. Suppress the output that external programs send
32 to standard error.
33 -s [playlist]
35 Run ezstream as a line-based shuffling utility. If no playlist
36 argument is given, a list of media file names is read from stan‐
37 dard input instead of an input file. After successfully reading
38 the entire list, it is shuffled and printed to standard output,
39 and ezstream will exit.
40 -V Print the ezstream version number and exit.
42 -v Produce more verbose output from ezstream. Use twice for even
44 more verbose output.
45 When the -q and -v parameters are provided simultaneously, an additional
47 line of information about the currently streamed file — playlist posi‐
48 tion, approximate playing time and bit rate — is displayed.
49 Runtime control
51 On POSIX systems, ezstream offers limited runtime control via signals.
52 By sending a signal to the ezstream process, e.g. with the kill(1) util‐
53 ity, a certain action will be triggered.
54 SIGHUP
56 Rereads the playlist file after the track that is currently
57 streamed. If the playlist is not to be shuffled, ezstream attempts
58 to find the previously streamed file and continue with the one fol‐
59 lowing it, or restarts from the beginning of the list otherwise.
60 SIGUSR1
62 Skips the currently playing track and moves on to the next in
63 playlist mode, or restarts the current track when streaming a single
64 file.
65 SIGUSR2
67 Triggers rereading of metadata for the stream by running the program
68 or script specified in <metadata_progname/> (see below.) This is the
69 only meaningful signal when streaming from standard input.
70
72 The ezstream utility uses a simple XML configuration file format. It has
73 a tree-like structure and is made up of XML elements. Of all the possi‐
74 ble XML features, only regular elements that contain text or other ele‐
75 ments, and comments, appear in an ezstream configuration file.
76 Each element in the configuration file consists of a start tag, its con‐
78 tent and an end tag. For example:
79 <filename>playlist.m3u</filename>
81 <!-- XML comments look like this. -->
82
84 In this section, each available element is listed and described. Note
85 that for this purpose, elements are introduced in their short, i.e. empty
86 form. In the configuration file, they need to be used as start tag +
87 content + end tag, like in the introductory example shown above.
88 Root element
90 <ezstream />
91 (Mandatory.) The configuration file's root element. It contains all
92 other configuration elements.
93 Global configuration elements
95 Each of the global configuration elements have the <ezstream/> element as
96 their parent.
97 <url />
99 (Mandatory.) Specifies the location and mount point of the Icecast
100 server, to which the stream will be sent. The content must be of
101 the form http://server:port/mountpoint For example:
102 <url>http://example.com:8000/stream.ogg</url>
104 <sourceuser />
106 (Optional.) Sets the source username for authentication with the
107 Icecast server. The default user (usually “source”) is used if this
108 element is not provided.
109 <sourcepassword />
111 (Mandatory.) Sets the source password for authentication with the
112 Icecast server.
113 <format />
115 (Mandatory.) This element has two different meanings, depending on
116 whether re-encoding is enabled or not. It specifies the output
117 format of the stream if re-encoding is enabled. Otherwise, it spec‐
118 ifies the input format of all input files. Recognized and supported
119 values for output stream formats are VORBIS, MP3 and THEORA. Other
120 values will be ignored and cause ezstream to simply pass through the
121 data, which may or may not work.
122 <filename />
124 (Mandatory.) Set the path and name of a single media file, a
125 playlist, the name of an external program (see below), or the key‐
126 word stdin for streaming from standard input. Playlists are recog‐
127 nized by their filename extension and end with either .m3u or .txt.
128 A playlist consists of filenames, one entry per line. Comments in
130 playlists are introduced by a ‘#’ sign at the beginning of a line
131 and ignored by ezstream.
132 <playlist_program />
134 (Optional.) Set to 1 (one) to indicate that the file in <filename/>
135 is actually an executable program or script. If set to 0 (zero),
136 <filename/> content is assumed to be a media file, playlist file or
137 the keyword stdin (the default).
138 See the SCRIPTING section for details on how the playlist program
140 must behave.
141 <shuffle />
143 (Optional.) Set to 1 (one) to randomly shuffle the entries of the
144 playlist specified in <filename/>. Files are played sequentially if
145 set to 0 (zero) or when the <shuffle/> element is absent. This
146 option will be ignored if <playlist_program/> is set to 1 (one.)
147 <metadata_progname />
149 (Optional.) Set the path and name of an executable program or script
150 that should be used by ezstream to set the metadata of the stream.
151 The program is automatically queried when a new track is streamed,
152 or whenever the SIGUSR2 signal is received.
153 If the <metadata_progname/> element is present in the configuration,
155 no attempts will be made to read metadata from files that are being
156 streamed. If this behavior is not desired, it should be removed or
157 commented out in the configuration file.
158 See the SCRIPTING section for details on how the metadata program
160 must behave.
161 <metadata_format />
163 (Optional.) Set the format of the string that should be used for the
164 ‘@M@’ placeholder when setting metadata with an external program or
165 script via <metadata_progname/>.
166 See the METADATA section for details on how metadata is handled by
168 ezstream.
169 <metadata_refreshinterval />
171 (Optional.) Configures the time (in seconds) inbetween additional
172 metadata updates via <metadata_progname/>. A value of 0 (zero)
173 triggers updates as fast as possible, while a value of -1 (minus
174 one) or the absence of this configuration element disables this fea‐
175 ture.
176 <stream_once />
178 Set to 1 (one) in order to stream the content of <filename/> only
179 once, and to 0 (zero) for continuous streaming (the default).
180 <reconnect_tries />
182 Set how many attempts should be made to reconnect to the Icecast
183 server in case the connection is interrupted. The default is to try
184 indefinitely, which is equal to setting this configuration option to
185 0 (zero).
186 <svrinfoname />
188 (Optional.) Set the name of the broadcast. Informational only.
189 <svrinfourl />
191 (Optional.) Set the URL of the web site associated with the broad‐
192 cast. Informational only.
193 <svrinfogenre />
195 (Optional.) Set the genre of the broadcast. Informational only,
196 used for YP.
197 <svrinfodescription />
199 (Optional.) Set the description of the broadcast. Informational
200 only, used for YP.
201 <svrinfobitrate />
203 (Optional.) Set the bit rate of the broadcast. This setting is also
204 purely informational and only used for YP. The value is set by the
205 user and not ezstream, and should match the bit rate of the stream.
206 <svrinfoquality />
208 (Optional.) Set the quality setting of an Ogg Vorbis broadcast.
209 Informational only and needs to be set by the user, used for YP.
210 <svrinfochannels />
212 (Optional.) Set the number of audio channels in the broadcast, e.g.
213 1 (one) for mono or 2 for stereo. Informational only and needs to
214 be set by the user, used for YP.
215 <svrinfosamplerate />
217 (Optional.) Set the sample rate of the broadcast. Informational
218 only and needs to be set by the user, used for YP.
219 <svrinfopublic />
221 (Optional.) Set to 1 (one) if the broadcast may be listed in a pub‐
222 lic YP directory. If set to 0 (zero), the Icecast server will not
223 submit this stream to a YP directory, which is also the default if
224 the <svrinfopublic/> element is absent.
225 <reencode />
227 (Optional.) Element that contains child elements, which specify if
228 and how re-encoding should be done.
229 Re-encoding settings
231 Each of the re-encoding configuration elements have the <reencode/> ele‐
232 ment as their parent.
233 <enable />
235 Set to 1 (one) to enable re-encoding. If set to 0 (zero), no re-
236 encoding will be done, which is also the default if the <enable/>
237 element is absent.
238 <encdec />
240 Element that contains child elements, which specify how to decode
241 and encode a certain media file format for streaming. Each format
242 is described by a separate <encdec/> element.
243 Decoder/Encoder settings
245 Each of the decoder/encoder configuration elements have the <encdec/>
246 element as their parent.
247 <format />
249 This element is used by ezstream to find the appropriate encoder for
250 the output stream format specified in the <format/> element inside
251 the global configuration. For consistency reasons, it is recom‐
252 mended that this element is always supplied, even for currently
253 unsupported output formats, with content such as VORBIS, MP3,
254 THEORA, FLAC, et cetera.
255 <match />
257 Set the filename extension used to identify a given media file for‐
258 mat. This allows ezstream to find the appropriate decoder for a
259 given file. Should be set to .mp3 for MP3, .flac for FLAC, .ogg for
260 Ogg Vorbis, and so on.
261 <decode />
263 Set the command to decode the specified media file format to raw
264 data and send it to standard output. During runtime, the place‐
265 holder ‘@T@’ is replaced with the name of the media file, as it is
266 specified in the <filename/> element or contained in a playlist
267 file. It should always be enclosed in quotes, to prevent problems
268 with filenames that contain whitespaces.
269 Metadata placeholders can be used in the <decode/> element as well,
271 for combined de-/encoder programs that produce data that can be
272 streamed. See the METADATA section for details on how metadata is
273 handled by ezstream.
274 For example, to decode Ogg Vorbis files using the oggdec utility:
276 <decode>oggdec -R -o - @T@</decode>
278 <encode />
280 Set the command to encode raw data, received from standard input, to
281 the specified stream format.
282 Metadata placeholders can be used in the <encode/> element. For
284 details about using metadata in ezstream, see below in the METADATA
285 section.
286 For example, to encode an Ogg Vorbis stream using the quality set‐
288 ting 1.5 with the oggenc utility:
289 <encode>oggenc -r -q 1.5 -t @M@ -</encode>
291
293 The ezstream utility provides hooks for externally controlled playlist
294 and metadata management. This is done by running external programs or
295 scripts that need to behave in ways explained here.
296 Common Rules
298 - The program must be an executable file.
299 - The program must write one line to standard output and exit.
300 - The program must not require arbitrary command line options to func‐
301 tion. A wrapper script must be used if there is no other way.
302 Playlist Programs
304 - The program must return only filenames, with one filename per execu‐
305 tion.
306 - The program should not return an empty line unless ezstream is sup‐
307 posed to know that the end of the playlist has been reached. This is
308 significant when the <stream_once/> option is enabled.
309 Metadata Programs
311 - The program must not return anything (just a newline character is
312 okay) if it is called by ezstream with a command line parameter that
313 the program does not support.
314 - When called without command line parameters, the program should
315 return a complete string that should be used for metadata.
316 - When called with the command line parameter "artist", the program
317 should return only the artist information of the metadata.
318 (Optional.)
319 - When called with the command line parameter "title", the program
320 should return only the title information of the metadata.
321 (Optional.)
322 - The supplied metadata must be encoded in UTF-8.
323
325 The main tool for handling metadata with ezstream is placeholders in
326 decoder and encoder commands that are replaced with real content during
327 runtime.
328 Note: To prevent malicious shell script in metadata (such as artist and
330 title tags) from being executed, all metadata content is automatically
331 enclosed in single quotes, with escaped single quote and backslash char‐
332 acters inbetween. To prevent this from causing unwanted side-effects (or
333 introducting security risk), placeholders must not be quoted any further.
334 Metadata Placeholders
336 @T@ Replaced with the media file name. Required in <decode/> and is
337 available in <metadata_format/>.
338 @M@ Replaced with a metadata string. See below for a detailed explana‐
340 tion. Available in <decode/> and <encode/>.
341 @a@ Replaced with the artist information. Available in <decode/>,
343 <encode/> and <metadata_format/>.
344 @t@ Replaced with the title information. Available in <decode/>,
346 <encode/> and <metadata_format/>.
347 @s@ Replaced with the string returned by <metadata_progname/> when
349 called without any command line parameters. Available only in
350 <metadata_format/>.
351 The @M@ Placeholder
353 While all other placeholders are simply replaced with whatever data they
354 are associated with, ‘@M@’ is context-sensitive. The logic used by
355 ezstream is the following:
356 If ('@M@ is present')
358 If ('<metadata_progname/>' AND '<metadata_format/>')
359 Replace with format string result.
360 Else
361 If (NOT '<metadata_progname/>' AND '@t@ is present')
362 Replace with empty string.
363 else
364 Replace with generated metadata string.
365 Endif
366 Endif
367 Endif
368 The generated metadata string for ‘@M@’ is of the format “Artist -
370 Title”, if both artist and title information is available. If one of the
371 two is missing, the available one is displayed without a leading or
372 trailing dash, e.g. just “Artist”. If neither artist nor title are
373 available, the name of the media file — without its file extension — is
374 used.
375 Metadata Caveats
377 It is possible to generate strange results with odd combinations of
378 placeholders, external metadata programs and updates during runtime via
379 SIGUSR2. If things start to become just confusing, simplify.
380 Metadata updates during runtime are done with a relatively broken feature
382 of libshout. Additional metadata information that is already present in
383 the stream sent via ezstream is usually destroyed and replaced with the
384 new data. It is not possible to properly discern between artist and
385 title information, which means that anything set with the SIGUSR2 feature
386 will continue to end up entirely in the "Title" field of a stream.
387 Of all possible Ogg-based streams, only Ogg Vorbis can have its metadata
389 manipulated by Icecast. Any attempt of ezstream to update other Ogg
390 metadata is actually a no-op.
391 While ezstream tries to do its best with relaying metadata accurately to
393 Icecast, and subsequently the listeners, different codesets and locales
394 can pose a problem. Especially when streaming MP3 files, it may help to
395 explicitly set a codeset to work with via the LC_CTYPE environment vari‐
396 able, as ezstream assumes ID3v1 tags to be in the user's current locale.
397 Note that, even though support for different locales is provided by
398 ezstream, Icecast itself and the listening clients also have a say in the
399 matter. The only way to ensure consistent results with metadata in non-
400 Ogg streams is to use the characters available in the ISO-8859-1 codeset.
401 External encoders may put additional, and possibly artificial, restric‐
403 tions on valid characters in metadata.
404
406 /usr/share/examples/ezstream Directory containing example configuration
407 files for various uses of ezstream, as well
408 as example playlist and metadata scripts.
409
411 ezstream-file.sh(1)
412
414 ezstream was written by:
415 Ed Zaleski <oddsock@oddsock.org>
417 Moritz Grimm <mgrimm@mrsserver.net>
418 This manual was written by Moritz Grimm.
420ezstream 0.6.0 July 25, 2019 ezstream 0.6.0