ezstream.1.in.in 18 KB
Newer Older
moritz's avatar
moritz committed
1
.\" $Id$
moritz's avatar
moritz committed
2
.\"
3
.\" Copyright (c) 2007, 2009, 2015 Moritz Grimm <mgrimm@mrsserver.net>
moritz's avatar
moritz committed
4
5
6
7
8
9
10
11
12
13
14
15
16
.\"
.\" 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 hmnqVv
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 m
Disable all metadata updates and keep existing metadata in streams untouched.
57
58
.It Fl n
Normalize metadata strings by removing excess whitespaces.
moritz's avatar
moritz committed
59
60
61
.It Fl q
Be more quiet.
Suppress the output that external programs send to standard error.
62
63
64
65
66
67
68
69
70
71
72
73
.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.
74
75
76
77
.It Fl V
Print the
.Nm
version number and exit.
moritz's avatar
moritz committed
78
79
80
81
82
83
84
85
86
87
88
89
.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
90
and bit rate \(em is displayed.
moritz's avatar
moritz committed
91
92
93
.Ss Runtime control
On POSIX systems,
.Nm
94
offers limited runtime control via signals.
moritz's avatar
moritz committed
95
96
97
98
99
100
101
102
103
104
105
106
107
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.
108
109
.It Cd SIGUSR2
Triggers rereading of metadata for the stream by running the program or script
110
111
specified in
.Li \&<metadata_progname/\&>
112
113
.Pq see below.
This is the only meaningful signal when streaming from standard input.
moritz's avatar
moritz committed
114
115
116
117
118
119
120
121
122
123
124
125
126
127
.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
128
.Em start tag ,
moritz's avatar
moritz committed
129
its content and an
130
.Em end tag .
moritz's avatar
moritz committed
131
132
133
134
135
136
137
138
139
140
141
142
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
143
.Bl -tag -width -Ds
moritz's avatar
moritz committed
144
145
146
147
148
149
.It Sy \&<ezstream\ /\&>
.Pq Mandatory.
The configuration file's root element.
It contains all other configuration elements.
.El
.Ss Global configuration elements
150
151
152
Each of the global configuration elements have the
.Li \&<ezstream/\&>
element as their parent.
153
.Bl -tag -width -Ds
moritz's avatar
moritz committed
154
155
.It Sy \&<url\ /\&>
.Pq Mandatory.
moritz's avatar
moritz committed
156
Specifies the location and mount point of the Icecast server, to which the
moritz's avatar
moritz committed
157
158
159
160
161
162
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\&>
163
164
165
166
167
168
169
170
171
.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
172
173
174
175
176
.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
177
This element has two different meanings, depending on whether re-encoding is
moritz's avatar
moritz committed
178
179
180
enabled or not.
It specifies the
.Em output format
moritz's avatar
moritz committed
181
of the stream if re-encoding is enabled.
moritz's avatar
moritz committed
182
183
184
185
186
Otherwise, it specifies the
.Em input format
of
.Sy all
input files.
187
Recognized and supported values for output stream formats are
moritz's avatar
moritz committed
188
189
190
191
192
193
194
195
196
.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.
197
198
199
200
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
201
202
203
204
205
206
207
208
209
210
211
212
.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 .
213
.It Sy \&<playlist_program\ /\&>
214
215
216
217
.Pq Optional.
Set to
.Sy 1
.Pq one
218
219
220
to indicate that the file in
.Li \&<filename/\&>
is actually an executable program or script.
221
222
223
If set to
.Sy 0
.Pq zero ,
224
225
.Li \&<filename/\&>
content is assumed to be a media file, playlist file or the keyword
226
227
.Pa stdin
.Pq the default .
228
229
230
231
.Pp
See the
.Sy SCRIPTING
section for details on how the playlist program must behave.
moritz's avatar
moritz committed
232
233
234
235
236
.It Sy \&<shuffle\ /\&>
.Pq Optional.
Set to
.Sy 1
.Pq one
237
238
to randomly shuffle the entries of the playlist specified in
.Li \&<filename/\&> .
moritz's avatar
moritz committed
239
240
241
Files are played sequentially if set to
.Sy 0
.Pq zero
242
243
244
245
246
247
or when the
.Li \&<shuffle/\&>
element is absent.
This option will be ignored if
.Li \&<playlist_program/\&>
is set to 1
248
.Pq one.
249
250
251
252
253
254
255
256
257
258
.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
259
260
261
262
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.
263
264
265
266
267
268
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.
269
270
271
.It Sy \&<metadata_format\ /\&>
.Pq Optional.
Set the format of the string that should be used for the
272
.Sq Li @M@
273
placeholder when setting metadata with an external program or script via
274
.Li \&<metadata_progname/\&> .
275
276
277
278
279
.Pp
See the
.Sy METADATA
section for details on how metadata is handled by
.Nm .
280
281
282
283
284
285
286
287
288
289
290
.It Sy \&<metadata_refreshinterval\ /\&>
.Pq Optional.
Configures the time
.Pq in seconds
inbetween additional metadata updates via
.Li \&<metadata_progname/\&> .
A value of 0
.Pq zero
triggers updates as fast as possible, while a value of \&-1
.Pq minus one
or the absence of this configuration element disables this feature.
291
292
293
294
.It Sy \&<stream_once\ /\&>
Set to
.Sy 1
.Pq one
295
296
297
in order to stream the content of
.Li \&<filename/\&>
only once, and to
298
299
300
301
.Sy 0
.Pq zero
for continuous streaming
.Pq the default .
302
303
304
305
306
307
308
.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
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
.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
327
Set the bit rate of the broadcast.
moritz's avatar
moritz committed
328
329
330
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
331
and should match the bit rate of the stream.
moritz's avatar
moritz committed
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
.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
359
360
361
the default if the
.Li \&<svrinfopublic/\&>
element is absent.
moritz's avatar
moritz committed
362
363
.It Sy \&<reencode\ /\&>
.Pq Optional.
moritz's avatar
moritz committed
364
Element that contains child elements, which specify if and how re-encoding
moritz's avatar
moritz committed
365
366
should be done.
.El
moritz's avatar
moritz committed
367
368
.Ss Re-encoding settings
Each of the re-encoding configuration elements have the
369
.Li \&<reencode/\&>
moritz's avatar
moritz committed
370
element as their parent.
371
.Bl -tag -width -Ds
moritz's avatar
moritz committed
372
373
374
375
.It Sy \&<enable\ /\&>
Set to
.Sy 1
.Pq one
moritz's avatar
moritz committed
376
to enable re-encoding.
moritz's avatar
moritz committed
377
378
379
If set to
.Sy 0
.Pq zero ,
moritz's avatar
moritz committed
380
no re-encoding will be done, which is also the default if the
381
.Li \&<enable/\&>
moritz's avatar
moritz committed
382
383
384
385
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.
386
387
388
Each format is described by a separate
.Li \&<encdec/\&>
element.
moritz's avatar
moritz committed
389
.El
390
.Ss Decoder/Encoder settings
391
392
Each of the decoder/encoder configuration elements have the
.Li \&<encdec/\&>
moritz's avatar
moritz committed
393
element as their parent.
394
.Bl -tag -width -Ds
moritz's avatar
moritz committed
395
396
397
398
.It Sy \&<format\ /\&>
This element is used by
.Nm
to find the appropriate encoder for the output stream format specified in the
399
400
.Li \&<format/\&>
element inside the global configuration.
401
402
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
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
.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@
425
is replaced with the name of the media file, as it is specified in the
426
427
.Li \&<filename/\&>
element or contained in a playlist file.
moritz's avatar
moritz committed
428
429
430
It should always be enclosed in quotes, to prevent problems with filenames that
contain whitespaces.
.Pp
431
432
Metadata placeholders can be used in the
.Li \&<decode/\&>
moritz's avatar
moritz committed
433
434
element as well, for combined de-/encoder programs that produce data that can
be streamed.
435
436
437
438
See the
.Sy METADATA
section for details on how metadata is handled by
.Nm .
moritz's avatar
moritz committed
439
440
441
442
443
.Pp
For example, to decode Ogg Vorbis files using the
.Cm oggdec
utility:
.Pp
444
.Dl \&<decode\&>oggdec -R -o - @T@\&</decode\&>
moritz's avatar
moritz committed
445
446
447
.It Sy \&<encode\ /\&>
Set the command to encode raw data, received from standard input, to the
specified stream format.
448
.Pp
449
450
451
Metadata placeholders can be used in the
.Li \&<encode/\&>
element.
452
453
454
455
456
For details about using metadata in
.Nm ,
see below in the
.Sy METADATA
section.
moritz's avatar
moritz committed
457
458
459
460
461
462
.Pp
For example, to encode an Ogg Vorbis stream using the quality setting 1.5 with
the
.Cm oggenc
utility:
.Pp
463
.Dl \&<encode\&>oggenc -r -q 1.5 -t @M@ -\&</encode\&>
moritz's avatar
moritz committed
464
.El
465
466
467
468
469
470
471
472
473
474
475
476
477
478
.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
479
The program must not require arbitrary command line options to function.
480
481
482
483
484
485
486
487
488
489
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.
490
491
492
This is significant when the
.Li \&<stream_once/\&>
option is enabled.
493
494
495
496
497
498
499
500
501
502
503
504
505
.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
506
.Qq Li artist ,
507
508
509
510
the program should return only the artist information of the metadata.
.Pq Optional.
.It
When called with the command line parameter
511
.Qq Li title ,
512
513
the program should return only the title information of the metadata.
.Pq Optional.
514
.It
515
The supplied metadata must be encoded in UTF-8.
516
.El
517
518
519
520
521
.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.
522
523
524
525
526
527
528
529
530
531
532
.Pp
.Em Note:
To prevent malicious shell script in metadata
.Pq such as artist and title tags
from being executed, all metadata content is automatically enclosed in single
quotes, with escaped single quote and backslash characters inbetween.
To prevent this from causing unwanted side-effects
.Pq or introducting security risk ,
placeholders
.Em must not
be quoted any further.
533
534
535
536
.Ss Metadata Placeholders
.Bl -tag -width -Ds
.It Sy @T@
Replaced with the media file name.
537
538
539
540
Required in
.Li \&<decode/\&>
and is available in
.Li \&<metadata_format/\&> .
541
542
543
.It Sy @M@
Replaced with a metadata string.
See below for a detailed explanation.
544
545
546
547
Available in
.Li \&<decode/\&>
and
.Li \&<encode/\&> .
548
549
.It Sy @a@
Replaced with the artist information.
550
551
552
553
554
Available in
.Li \&<decode/\&> ,
.Li \&<encode/\&>
and
.Li \&<metadata_format/\&> .
555
556
.It Sy @t@
Replaced with the title information.
557
558
559
560
561
Available in
.Li \&<decode/\&> ,
.Li \&<encode/\&>
and
.Li \&<metadata_format/\&> .
562
.It Sy @s@
563
564
565
566
567
Replaced with the string returned by
.Li \&<metadata_progname/\&>
when called without any command line parameters.
Available only in
.Li \&<metadata_format/\&> .
568
569
570
571
.El
.Ss The @M@ Placeholder
While all other placeholders are simply replaced with whatever data they are
associated with,
572
.Sq Li @M@
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
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
592
.Sq Li @M@
593
is of the format
594
.Dq Em Artist - Title ,
595
596
597
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
598
599
600
.Dq Em Artist .
If neither artist nor title are available, the name of the media file \(em
without its file extension \(em is used.
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
.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
616
.Qq Em Title
617
field of a stream.
618
619
620
621
622
623
624
625
626
627
628
629
630
631
.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
632
633
634
635
636
637
638
639
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.
640
641
642
.Pp
External encoders may put additional, and possibly artificial, restrictions on
valid characters in metadata.
moritz's avatar
moritz committed
643
644
645
646
.Sh FILES
.Bl -tag -width "!!EXAMPLES_DIR!!" -compact
.It Pa !!EXAMPLES_DIR!!
Directory containing example configuration files for various uses of
647
648
.Nm ,
as well as example playlist and metadata scripts.
moritz's avatar
moritz committed
649
.El
650
651
.Sh SEE ALSO
.Xr ezstream-file.sh 1
moritz's avatar
moritz committed
652
653
654
655
656
.Sh AUTHORS
.Nm
was written by:
.Pp
.An Ed Zaleski Aq oddsock@oddsock.org
657
.An Moritz Grimm Aq mgrimm@mrsserver.net
moritz's avatar
moritz committed
658
.Pp
659
660
661
.An -nosplit
This manual was written by
.An Moritz Grimm .