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