ezstream.1.in.in 21.8 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
.It Sy \&<name\ /\&>
Set the name of the stream configuration.
.Pp
The name is case-aware, but not case-sensitive.
.Pp
308
309
310
311
.Em Note:
At this time, only the stream configuration with the default name is
used and must be present.
.Pp
312
313
Default:
.Ar default
Moritz Grimm's avatar
Moritz Grimm committed
314
.It Sy \&<mountpoint\ /\&>
moritz's avatar
moritz committed
315
.Pq Mandatory.
Moritz Grimm's avatar
Moritz Grimm committed
316
Stream mountpoint on the server.
317
318
319
320
321
322
323
324
325
326
.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
327
328
329
330
331
332
333
334
335
.It Sy \&<intake\ /\&>
Use the intake
.Po
input media
.Pc
configuration with the provided symbolic name for this stream.
.Pp
Default:
.Ar default
336
337
338
339
340
341
342
343
344
.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
345
346
347
.Bl -tag -width Matroska -compact
.It Ar Ogg
Ogg media format
348
349
.It Ar MP3
MP3 audio format
Moritz Grimm's avatar
Moritz Grimm committed
350
351
352
353
.It Ar WebM
WebM media format
.It Ar Matroska
Matroska media format
354
355
356
357
358
359
360
361
362
363
364
365
366
.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
367
368
369
370
Informational name of the broadcast.
.Pp
Default:
.Em none
371
.It Sy \&<stream_url\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
372
373
374
375
Informational URL associated with the broadcast, e.g. the web site.
.Pp
Default:
.Em none
376
.It Sy \&<stream_genre\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
377
378
379
380
Informational genre of the broadcast.
.Pp
Default:
.Em none
381
.It Sy \&<stream_description\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
382
383
384
385
Informational description of the broadcast.
.Pp
Default:
.Em none
386
.It Sy \&<stream_quality\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
387
388
389
390
Informational quality setting of the VBR broadcast.
.Pp
Default:
.Em none
391
.It Sy \&<stream_bitrate\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
392
393
394
395
Informational bitrate setting of the CBR broadcast.
.Pp
Default:
.Em none
396
.It Sy \&<stream_samplerate\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
397
398
399
400
Informational sample rate of the broadcast audio.
.Pp
Default:
.Em none
401
.It Sy \&<stream_channels\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
402
403
404
405
406
Informational number of audio channels of the broadcast.
.Pp
Default:
.Em none
.El
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
.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
423
.Bl -tag -width -Ds
424
.It Sy \&<intake\ /\&>
moritz's avatar
moritz committed
425
.Pq Mandatory.
Moritz Grimm's avatar
Moritz Grimm committed
426
427
This element contains the entire input media configuration as child elements.
Its parent is the
428
.Sy \&<intakes\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
429
430
element.
.El
431
.Ss Intake configuration
Moritz Grimm's avatar
Moritz Grimm committed
432
.Bl -tag -width -Ds
433
434
435
436
437
438
439
440
441
.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
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
.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
460
461
462
463
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
464
465
466
467
468
469
470
.It Ar program
The input is an executable
.Dq Playlist Program .
See
.Xr SCRIPTING
for more information.
.It Ar stdin
471
472
The input is read from standard input and streamed as-is without any
reencoding.
Moritz Grimm's avatar
Moritz Grimm committed
473
474
475
476
477
.El
.It Sy \&<filename\ /\&>
The input media file name; mandatory for all but the
.Ar stdin
type.
moritz's avatar
moritz committed
478
.It Sy \&<shuffle\ /\&>
Moritz Grimm's avatar
Moritz Grimm committed
479
480
481
482
483
484
485
486
487
488
489
490
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
491
.Nm
Moritz Grimm's avatar
Moritz Grimm committed
492
should exit after streaming its media input, or start over.
493
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
.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.
521
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
522
523
524
Default:
.Em use metadata as contained in media files
.It Sy \&<format_str\ /\&>
525
Set the format of the string that should be used for the
526
.Sq Li @M@
Moritz Grimm's avatar
Moritz Grimm committed
527
placeholder, when quering for metadata from an executable.
528
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
529
Default:
530
.Li @a@ - @t@
Moritz Grimm's avatar
Moritz Grimm committed
531
532
533
534
535
536
537
538
539
540
541
.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
542
.Pq in seconds
Moritz Grimm's avatar
Moritz Grimm committed
543
544
545
546
547
548
549
550
551
552
553
554
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
555
.El
Moritz Grimm's avatar
Moritz Grimm committed
556
557
558
559
560
561
562
563
564
565
566
567
.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
568
.Bl -tag -width -Ds
Moritz Grimm's avatar
Moritz Grimm committed
569
570
571
572
.It Sy \&<decoders\ /\&>
This element contains all decoder blocks as child elements.
Its parent is the
.Sy \&<ezstream\ /\&>
573
element.
moritz's avatar
moritz committed
574
.El
Moritz Grimm's avatar
Moritz Grimm committed
575
.Ss Decoder block
576
.Bl -tag -width -Ds
Moritz Grimm's avatar
Moritz Grimm committed
577
578
579
580
581
582
583
584
585
586
.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.
587
588
.Pp
The name is case-aware, but not case-sensitive.
Moritz Grimm's avatar
Moritz Grimm committed
589
590
.Pp
Default:
591
.Ar default
Moritz Grimm's avatar
Moritz Grimm committed
592
593
594
595
596
597
598
.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
599
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
600
601
602
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.
603
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
604
605
606
607
608
609
610
611
612
613
614
615
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.
616
617
.Pp
A filename extension can only be associated with one decoder.
Moritz Grimm's avatar
Moritz Grimm committed
618
619
620
621
622
623
624
.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\ /\&>
625
element.
Moritz Grimm's avatar
Moritz Grimm committed
626
627
628
629
630
631
632
633
634
635
636
637
638
.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.
639
640
Set the name of the encoder configuration.
This may be referenced in a
Moritz Grimm's avatar
Moritz Grimm committed
641
642
643
644
.Sy \&<stream\ /\&>
block in case (re)encoding is desired.
.Pp
The name is case-aware, but not case-sensitive.
645
646
647
.Pp
Default:
.Ar default
Moritz Grimm's avatar
Moritz Grimm committed
648
649
650
651
652
653
654
655
.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.
656
Set the full command line to encode the
Moritz Grimm's avatar
Moritz Grimm committed
657
658
.Dq canonical internal format
from standard input into a supported stream format on standard output.
moritz's avatar
moritz committed
659
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
660
Metadata placeholders may be used here.
moritz's avatar
moritz committed
661
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
662
663
Example:
.Dl \&<program\&>oggenc -r -q 1.5 -t @M@ -\&</program\&>
moritz's avatar
moritz committed
664
.El
665
666
667
668
669
670
671
672
673
674
675
676
677
678
.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
679
The program must not require arbitrary command line options to function.
680
681
682
683
684
685
686
687
688
689
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.
690
691
692
This is significant when the
.Li \&<stream_once/\&>
option is enabled.
693
694
695
696
697
698
699
.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
700
with a command line argument that the program does not support.
701
.It
Moritz Grimm's avatar
Moritz Grimm committed
702
When called without command line arguments, the program should return a
703
704
complete string that should be used for metadata.
.It
Moritz Grimm's avatar
Moritz Grimm committed
705
When called with the command line argument
706
.Qq Li artist ,
707
708
709
the program should return only the artist information of the metadata.
.Pq Optional.
.It
Moritz Grimm's avatar
Moritz Grimm committed
710
When called with the command line argument
711
.Qq Li title ,
712
713
the program should return only the title information of the metadata.
.Pq Optional.
714
.It
715
The supplied metadata must be encoded in UTF-8.
716
.El
717
718
719
720
721
.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.
722
723
.Pp
.Em Note:
Moritz Grimm's avatar
Moritz Grimm committed
724
725
726
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.
727
.Em \&Do not add any additional quoting!
728
729
730
731
.Ss Metadata Placeholders
.Bl -tag -width -Ds
.It Sy @T@
Replaced with the media file name.
732
Required in
Moritz Grimm's avatar
Moritz Grimm committed
733
734
735
.Li /ezstream/decoders/decoder/program .
Available in
.Li /ezstream/metadata/format_str .
736
737
.It Sy @M@
Replaced with a metadata string.
Moritz Grimm's avatar
Moritz Grimm committed
738
.Pq See below for a detailed explanation.
739
Available in
Moritz Grimm's avatar
Moritz Grimm committed
740
.Li /ezstream/decoders/decoder/program
741
and
Moritz Grimm's avatar
Moritz Grimm committed
742
.Li /ezstream/encoders/encoder/program .
743
744
.It Sy @a@
Replaced with the artist information.
745
Available in
Moritz Grimm's avatar
Moritz Grimm committed
746
747
.Li /ezstream/decoders/decoder/program ,
.Li /ezstream/encoders/encoder/program
748
and
Moritz Grimm's avatar
Moritz Grimm committed
749
.Li /ezstream/metadata/format_str .
750
751
.It Sy @t@
Replaced with the title information.
752
Available in
Moritz Grimm's avatar
Moritz Grimm committed
753
754
.Li /ezstream/decoders/decoder/program ,
.Li /ezstream/encoders/encoder/program
755
and
Moritz Grimm's avatar
Moritz Grimm committed
756
.Li /ezstream/metadata/format_str .
757
758
759
760
761
762
763
.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 .
764
.It Sy @s@
765
Replaced with the string returned by
Moritz Grimm's avatar
Moritz Grimm committed
766
767
.Li /ezstream/metadata/program
when called without any command line arguments.
768
Available only in
Moritz Grimm's avatar
Moritz Grimm committed
769
.Li /ezstream/metadata/format_str .
770
771
772
773
.El
.Ss The @M@ Placeholder
While all other placeholders are simply replaced with whatever data they are
associated with,
774
.Sq Li @M@
775
776
777
778
779
780
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
781
    If (/ezstream/metadata/program AND /ezstream/metadata/format_str)
782
783
        Replace with format string result.
    Else
Moritz Grimm's avatar
Moritz Grimm committed
784
        If (NOT /ezstream/metadata/program AND '@t@ is present')
785
786
787
788
789
790
791
792
793
            Replace with empty string.
        else
            Replace with generated metadata string.
        Endif
    Endif
Endif
.Ed
.Pp
The generated metadata string for
794
.Sq Li @M@
795
is of the format
796
.Dq Em Artist - Title ,
797
798
799
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
800
801
802
.Dq Em Artist .
If neither artist nor title are available, the name of the media file \(em
without its file extension \(em is used.
803
804
805
806
807
808
.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
809
Metadata updates during runtime are done with a eccentric feature of libshout.
810
811
812
813
814
815
816
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
817
.Qq Em Title
818
field of a stream.
819
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
820
821
822
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.
823
.Pp
Moritz Grimm's avatar
Moritz Grimm committed
824
825
826
The ID3v1 tags
.Pq relevant when streaming in MP3 format
do not specify any character encoding, so
827
.Nm
Moritz Grimm's avatar
Moritz Grimm committed
828
829
830
831
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
832
.Ev LC_CTYPE
833
834
835
836
837
838
839
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
840
to use only the characters available in the ISO-8859-1 codeset.
841
842
843
.Pp
External encoders may put additional, and possibly artificial, restrictions on
valid characters in metadata.
moritz's avatar
moritz committed
844
845
846
847
.Sh FILES
.Bl -tag -width "!!EXAMPLES_DIR!!" -compact
.It Pa !!EXAMPLES_DIR!!
Directory containing example configuration files for various uses of
848
849
.Nm ,
as well as example playlist and metadata scripts.
moritz's avatar
moritz committed
850
.El
851
.Sh SEE ALSO
852
.Xr ezstream-cfgmigrate 1 ,
853
.Xr ezstream-file.sh 1
moritz's avatar
moritz committed
854
855
856
857
858
.Sh AUTHORS
.Nm
was written by:
.Pp
.An Ed Zaleski Aq oddsock@oddsock.org
859
.An Moritz Grimm Aq mgrimm@mrsserver.net
moritz's avatar
moritz committed
860
.Pp
861
862
863
.An -nosplit
This manual was written by
.An Moritz Grimm .