ezstream.1.in.in 21.7 KB
Newer Older
Moritz Grimm's avatar
Moritz Grimm committed
1
.\" Copyright (c) 2007 - 2020            Moritz Grimm <mgrimm@mrsserver.net>
moritz's avatar
moritz committed
2
3
4
5
6
7
8
9
10
11
.\"
.\" 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.
.\"
12
.Dd @BUILD_DATE@
moritz's avatar
moritz committed
13
.Dt EZSTREAM 1
14
.Os @PACKAGE_NAME@ @PACKAGE_VERSION@
moritz's avatar
moritz committed
15
16
.Sh NAME
.Nm ezstream
17
.Nd source client for Icecast with external de-/encoder support
moritz's avatar
moritz committed
18
19
20
.Sh SYNOPSIS
.Nm
.Bk -words
Moritz Grimm's avatar
Moritz Grimm committed
21
.Op Fl hqrVv
moritz's avatar
moritz committed
22
.Fl c Ar configfile
23
.Op Fl p Ar pidfile
moritz's avatar
moritz committed
24
.Ek
25
26
.Nm
.Bk -words
Moritz Grimm's avatar
Moritz Grimm committed
27
.Fl s Ar file
28
.Ek
moritz's avatar
moritz committed
29
30
.Sh DESCRIPTION
.Nm
31
32
33
34
35
36
37
is a command line source client for media streams, primarily for streaming
to Icecast servers.
.Pp
It allows the creation of media streams based on input from files or standard
input that is piped through an optional external de- and encoder.
As every part of this chain is highly configurable, ezstream can be useful in
a large number of streaming setups.
Moritz Grimm's avatar
Moritz Grimm committed
38
.Ss Command line arguments
moritz's avatar
moritz committed
39
40
41
42
43
.Bl -tag -width Ds
.It Fl c Ar configfile
Use the XML configuration in
.Ar configfile .
.It Fl h
Moritz Grimm's avatar
Moritz Grimm committed
44
Print a summary of available command line arguments with short descriptions
moritz's avatar
moritz committed
45
and exit.
46
47
48
49
50
51
52
53
54
55
56
57
58
59
.It Fl p Ar pidfile
Write the
.Nm
process ID
.Pq a single number
to
.Ar pidfile .
The file will be written even when it already exists.
A file lock is maintained until the main
.Nm
process terminates.
If the file cannot be written for any reason,
.Nm
will log this, but not consider it a fatal error.
moritz's avatar
moritz committed
60
61
62
.It Fl q
Be more quiet.
Suppress the output that external programs send to standard error.
Moritz Grimm's avatar
Moritz Grimm committed
63
64
65
66
67
68
69
70
.It Fl r
Maintain a line of real-time status information about the stream on standard
output.
.Po
Implies
.Fl q .
.Pc
.It Fl s Ar file
71
72
73
Run
.Nm
as a line-based shuffling utility.
74
If a
75
.Ar playlist
76
77
78
argument of
.Dq -
is given, a list of media file names is read from standard input
79
80
81
82
83
instead of an input file.
After successfully reading the entire list, it is shuffled and printed to
standard output, and
.Nm
will exit.
84
85
86
87
.It Fl V
Print the
.Nm
version number and exit.
moritz's avatar
moritz committed
88
.It Fl v
Moritz Grimm's avatar
Moritz Grimm committed
89
90
Increase logging verbosity.
May be used up to three times to also include debug logging output.
moritz's avatar
moritz committed
91
92
.El
.Ss Runtime control
93
.Nm Ezstream
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
.It Cd SIGUSR2
109
110
Triggers rereading of metadata for the stream by running the configured
program or script.
111
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 Grimm's avatar
Moritz Grimm 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
.It Sy \&<ezstream\ /\&>
.Pq Mandatory.
The configuration file's root element.
145
146
147
148
149
150
151
152
153
154
It contains all other configuration elements.
.Pp
.El
.Ss Servers block
.Bl -tag -width -Ds
.It Sy \&<servers\ /\&>
This element contains all server blocks as child elements.
Its parent is the
.Sy \&<ezstream\ /\&>
element.
Moritz Grimm's avatar
Moritz Grimm committed
155
.Pp
156
157
A configuration file may contain multiple named server configurations.
The stream configuration determines what server configuration should be used.
moritz's avatar
moritz committed
158
.El
Moritz Grimm's avatar
Moritz Grimm committed
159
.Ss Server block
160
.Bl -tag -width -Ds
Moritz Grimm's avatar
Moritz Grimm committed
161
.It Sy \&<server\ /\&>
moritz's avatar
moritz committed
162
.Pq Mandatory.
163
This element contains a complete server configuration as child elements.
Moritz Grimm's avatar
Moritz Grimm committed
164
Its parent is the
165
.Sy \&<servers\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
166
167
168
169
element.
.El
.Ss Server configuration
.Bl -tag -width -Ds
170
171
172
173
174
175
176
177
178
.It Sy \&<name\ /\&>
Set the name of the server configuration.
This may be referenced in a
.Sy \&<stream\ /\&> .
.Pp
The name is case-aware, but not case-sensitive.
.Pp
Default:
.Ar default
Moritz Grimm's avatar
Moritz Grimm committed
179
180
.It Sy \&<protocol\ /\&>
Transport protocol used to stream to the server:
moritz's avatar
moritz committed
181
.Pp
182
.Bl -tag -width RoarAudio -compact
Moritz Grimm's avatar
Moritz Grimm committed
183
.It Ar HTTP
184
185
186
Plain-text HTTP.
The \&<tls\ /\&> option defines, if TLS via RFC2817 or RFC2818 is also
attempted.
187
188
.It Ar HTTPS
HTTP over TLS.
189
190
191
192
193
194
This option implies that \&<tls\ /\&> is set to
.Qq required .
.It Ar ICY
ICY streaming protocol
.It Ar RoarAudio
RoarAudio streaming protocol
Moritz Grimm's avatar
Moritz Grimm committed
195
.El
196
197
198
.Pp
Default:
.Ar HTTP
Moritz Grimm's avatar
Moritz Grimm committed
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
.It Sy \&<hostname\ /\&>
.Pq Mandatory.
The FQDN host name or IP address of the server.
.It Sy \&<port\ /\&>
Port number on which the server is listening.
.Pp
Default:
.Ar 8000
.It Sy \&<user\ /\&>
User to authenticate as on the server.
.Pp
Default:
.Ar source
.It Sy \&<password\ /\&>
.Pq Mandatory.
Password to authenticate with on the server.
215
216
217
218
219
220
221
222
.It Sy \&<reconnect_attempts\ /\&>
Number of reconnect attempts in case of connection issues with the server,
or 0
.Pq zero
for trying indefinitely.
.Pp
Default:
.Ar 0
223
224
225
226
227
228
229
230
231
232
233
234
235
236
.It Sy \&<tls\ /\&>
Configure the TLS encryption requirement for the server connection.
Possible values are:
.Pp
.Bl -tag -width 0|NO|FALSE -compact
.It Ar None
No TLS encryption will be attempted.
.It Ar May
Opportunistic TLS encryption may be used, if the server supports it
.It Ar Required
TLS encryption is required.
This is the only setting that is providing security against both passive and
active attackers.
.El
237
238
239
240
241
242
243
244
.Pp
Default:
.Ar May
.Pp
This option is ignored when \&<protocol\ /\&> is set to
.Ar HTTPS ,
which implies a value of
.Ar Required .
245
246
247
.It Sy \&<tls_cipher_suite\ /\&>
Configure allowed cipher suites for TLS.
.Pp
248
249
For example (modern cipher suites, PFS, TLS 1.2 or better):
.Sy HIGH:!RSA:!SHA:!DH:!aNULL:!eNULL:!TLSv1 .
250
251
252
.Pp
Default:
.Em libshout default cipher suite
253
254
255
256
257
258
.It Sy \&<ca_dir\ /\&>
Directory in which OpenSSL finds root CA certificates for validating the
.Ar HTTPS
server identity.
.Pp
Default:
259
.Em system default
260
261
262
263
264
265
.It Sy \&<ca_file\ /\&>
Path of a root CA bundle file for validating the
.Ar HTTPS
server identity.
.Pp
Default:
266
.Em system default
267
.It Sy \&<client_cert\ /\&>
268
269
270
X.503 client certificate and key
.Pq in PEM format containing both certificate and key in the same file
for authentication on an
271
272
273
274
275
.Ar HTTPS
server.
.Pp
Default:
.Em no client certificate authentication
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
.El
.Ss Streams block
.Bl -tag -width -Ds
.It Sy \&<streams\ /\&>
This element contains all stream blocks as child elements.
Its parent is the
.Sy \&<ezstream\ /\&>
element.
.Pp
.Em Note:
While multiple stream configurations are supported by the file format, only
the one configuration with the name
.Ar default
will be used by
.Nm .
Moritz Grimm's avatar
Moritz Grimm committed
291
292
293
294
295
296
297
.El
.Ss Stream block
.Bl -tag -width -Ds
.It Sy \&<stream\ /\&>
.Pq Mandatory.
This element contains the entire stream configuration as child elements.
Its parent is the
298
.Sy \&<streams\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
299
300
301
302
element.
.El
.Ss Stream configuration
.Bl -tag -width -Ds
303
304
305
306
307
308
309
.It Sy \&<name\ /\&>
Set the name of the stream configuration.
.Pp
The name is case-aware, but not case-sensitive.
.Pp
Default:
.Ar default
Moritz Grimm's avatar
Moritz Grimm committed
310
.It Sy \&<mountpoint\ /\&>
moritz's avatar
moritz committed
311
.Pq Mandatory.
Moritz Grimm's avatar
Moritz Grimm committed
312
Stream mountpoint on the server.
313
314
315
316
317
318
319
320
321
322
.It Sy \&<public\ /\&>
Boolean setting of whether the broadcast may be listed in a public YP
directory, or not.
.Pp
.Bl -tag -width 0|NO|FALSE -compact
.It Ar 0|No|False
The broadcast is private (the default).
.It Ar 1|Yes|True
The broadcast is public.
.El
323
324
325
326
327
328
329
330
331
.It Sy \&<intake\ /\&>
Use the intake
.Po
input media
.Pc
configuration with the provided symbolic name for this stream.
.Pp
Default:
.Ar default
332
333
334
335
336
337
338
339
340
.It Sy \&<server\ /\&>
Use the server configuration with the provided symbolic name for this stream.
.Pp
Default:
.Ar default
.It Sy \&<format\ /\&>
.Pq Mandatory.
The stream format.
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
341
342
343
.Bl -tag -width Matroska -compact
.It Ar Ogg
Ogg media format
344
345
.It Ar MP3
MP3 audio format
Moritz Grimm's avatar
Moritz Grimm committed
346
347
348
349
.It Ar WebM
WebM media format
.It Ar Matroska
Matroska media format
350
351
352
353
354
355
356
357
358
359
360
361
362
.El
.It Sy \&<encoder\ /\&>
Use the encoder configuration with the provided symbolic name
.Pq see below ,
for (re)encoding the stream.
Not configuring an encoder makes
.Nm
stream input media files as-is.
.Pp
The configured encoder's output stream format must match what is configured
in
.Sy \&<format\ /\&> .
.It Sy \&<stream_name\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
363
364
365
366
Informational name of the broadcast.
.Pp
Default:
.Em none
367
.It Sy \&<stream_url\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
368
369
370
371
Informational URL associated with the broadcast, e.g. the web site.
.Pp
Default:
.Em none
372
.It Sy \&<stream_genre\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
373
374
375
376
Informational genre of the broadcast.
.Pp
Default:
.Em none
377
.It Sy \&<stream_description\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
378
379
380
381
Informational description of the broadcast.
.Pp
Default:
.Em none
382
.It Sy \&<stream_quality\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
383
384
385
386
Informational quality setting of the VBR broadcast.
.Pp
Default:
.Em none
387
.It Sy \&<stream_bitrate\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
388
389
390
391
Informational bitrate setting of the CBR broadcast.
.Pp
Default:
.Em none
392
.It Sy \&<stream_samplerate\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
393
394
395
396
Informational sample rate of the broadcast audio.
.Pp
Default:
.Em none
397
.It Sy \&<stream_channels\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
398
399
400
401
402
Informational number of audio channels of the broadcast.
.Pp
Default:
.Em none
.El
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
.Ss Intakes block
.Bl -tag -width -Ds
.It Sy \&<intakes\ /\&>
This element contains all intake blocks as child elements.
Its parent is the
.Sy \&<ezstream\ /\&>
element.
.Pp
A configuration file may contain multiple named intake configurations.
The stream configuration determines what intake
.Po
media input
.Pc
configuration should be used.
.El
.Ss Intake block
Moritz Grimm's avatar
Moritz Grimm committed
419
.Bl -tag -width -Ds
420
.It Sy \&<intake\ /\&>
moritz's avatar
moritz committed
421
.Pq Mandatory.
Moritz Grimm's avatar
Moritz Grimm committed
422
423
This element contains the entire input media configuration as child elements.
Its parent is the
424
.Sy \&<intakes\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
425
426
element.
.El
427
.Ss Intake configuration
Moritz Grimm's avatar
Moritz Grimm committed
428
.Bl -tag -width -Ds
429
430
431
432
433
434
435
436
437
.It Sy \&<name\ /\&>
Set the name of the intake configuration.
This may be referenced in a
.Sy \&<stream\ /\&> .
.Pp
The name is case-aware, but not case-sensitive.
.Pp
Default:
.Ar default
Moritz Grimm's avatar
Moritz Grimm committed
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
.It Sy \&<type\ /\&>
Configure the input media type:
.Pp
.Bl -tag -width AUTODETECT -compact
.It Ar autodetect
Attempt to autodetect, whether the input is a playlist, or a single media
file.
Playlists are detected by their
.Dq Li .m3u
and
.Dq Li .txt
file name extensions.
.Pq This is the default.
.It Ar file
The input is one single media file.
.It Ar playlist
The input is a playlist.
Playlists are a newline-delimited list of media file path names.
moritz's avatar
moritz committed
456
457
458
459
Comments in playlists are introduced by a
.Sq Li #
sign at the beginning of a line and ignored by
.Nm .
Moritz Grimm's avatar
Moritz Grimm committed
460
461
462
463
464
465
466
467
468
469
470
471
472
.It Ar program
The input is an executable
.Dq Playlist Program .
See
.Xr SCRIPTING
for more information.
.It Ar stdin
The input is read from standard input.
.El
.It Sy \&<filename\ /\&>
The input media file name; mandatory for all but the
.Ar stdin
type.
moritz's avatar
moritz committed
473
.It Sy \&<shuffle\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
474
475
476
477
478
479
480
481
482
483
484
485
Boolean setting of whether the
.Ar playlist
type media should be shuffled, or not.
.Pp
.Bl -tag -width 0|NO|FALSE -compact
.It Ar 0|No|False
Stream the playlist content sequentially (the default).
.It Ar 1|Yes|True
Shuffle the playlist prior to streaming its content.
.El
.It Sy \&<stream_once\ /\&>
Boolean setting of whether
486
.Nm
Moritz Grimm's avatar
Moritz Grimm committed
487
should exit after streaming its media input, or start over.
488
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
.Bl -tag -width 0|NO|FALSE -compact
.It Ar 0|No|False
Attempt to start over whenever the end of the media input is reached (the
default).
.It Ar 1|Yes|True
After streaming all media input, exit.
.El
.El
.Ss Metadata block
.Bl -tag -width -Ds
.It Sy \&<metadata\ /\&>
This element contains the entire metadata configuration as child elements.
Its parent is the
.Sy \&<ezstream\ /\&>
element.
.El
.Ss Metadata configuration
.Bl -tag -width -Ds
.It Sy \&<program\ /\&>
Set an executable
.Dq Metadata Program
to be queried for all metadata on
.Sy SIGUSR2
or whenever a new track begins.
See
.Xr SCRIPTING
for more information.
516
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
517
518
519
Default:
.Em use metadata as contained in media files
.It Sy \&<format_str\ /\&>
520
Set the format of the string that should be used for the
521
.Sq Li @M@
Moritz Grimm's avatar
Moritz Grimm committed
522
placeholder, when quering for metadata from an executable.
523
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
524
Default:
525
.Li @a@ - @t@
Moritz Grimm's avatar
Moritz Grimm committed
526
527
528
529
530
531
532
533
534
535
536
.It Sy \&<refresh_interval\ /\&>
Configure a time interval for additional metadata updates via a
.Dq Metadata Program :
.Pp
.Bl -tag -width -1 -compact
.It Ar -1
Do not trigger any additional metadata updates (the default).
.It Ar 0
Trigger metadata updates at the highest reasonable frequency.
.It Ar \&>0
Configure the time
537
.Pq in seconds
Moritz Grimm's avatar
Moritz Grimm committed
538
539
540
541
542
543
544
545
546
547
548
549
in between additional metadata updates.
.El
.It Sy \&<normalize_strings\ /\&>
Boolean setting of whether metadata strings should have excess whitespace
removed, or not.
.Pp
.Bl -tag -width 0|NO|FALSE -compact
.It Ar 0|No|False
Use metadata strings as-is (the default).
.It Ar 1|Yes|True
Trim leading and trailing whitespace, as well as remove excess whitespace
in case that there is more than one in sequence.
moritz's avatar
moritz committed
550
.El
Moritz Grimm's avatar
Moritz Grimm committed
551
552
553
554
555
556
557
558
559
560
561
562
.It Sy \&<no_updates\ /\&>
Boolean setting of whether metadata updates should be suppressed altogether,
or not.
.Pp
.Bl -tag -width 0|NO|FALSE -compact
.It Ar 0|No|False
Update metadata in the usual manner (the default).
.It Ar 1|Yes|True
Disable all metadata updates, and keep existing metadata in streams untouched.
.El
.El
.Ss Decoders block
563
.Bl -tag -width -Ds
Moritz Grimm's avatar
Moritz Grimm committed
564
565
566
567
.It Sy \&<decoders\ /\&>
This element contains all decoder blocks as child elements.
Its parent is the
.Sy \&<ezstream\ /\&>
568
element.
moritz's avatar
moritz committed
569
.El
Moritz Grimm's avatar
Moritz Grimm committed
570
.Ss Decoder block
571
.Bl -tag -width -Ds
Moritz Grimm's avatar
Moritz Grimm committed
572
573
574
575
576
577
578
579
580
581
.It Sy \&<decoder\ /\&>
This element contains all configuration of a single decoder.
Its parent is the
.Sy \&<decoders\ /\&>
element.
.El
.Ss Decoder configuration
.Bl -tag -width -Ds
.It Sy \&<name\ /\&>
Set the name of the decoder configuration.
582
583
.Pp
The name is case-aware, but not case-sensitive.
Moritz Grimm's avatar
Moritz Grimm committed
584
585
.Pp
Default:
586
.Ar default
Moritz Grimm's avatar
Moritz Grimm committed
587
588
589
590
591
592
593
.It Sy \&<program\ /\&>
.Pq Mandatory.
Set the full command line to decode a media input file, represented by the
.Sq @T@
placeholder, into a
.Dq canonical internal format
on standard output.
moritz's avatar
moritz committed
594
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
595
596
597
The canonical format should be the same for all configured decoders, e.g. RAW
audio with a specific signedness, bitrate, and samplerate that can be
consumed by encoders.
598
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
599
600
601
602
603
604
605
606
607
608
609
610
For exotic use cases, metadata placeholders may be used here.
.Pp
Example:
.Dl \&<program\&>oggdec -R -o - @T@\&</program\&>
.It Sy \&<file_ext\ /\&>
.Pq Mandatory.
Set a filename extension to be associated with this decoder.
.Pp
It is possible to specify more than one
.Sy \&<file_ext\ /\&>
element per decoder to associate more than one file extension to the same
decoder.
611
612
.Pp
A filename extension can only be associated with one decoder.
Moritz Grimm's avatar
Moritz Grimm committed
613
614
615
616
617
618
619
.El
.Ss Encoders block
.Bl -tag -width -Ds
.It Sy \&<encoders\ /\&>
This element contains all encoder blocks as child elements.
Its parent is the
.Sy \&<ezstream\ /\&>
620
element.
Moritz Grimm's avatar
Moritz Grimm committed
621
622
623
624
625
626
627
628
629
630
631
632
633
.El
.Ss Encoder block
.Bl -tag -width -Ds
.It Sy \&<encoder\ /\&>
This element contains all configuration of a single encoder.
Its parent is the
.Sy \&<encoders\ /\&>
element.
.El
.Ss Encoder configuration
.Bl -tag -width -Ds
.It Sy \&<name\ /\&>
.Pq Mandatory.
634
635
Set the name of the encoder configuration.
This may be referenced in a
Moritz Grimm's avatar
Moritz Grimm committed
636
637
638
639
.Sy \&<stream\ /\&>
block in case (re)encoding is desired.
.Pp
The name is case-aware, but not case-sensitive.
640
641
642
.Pp
Default:
.Ar default
Moritz Grimm's avatar
Moritz Grimm committed
643
644
645
646
647
648
649
650
.It Sy \&<format\ /\&>
.Pq Mandatory.
Stream format produced by this encoder.
This must be one of the available stream formats as specified for the
.Sy \&<stream\ /\&>
block.
.It Sy \&<program\ /\&>
.Pq Mandatory.
651
Set the full command line to encode the
Moritz Grimm's avatar
Moritz Grimm committed
652
653
.Dq canonical internal format
from standard input into a supported stream format on standard output.
moritz's avatar
moritz committed
654
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
655
Metadata placeholders may be used here.
moritz's avatar
moritz committed
656
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
657
658
Example:
.Dl \&<program\&>oggenc -r -q 1.5 -t @M@ -\&</program\&>
moritz's avatar
moritz committed
659
.El
660
661
662
663
664
665
666
667
668
669
670
671
672
673
.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
674
The program must not require arbitrary command line options to function.
675
676
677
678
679
680
681
682
683
684
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.
685
686
687
This is significant when the
.Li \&<stream_once/\&>
option is enabled.
688
689
690
691
692
693
694
.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
Moritz Grimm's avatar
Moritz Grimm committed
695
with a command line argument that the program does not support.
696
.It
Moritz Grimm's avatar
Moritz Grimm committed
697
When called without command line arguments, the program should return a
698
699
complete string that should be used for metadata.
.It
Moritz Grimm's avatar
Moritz Grimm committed
700
When called with the command line argument
701
.Qq Li artist ,
702
703
704
the program should return only the artist information of the metadata.
.Pq Optional.
.It
Moritz Grimm's avatar
Moritz Grimm committed
705
When called with the command line argument
706
.Qq Li title ,
707
708
the program should return only the title information of the metadata.
.Pq Optional.
709
.It
710
The supplied metadata must be encoded in UTF-8.
711
.El
712
713
714
715
716
.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.
717
718
.Pp
.Em Note:
Moritz Grimm's avatar
Moritz Grimm committed
719
720
721
All placeholders are replaced with content enclosed in single quotes, with
escaped single quote and backslash characters in between, so that
interpretation by the shell does not occur.
722
.Em \&Do not add any additional quoting!
723
724
725
726
.Ss Metadata Placeholders
.Bl -tag -width -Ds
.It Sy @T@
Replaced with the media file name.
727
Required in
Moritz Grimm's avatar
Moritz Grimm committed
728
729
730
.Li /ezstream/decoders/decoder/program .
Available in
.Li /ezstream/metadata/format_str .
731
732
.It Sy @M@
Replaced with a metadata string.
Moritz Grimm's avatar
Moritz Grimm committed
733
.Pq See below for a detailed explanation.
734
Available in
Moritz Grimm's avatar
Moritz Grimm committed
735
.Li /ezstream/decoders/decoder/program
736
and
Moritz Grimm's avatar
Moritz Grimm committed
737
.Li /ezstream/encoders/encoder/program .
738
739
.It Sy @a@
Replaced with the artist information.
740
Available in
Moritz Grimm's avatar
Moritz Grimm committed
741
742
.Li /ezstream/decoders/decoder/program ,
.Li /ezstream/encoders/encoder/program
743
and
Moritz Grimm's avatar
Moritz Grimm committed
744
.Li /ezstream/metadata/format_str .
745
746
.It Sy @t@
Replaced with the title information.
747
Available in
Moritz Grimm's avatar
Moritz Grimm committed
748
749
.Li /ezstream/decoders/decoder/program ,
.Li /ezstream/encoders/encoder/program
750
and
Moritz Grimm's avatar
Moritz Grimm committed
751
.Li /ezstream/metadata/format_str .
752
753
754
755
756
757
758
.It Sy @b@
Replaced with the album information.
Available in
.Li /ezstream/decoders/decoder/program ,
.Li /ezstream/encoders/encoder/program
and
.Li /ezstream/metadata/format_str .
759
.It Sy @s@
760
Replaced with the string returned by
Moritz Grimm's avatar
Moritz Grimm committed
761
762
.Li /ezstream/metadata/program
when called without any command line arguments.
763
Available only in
Moritz Grimm's avatar
Moritz Grimm committed
764
.Li /ezstream/metadata/format_str .
765
766
767
768
.El
.Ss The @M@ Placeholder
While all other placeholders are simply replaced with whatever data they are
associated with,
769
.Sq Li @M@
770
771
772
773
774
775
is context-sensitive.
The logic used by
.Nm
is the following:
.Bd -literal -offset indent
If ('@M@ is present')
Moritz Grimm's avatar
Moritz Grimm committed
776
    If (/ezstream/metadata/program AND /ezstream/metadata/format_str)
777
778
        Replace with format string result.
    Else
Moritz Grimm's avatar
Moritz Grimm committed
779
        If (NOT /ezstream/metadata/program AND '@t@ is present')
780
781
782
783
784
785
786
787
788
            Replace with empty string.
        else
            Replace with generated metadata string.
        Endif
    Endif
Endif
.Ed
.Pp
The generated metadata string for
789
.Sq Li @M@
790
is of the format
791
.Dq Em Artist - Title ,
792
793
794
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
795
796
797
.Dq Em Artist .
If neither artist nor title are available, the name of the media file \(em
without its file extension \(em is used.
798
799
800
801
802
803
.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
Moritz Grimm's avatar
Moritz Grimm committed
804
Metadata updates during runtime are done with a eccentric feature of libshout.
805
806
807
808
809
810
811
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
812
.Qq Em Title
813
field of a stream.
814
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
815
816
817
Additional limitations in Icecast may apply as well, where one historic
example is that of all possible Ogg-based streams, only Ogg Vorbis can have
its metadata manipulated.
818
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
819
820
821
The ID3v1 tags
.Pq relevant when streaming in MP3 format
do not specify any character encoding, so
822
.Nm
Moritz Grimm's avatar
Moritz Grimm committed
823
824
825
826
operates in a manner of
.Dq best effort .
In case of encoding issues, it may help to explicitly set a codeset to work
with via the
827
.Ev LC_CTYPE
828
829
830
831
832
833
834
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
Moritz Grimm's avatar
Moritz Grimm committed
835
to use only the characters available in the ISO-8859-1 codeset.
836
837
838
.Pp
External encoders may put additional, and possibly artificial, restrictions on
valid characters in metadata.
moritz's avatar
moritz committed
839
840
841
842
.Sh FILES
.Bl -tag -width "!!EXAMPLES_DIR!!" -compact
.It Pa !!EXAMPLES_DIR!!
Directory containing example configuration files for various uses of
843
844
.Nm ,
as well as example playlist and metadata scripts.
moritz's avatar
moritz committed
845
.El
846
.Sh SEE ALSO
847
.Xr ezstream-cfgmigrate 1 ,
848
.Xr ezstream-file.sh 1
moritz's avatar
moritz committed
849
850
851
852
853
.Sh AUTHORS
.Nm
was written by:
.Pp
.An Ed Zaleski Aq oddsock@oddsock.org
854
.An Moritz Grimm Aq mgrimm@mrsserver.net
moritz's avatar
moritz committed
855
.Pp
856
857
858
.An -nosplit
This manual was written by
.An Moritz Grimm .