ezstream.1.in.in 18 KB
Newer Older
1
.\" Copyright (c) 2007, 2009, 2015 Moritz Grimm <mgrimm@mrsserver.net>
moritz's avatar
moritz committed
2
3
4
5
6
7
8
9
10
11
12
13
14
.\"
.\" 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
15
.\"
16
.Dd @BUILD_DATE@
moritz's avatar
moritz committed
17
.Dt EZSTREAM 1
18
.Os @PACKAGE_NAME@ @PACKAGE_VERSION@
moritz's avatar
moritz committed
19
20
.Sh NAME
.Nm ezstream
21
.Nd source client for Icecast with external de-/encoder support
moritz's avatar
moritz committed
22
23
24
.Sh SYNOPSIS
.Nm
.Bk -words
25
.Op Fl hmnqVv
moritz's avatar
moritz committed
26
.Fl c Ar configfile
moritz's avatar
moritz committed
27
.Ek
28
29
30
31
32
.Nm
.Bk -words
.Fl s
.Op Ar playlist
.Ek
moritz's avatar
moritz committed
33
34
35
36
37
38
39
40
.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
41
It can also use various external decoders and encoders to re-encode from one
moritz's avatar
moritz committed
42
43
44
45
46
47
48
49
50
51
52
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.
53
54
.It Fl m
Disable all metadata updates and keep existing metadata in streams untouched.
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
282
283
284
285
286
287
288
.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.
289
290
291
292
.It Sy \&<stream_once\ /\&>
Set to
.Sy 1
.Pq one
293
294
295
in order to stream the content of
.Li \&<filename/\&>
only once, and to
296
297
298
299
.Sy 0
.Pq zero
for continuous streaming
.Pq the default .
300
301
302
303
304
305
306
.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
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
.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
325
Set the bit rate of the broadcast.
moritz's avatar
moritz committed
326
327
328
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
329
and should match the bit rate of the stream.
moritz's avatar
moritz committed
330
331
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
.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
357
358
359
the default if the
.Li \&<svrinfopublic/\&>
element is absent.
moritz's avatar
moritz committed
360
361
.It Sy \&<reencode\ /\&>
.Pq Optional.
moritz's avatar
moritz committed
362
Element that contains child elements, which specify if and how re-encoding
moritz's avatar
moritz committed
363
364
should be done.
.El
moritz's avatar
moritz committed
365
366
.Ss Re-encoding settings
Each of the re-encoding configuration elements have the
367
.Li \&<reencode/\&>
moritz's avatar
moritz committed
368
element as their parent.
369
.Bl -tag -width -Ds
moritz's avatar
moritz committed
370
371
372
373
.It Sy \&<enable\ /\&>
Set to
.Sy 1
.Pq one
moritz's avatar
moritz committed
374
to enable re-encoding.
moritz's avatar
moritz committed
375
376
377
If set to
.Sy 0
.Pq zero ,
moritz's avatar
moritz committed
378
no re-encoding will be done, which is also the default if the
379
.Li \&<enable/\&>
moritz's avatar
moritz committed
380
381
382
383
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.
384
385
386
Each format is described by a separate
.Li \&<encdec/\&>
element.
moritz's avatar
moritz committed
387
.El
388
.Ss Decoder/Encoder settings
389
390
Each of the decoder/encoder configuration elements have the
.Li \&<encdec/\&>
moritz's avatar
moritz committed
391
element as their parent.
392
.Bl -tag -width -Ds
moritz's avatar
moritz committed
393
394
395
396
.It Sy \&<format\ /\&>
This element is used by
.Nm
to find the appropriate encoder for the output stream format specified in the
397
398
.Li \&<format/\&>
element inside the global configuration.
399
400
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
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
.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@
423
is replaced with the name of the media file, as it is specified in the
424
425
.Li \&<filename/\&>
element or contained in a playlist file.
moritz's avatar
moritz committed
426
427
428
It should always be enclosed in quotes, to prevent problems with filenames that
contain whitespaces.
.Pp
429
430
Metadata placeholders can be used in the
.Li \&<decode/\&>
moritz's avatar
moritz committed
431
432
element as well, for combined de-/encoder programs that produce data that can
be streamed.
433
434
435
436
See the
.Sy METADATA
section for details on how metadata is handled by
.Nm .
moritz's avatar
moritz committed
437
438
439
440
441
.Pp
For example, to decode Ogg Vorbis files using the
.Cm oggdec
utility:
.Pp
442
.Dl \&<decode\&>oggdec -R -o - @T@\&</decode\&>
moritz's avatar
moritz committed
443
444
445
.It Sy \&<encode\ /\&>
Set the command to encode raw data, received from standard input, to the
specified stream format.
446
.Pp
447
448
449
Metadata placeholders can be used in the
.Li \&<encode/\&>
element.
450
451
452
453
454
For details about using metadata in
.Nm ,
see below in the
.Sy METADATA
section.
moritz's avatar
moritz committed
455
456
457
458
459
460
.Pp
For example, to encode an Ogg Vorbis stream using the quality setting 1.5 with
the
.Cm oggenc
utility:
.Pp
461
.Dl \&<encode\&>oggenc -r -q 1.5 -t @M@ -\&</encode\&>
moritz's avatar
moritz committed
462
.El
463
464
465
466
467
468
469
470
471
472
473
474
475
476
.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
477
The program must not require arbitrary command line options to function.
478
479
480
481
482
483
484
485
486
487
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.
488
489
490
This is significant when the
.Li \&<stream_once/\&>
option is enabled.
491
492
493
494
495
496
497
498
499
500
501
502
503
.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
504
.Qq Li artist ,
505
506
507
508
the program should return only the artist information of the metadata.
.Pq Optional.
.It
When called with the command line parameter
509
.Qq Li title ,
510
511
the program should return only the title information of the metadata.
.Pq Optional.
512
.It
513
The supplied metadata must be encoded in UTF-8.
514
.El
515
516
517
518
519
.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.
520
521
522
523
524
525
526
527
528
529
530
.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.
531
532
533
534
.Ss Metadata Placeholders
.Bl -tag -width -Ds
.It Sy @T@
Replaced with the media file name.
535
536
537
538
Required in
.Li \&<decode/\&>
and is available in
.Li \&<metadata_format/\&> .
539
540
541
.It Sy @M@
Replaced with a metadata string.
See below for a detailed explanation.
542
543
544
545
Available in
.Li \&<decode/\&>
and
.Li \&<encode/\&> .
546
547
.It Sy @a@
Replaced with the artist information.
548
549
550
551
552
Available in
.Li \&<decode/\&> ,
.Li \&<encode/\&>
and
.Li \&<metadata_format/\&> .
553
554
.It Sy @t@
Replaced with the title information.
555
556
557
558
559
Available in
.Li \&<decode/\&> ,
.Li \&<encode/\&>
and
.Li \&<metadata_format/\&> .
560
.It Sy @s@
561
562
563
564
565
Replaced with the string returned by
.Li \&<metadata_progname/\&>
when called without any command line parameters.
Available only in
.Li \&<metadata_format/\&> .
566
567
568
569
.El
.Ss The @M@ Placeholder
While all other placeholders are simply replaced with whatever data they are
associated with,
570
.Sq Li @M@
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
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
590
.Sq Li @M@
591
is of the format
592
.Dq Em Artist - Title ,
593
594
595
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
596
597
598
.Dq Em Artist .
If neither artist nor title are available, the name of the media file \(em
without its file extension \(em is used.
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
.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
614
.Qq Em Title
615
field of a stream.
616
617
618
619
620
621
622
623
624
625
626
627
628
629
.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
630
631
632
633
634
635
636
637
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.
638
639
640
.Pp
External encoders may put additional, and possibly artificial, restrictions on
valid characters in metadata.
moritz's avatar
moritz committed
641
642
643
644
.Sh FILES
.Bl -tag -width "!!EXAMPLES_DIR!!" -compact
.It Pa !!EXAMPLES_DIR!!
Directory containing example configuration files for various uses of
645
646
.Nm ,
as well as example playlist and metadata scripts.
moritz's avatar
moritz committed
647
.El
648
649
.Sh SEE ALSO
.Xr ezstream-file.sh 1
moritz's avatar
moritz committed
650
651
652
653
654
.Sh AUTHORS
.Nm
was written by:
.Pp
.An Ed Zaleski Aq oddsock@oddsock.org
655
.An Moritz Grimm Aq mgrimm@mrsserver.net
moritz's avatar
moritz committed
656
.Pp
657
658
659
.An -nosplit
This manual was written by
.An Moritz Grimm .