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