← Back to branch summary

~ubuntu-branches/ubuntu/lucid/ezstream/lucid

« back to all changes in this revision

Viewing changes to doc/ezstream.1.in

  • 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

Show diffs side-by-side

added added

removed removed

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