« back to all changes in this revision
Viewing changes to doc/ezstream.1.in.in
- browse files at revision 5
- compare with another revision
- download diff
- download tarball
- view history from revision 5
- Committer: Bazaar Package Importer
- Author(s): Romain Beauxis
- Date: 2009-09-27 16:50:53 UTC
- mfrom: (1.1.3 upstream) (3.1.2 squeeze)
- Revision ID: james.westby@ubuntu.com-20090927165053-jkfio6ahwa723q0q
Tags: 0.5.6~dfsg-1
* New upstream release
* Bumped standards version to 3.8.3
* Bumped standards version to 3.8.3
- files added:
- doc/ezstream-file.sh.1.in.in
- files removed:
- doc/ezstream.1.in
- files modified:
- COPYING
added
removed
doc/ezstream.1.in.in
1
.\" $Id: ezstream.1.in.in 16537 2009-08-30 21:55:24Z moritz $
2
.\"
3
.\" Copyright (c) 2007, 2009 Moritz Grimm <mdgrimm@gmx.net>
4
.\"
5
.\" This program is free software; you can redistribute it and/or modify
6
.\" it under the terms of the GNU General Public License version 2 as
7
.\" published by the Free Software Foundation.
8
.\"
9
.\" This program is distributed in the hope that it will be useful,
10
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12
.\" GNU General Public License for more details.
13
.\"
14
.\" You should have received a copy of the GNU General Public License
15
.\" along with this program; if not, write to the Free Software
16
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17
.\"
18
.Dd @BUILD_DATE@
19
.Dt EZSTREAM 1
20
.Os @PACKAGE_NAME@ @PACKAGE_VERSION@
21
.Sh NAME
22
.Nm ezstream
23
.Nd source client for Icecast with external de-/encoder support
24
.Sh SYNOPSIS
25
.Nm
26
.Bk -words
27
.Op Fl hnqVv
28
.Fl c Ar configfile
29
.Ek
30
.Nm
31
.Bk -words
32
.Fl s
33
.Op Ar playlist
34
.Ek
35
.Sh DESCRIPTION
36
The
37
.Nm
38
utility is a source client for the Icecast media streaming server.
39
In its basic mode of operation, it streams media files and data from standard
40
input
41
.Qq as-is
42
\(em such as Ogg Vorbis, Ogg Theora and MP3 \(em to a server.
43
It can also use various external decoders and encoders to re-encode from one
44
format to another, and stream the result.
45
The only requirement is that the external programs support writing to or
46
reading from standard input, and can be used from the command line.
47
.Ss Command line parameters
48
.Bl -tag -width Ds
49
.It Fl c Ar configfile
50
Use the XML configuration in
51
.Ar configfile .
52
.It Fl h
53
Print a summary of available command line parameters with short descriptions
54
and exit.
55
.It Fl n
56
Normalize metadata strings by removing excess whitespaces.
57
.It Fl q
58
Be more quiet.
59
Suppress the output that external programs send to standard error.
60
.It Fl s Op Ar playlist
61
Run
62
.Nm
63
as a line-based shuffling utility.
64
If no
65
.Ar playlist
66
argument is given, a list of media file names is read from standard input
67
instead of an input file.
68
After successfully reading the entire list, it is shuffled and printed to
69
standard output, and
70
.Nm
71
will exit.
72
.It Fl V
73
Print the
74
.Nm
75
version number and exit.
76
.It Fl v
77
Produce more verbose output from
78
.Nm .
79
Use twice for even more verbose output.
80
.El
81
.Pp
82
When the
83
.Fl q
84
and
85
.Fl v
86
parameters are provided simultaneously, an additional line of information about
87
the currently streamed file \(em playlist position, approximate playing time
88
and bit rate \(em is displayed.
89
.Ss Runtime control
90
On POSIX systems,
91
.Nm
92
offers limited runtime control via signals.
93
By sending a signal to the ezstream process, e.g. with the
94
.Xr kill 1
95
utility, a certain action will be triggered.
96
.Bl -tag -width -Ds
97
.It Cd SIGHUP
98
Rereads the playlist file after the track that is currently streamed.
99
If the playlist is not to be shuffled,
100
.Nm
101
attempts to find the previously streamed file and continue with the one
102
following it, or restarts from the beginning of the list otherwise.
103
.It Cd SIGUSR1
104
Skips the currently playing track and moves on to the next in playlist mode, or
105
restarts the current track when streaming a single file.
106
.It Cd SIGUSR2
107
Triggers rereading of metadata for the stream by running the program or script
108
specified in
109
.Li \&<metadata_progname/\&>
110
.Pq see below.
111
This is the only meaningful signal when streaming from standard input.
112
.El
113
.Pp
114
.Sh CONFIGURATION FILE SYNTAX
115
The
116
.Nm
117
utility uses a simple XML configuration file format.
118
It has a tree-like structure and is made up of
119
.Em XML elements .
120
Of all the possible XML features, only regular elements that contain text or
121
other elements, and comments, appear in an
122
.Nm
123
configuration file.
124
.Pp
125
Each element in the configuration file consists of a
126
.Em start tag ,
127
its content and an
128
.Em end tag .
129
For example:
130
.Pp
131
.Dl \&<filename\&>playlist.m3u<\&/filename\&>
132
.Dl \&<\&!-- XML comments look like this. --\&>
133
.Sh XML CONFIGURATION
134
In this section, each available element is listed and described.
135
Note that for this purpose, elements are introduced in their short, i.e. empty
136
form.
137
In the configuration file, they need to be used as
138
.Em start tag + content + end tag ,
139
like in the introductory example shown above.
140
.Ss Root element
141
.Bl -tag -width -Ds
142
.It Sy \&<ezstream\ /\&>
143
.Pq Mandatory.
144
The configuration file's root element.
145
It contains all other configuration elements.
146
.El
147
.Ss Global configuration elements
148
Each of the global configuration elements have the
149
.Li \&<ezstream/\&>
150
element as their parent.
151
.Bl -tag -width -Ds
152
.It Sy \&<url\ /\&>
153
.Pq Mandatory.
154
Specifies the location and mount point of the Icecast server, to which the
155
stream will be sent.
156
The content must be of the form
157
.Pa http://server:port/mountpoint
158
For example:
159
.Pp
160
.Dl \&<url\&>http://example.com:8000/stream.ogg\&</url\&>
161
.It Sy \&<sourceuser\ /\&>
162
.Pq Optional.
163
Sets the source username for authentication with the Icecast server.
164
The default user
165
.Po
166
usually
167
.Dq Li source
168
.Pc
169
is used if this element is not provided.
170
.It Sy \&<sourcepassword\ /\&>
171
.Pq Mandatory.
172
Sets the source password for authentication with the Icecast server.
173
.It Sy \&<format\ /\&>
174
.Pq Mandatory.
175
This element has two different meanings, depending on whether re-encoding is
176
enabled or not.
177
It specifies the
178
.Em output format
179
of the stream if re-encoding is enabled.
180
Otherwise, it specifies the
181
.Em input format
182
of
183
.Sy all
184
input files.
185
Recognized and supported values for output stream formats are
186
.Sy VORBIS ,
187
.Sy MP3
188
and
189
.Sy THEORA .
190
Other values will be ignored and cause
191
.Nm
192
to simply pass through the data, which may or may not work.
193
.It Sy \&<filename\ /\&>
194
.Pq Mandatory.
195
Set the path and name of a single media file, a playlist, the name of an
196
external program
197
.Pq see below ,
198
or the keyword
199
.Pa stdin
200
for streaming from standard input.
201
Playlists are recognized by their filename extension and end with either
202
.Em .m3u
203
or
204
.Em .txt .
205
.Pp
206
A playlist consists of filenames, one entry per line.
207
Comments in playlists are introduced by a
208
.Sq Li #
209
sign at the beginning of a line and ignored by
210
.Nm .
211
.It Sy \&<playlist_program\ /\&>
212
.Pq Optional.
213
Set to
214
.Sy 1
215
.Pq one
216
to indicate that the file in
217
.Li \&<filename/\&>
218
is actually an executable program or script.
219
If set to
220
.Sy 0
221
.Pq zero ,
222
.Li \&<filename/\&>
223
content is assumed to be a media file, playlist file or the keyword
224
.Pa stdin
225
.Pq the default .
226
.Pp
227
See the
228
.Sy SCRIPTING
229
section for details on how the playlist program must behave.
230
.It Sy \&<shuffle\ /\&>
231
.Pq Optional.
232
Set to
233
.Sy 1
234
.Pq one
235
to randomly shuffle the entries of the playlist specified in
236
.Li \&<filename/\&> .
237
Files are played sequentially if set to
238
.Sy 0
239
.Pq zero
240
or when the
241
.Li \&<shuffle/\&>
242
element is absent.
243
This option will be ignored if
244
.Li \&<playlist_program/\&>
245
is set to 1
246
.Pq one.
247
.It Sy \&<metadata_progname\ /\&>
248
.Pq Optional.
249
Set the path and name of an executable program or script that should be used by
250
.Nm
251
to set the metadata of the stream.
252
The program is automatically queried when a new track is streamed, or whenever
253
the
254
.Sy SIGUSR2
255
signal is received.
256
.Pp
257
If the
258
.Li \&<metadata_progname/\&>
259
element is present in the configuration, no attempts will be made to read
260
metadata from files that are being streamed.
261
If this behavior is not desired, it should be removed or commented out in the
262
configuration file.
263
.Pp
264
See the
265
.Sy SCRIPTING
266
section for details on how the metadata program must behave.
267
.It Sy \&<metadata_format\ /\&>
268
.Pq Optional.
269
Set the format of the string that should be used for the
270
.Sq Li @M@
271
placeholder when setting metadata with an external program or script via
272
.Li \&<metadata_progname/\&> .
273
.Pp
274
See the
275
.Sy METADATA
276
section for details on how metadata is handled by
277
.Nm .
278
.It Sy \&<stream_once\ /\&>
279
Set to
280
.Sy 1
281
.Pq one
282
in order to stream the content of
283
.Li \&<filename/\&>
284
only once, and to
285
.Sy 0
286
.Pq zero
287
for continuous streaming
288
.Pq the default .
289
.It Sy \&<reconnect_tries\ /\&>
290
Set how many attempts should be made to reconnect to the Icecast server in case
291
the connection is interrupted.
292
The default is to try indefinitely, which is equal to setting this
293
configuration option to
294
.Sy 0
295
.Pq zero .
296
.It Sy \&<svrinfoname\ /\&>
297
.Pq Optional.
298
Set the name of the broadcast.
299
Informational only.
300
.It Sy \&<svrinfourl\ /\&>
301
.Pq Optional.
302
Set the URL of the web site associated with the broadcast.
303
Informational only.
304
.It Sy \&<svrinfogenre\ /\&>
305
.Pq Optional.
306
Set the genre of the broadcast.
307
Informational only, used for YP.
308
.It Sy \&<svrinfodescription\ /\&>
309
.Pq Optional.
310
Set the description of the broadcast.
311
Informational only, used for YP.
312
.It Sy \&<svrinfobitrate\ /\&>
313
.Pq Optional.
314
Set the bit rate of the broadcast.
315
This setting is also purely informational and only used for YP.
316
The value is set by the user and not
317
.Nm ,
318
and should match the bit rate of the stream.
319
.It Sy \&<svrinfoquality\ /\&>
320
.Pq Optional.
321
Set the quality setting of an Ogg Vorbis broadcast.
322
Informational only and needs to be set by the user, used for YP.
323
.It Sy \&<svrinfochannels\ /\&>
324
.Pq Optional.
325
Set the number of audio channels in the broadcast, e.g.
326
.Sy 1
327
.Pq one
328
for mono or
329
.Sy 2
330
for stereo.
331
Informational only and needs to be set by the user, used for YP.
332
.It Sy \&<svrinfosamplerate\ /\&>
333
.Pq Optional.
334
Set the sample rate of the broadcast.
335
Informational only and needs to be set by the user, used for YP.
336
.It Sy \&<svrinfopublic\ /\&>
337
.Pq Optional.
338
Set to
339
.Sy 1
340
.Pq one
341
if the broadcast may be listed in a public YP directory.
342
If set to
343
.Sy 0
344
.Pq zero ,
345
the Icecast server will not submit this stream to a YP directory, which is also
346
the default if the
347
.Li \&<svrinfopublic/\&>
348
element is absent.
349
.It Sy \&<reencode\ /\&>
350
.Pq Optional.
351
Element that contains child elements, which specify if and how re-encoding
352
should be done.
353
.El
354
.Ss Re-encoding settings
355
Each of the re-encoding configuration elements have the
356
.Li \&<reencode/\&>
357
element as their parent.
358
.Bl -tag -width -Ds
359
.It Sy \&<enable\ /\&>
360
Set to
361
.Sy 1
362
.Pq one
363
to enable re-encoding.
364
If set to
365
.Sy 0
366
.Pq zero ,
367
no re-encoding will be done, which is also the default if the
368
.Li \&<enable/\&>
369
element is absent.
370
.It Sy \&<encdec\ /\&>
371
Element that contains child elements, which specify how to decode and encode
372
a certain media file format for streaming.
373
Each format is described by a separate
374
.Li \&<encdec/\&>
375
element.
376
.El
377
.Ss Decoder/Encoder settings
378
Each of the decoder/encoder configuration elements have the
379
.Li \&<encdec/\&>
380
element as their parent.
381
.Bl -tag -width -Ds
382
.It Sy \&<format\ /\&>
383
This element is used by
384
.Nm
385
to find the appropriate encoder for the output stream format specified in the
386
.Li \&<format/\&>
387
element inside the global configuration.
388
For consistency reasons, it is recommended that this element is always
389
supplied, even for currently unsupported output formats, with content such as
390
.Sy VORBIS ,
391
.Sy MP3 ,
392
.Sy THEORA ,
393
.Sy FLAC ,
394
et cetera.
395
.It Sy \&<match\ /\&>
396
Set the filename extension used to identify a given media file format.
397
This allows
398
.Nm
399
to find the appropriate decoder for a given file.
400
Should be set to
401
.Em .mp3
402
for MP3,
403
.Em .flac
404
for FLAC,
405
.Em .ogg
406
for Ogg Vorbis, and so on.
407
.It Sy \&<decode\ /\&>
408
Set the command to decode the specified media file format to raw data and send
409
it to standard output.
410
During runtime, the placeholder
411
.Sq Li @T@
412
is replaced with the name of the media file, as it is specified in the
413
.Li \&<filename/\&>
414
element or contained in a playlist file.
415
It should always be enclosed in quotes, to prevent problems with filenames that
416
contain whitespaces.
417
.Pp
418
Metadata placeholders can be used in the
419
.Li \&<decode/\&>
420
element as well, for combined de-/encoder programs that produce data that can
421
be streamed.
422
See the
423
.Sy METADATA
424
section for details on how metadata is handled by
425
.Nm .
426
.Pp
427
For example, to decode Ogg Vorbis files using the
428
.Cm oggdec
429
utility:
430
.Pp
431
.Dl \&<decode\&>oggdec -R -o - \&"@T@\&"\&</decode\&>
432
.It Sy \&<encode\ /\&>
433
Set the command to encode raw data, received from standard input, to the
434
specified stream format.
435
.Pp
436
Metadata placeholders can be used in the
437
.Li \&<encode/\&>
438
element.
439
For details about using metadata in
440
.Nm ,
441
see below in the
442
.Sy METADATA
443
section.
444
.Pp
445
For example, to encode an Ogg Vorbis stream using the quality setting 1.5 with
446
the
447
.Cm oggenc
448
utility:
449
.Pp
450
.Dl \&<encode\&>oggenc -r -q 1.5 -t \&"@M@\&" -\&</encode\&>
451
.El
452
.Sh SCRIPTING
453
The
454
.Nm
455
utility provides hooks for externally controlled playlist and metadata
456
management.
457
This is done by running external programs or scripts that need to behave in
458
ways explained here.
459
.Ss Common Rules
460
.Bl -dash -compact
461
.It
462
The program must be an executable file.
463
.It
464
The program must write one line to standard output and exit.
465
.It
466
The program must not require arbitrary command line options to function.
467
A wrapper script must be used if there is no other way.
468
.El
469
.Ss Playlist Programs
470
.Bl -dash -compact
471
.It
472
The program must return only filenames, with one filename per execution.
473
.It
474
The program should not return an empty line unless
475
.Nm
476
is supposed to know that the end of the playlist has been reached.
477
This is significant when the
478
.Li \&<stream_once/\&>
479
option is enabled.
480
.El
481
.Ss Metadata Programs
482
.Bl -dash -compact
483
.It
484
The program must not return anything (just a newline character is okay) if it
485
is called by
486
.Nm
487
with a command line parameter that the program does not support.
488
.It
489
When called without command line parameters, the program should return a
490
complete string that should be used for metadata.
491
.It
492
When called with the command line parameter
493
.Qq Li artist ,
494
the program should return only the artist information of the metadata.
495
.Pq Optional.
496
.It
497
When called with the command line parameter
498
.Qq Li title ,
499
the program should return only the title information of the metadata.
500
.Pq Optional.
501
.It
502
The supplied metadata must be encoded in UTF-8.
503
.El
504
.Sh METADATA
505
The main tool for handling metadata with
506
.Nm
507
is placeholders in decoder and encoder commands that are replaced with real
508
content during runtime.
509
The tricky part is that one of the placeholders has to be handled differently,
510
depending on where the metadata comes from.
511
This section will explain each possible scenario.
512
.Ss Metadata Placeholders
513
.Bl -tag -width -Ds
514
.It Sy @T@
515
Replaced with the media file name.
516
Required in
517
.Li \&<decode/\&>
518
and is available in
519
.Li \&<metadata_format/\&> .
520
.It Sy @M@
521
Replaced with a metadata string.
522
See below for a detailed explanation.
523
Available in
524
.Li \&<decode/\&>
525
and
526
.Li \&<encode/\&> .
527
.It Sy @a@
528
Replaced with the artist information.
529
Available in
530
.Li \&<decode/\&> ,
531
.Li \&<encode/\&>
532
and
533
.Li \&<metadata_format/\&> .
534
.It Sy @t@
535
Replaced with the title information.
536
Available in
537
.Li \&<decode/\&> ,
538
.Li \&<encode/\&>
539
and
540
.Li \&<metadata_format/\&> .
541
.It Sy @s@
542
Replaced with the string returned by
543
.Li \&<metadata_progname/\&>
544
when called without any command line parameters.
545
Available only in
546
.Li \&<metadata_format/\&> .
547
.El
548
.Ss The @M@ Placeholder
549
While all other placeholders are simply replaced with whatever data they are
550
associated with,
551
.Sq Li @M@
552
is context-sensitive.
553
The logic used by
554
.Nm
555
is the following:
556
.Bd -literal -offset indent
557
If ('@M@ is present')
558
If ('\&<metadata_progname/\&>' AND '\&<metadata_format/\&>')
559
Replace with format string result.
560
Else
561
If (NOT '\&<metadata_progname/\&>' AND '@t@ is present')
562
Replace with empty string.
563
else
564
Replace with generated metadata string.
565
Endif
566
Endif
567
Endif
568
.Ed
569
.Pp
570
The generated metadata string for
571
.Sq Li @M@
572
is of the format
573
.Dq Em Artist - Title ,
574
if both artist and title information is available.
575
If one of the two is missing, the available one is displayed without a leading
576
or trailing dash, e.g. just
577
.Dq Em Artist .
578
If neither artist nor title are available, the name of the media file \(em
579
without its file extension \(em is used.
580
.Ss Metadata Caveats
581
It is possible to generate strange results with odd combinations of
582
placeholders, external metadata programs and updates during runtime via
583
.Sy SIGUSR2 .
584
If things start to become just confusing, simplify.
585
.Pp
586
Metadata updates during runtime are done with a relatively broken feature of
587
libshout.
588
Additional metadata information that is already present in the stream sent via
589
.Nm
590
is usually destroyed and replaced with the new data.
591
It is not possible to properly discern between artist and title information,
592
which means that anything set with the
593
.Sy SIGUSR2
594
feature will continue to end up entirely in the
595
.Qq Em Title
596
field of a stream.
597
.Pp
598
Of all possible Ogg-based streams, only Ogg Vorbis can have its metadata
599
manipulated by Icecast.
600
Any attempt of
601
.Nm
602
to update other Ogg metadata is actually a no-op.
603
.Pp
604
While
605
.Nm
606
tries to do its best with relaying metadata accurately to Icecast, and
607
subsequently the listeners, different codesets and locales can pose a problem.
608
Especially when streaming MP3 files, it may help to explicitly set a codeset
609
to work with via the
610
.Ev LC_CTYPE
611
environment variable, as
612
.Nm
613
assumes ID3v1 tags to be in the user's current locale.
614
Note that, even though support for different locales is provided by
615
.Nm ,
616
Icecast itself and the listening clients also have a say in the matter.
617
The only way to ensure consistent results with metadata in non-Ogg streams is
618
to use the characters available in the ISO-8859-1 codeset.
619
.Pp
620
External encoders may put additional, and possibly artificial, restrictions on
621
valid characters in metadata.
622
.Sh FILES
623
.Bl -tag -width "!!EXAMPLES_DIR!!" -compact
624
.It Pa !!EXAMPLES_DIR!!
625
Directory containing example configuration files for various uses of
626
.Nm ,
627
as well as example playlist and metadata scripts.
628
.El
629
.Sh SEE ALSO
630
.Xr ezstream-file.sh 1
631
.Sh AUTHORS
632
.Nm
633
was written by:
634
.Pp
635
.An Ed Zaleski Aq oddsock@oddsock.org
636
.An Moritz Grimm Aq mdgrimm@gmx.net
637
.Pp
638
This manual was written by Moritz Grimm.
Loggerhead is a web-based interface for Breezy
Version: 2.0.1