aboutsummaryrefslogtreecommitdiff
path: root/audio/fIcy/fIcy.1
blob: 2251f2d68482ae6142e112c411beee2f675ba0b1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "FICY 1"
.TH FICY 1 "2013-05-12" "1.0.18" "SlackBuilds.org"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
fIcy \- an icecast/shoutcast stream grabber suite
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
fIcy \fB[options]\fR \fBserver [port [path]]|url\fR
.PP
The main program. Takes directly a stream url and dumps the tracks on
the specified file/s and standard output, depending on the settings.
.PP
fPls \fB[options]\fR \fBfile|url\fR \fB[fIcy options]\fR
.PP
Playlist manager. Reads a playlist (local or remote) and manages fIcy
retries/timeouts/errors, forwarding the specified flags.
.PP
fResync \fB[options]\fR \fBfile\fR
.PP
\&\s-1MPEG\s0 resyncing utility. Re-aligns head frame headers on dumped or
broken files. Usually needed for embedded hardware decoders or editing
software.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
fIcy is a small icecast/shoutcast stream grabber suite for use under shell
environment. Its goal is to automatically rip a stream into user customisable
files. It will work with \s-1ICY\s0 compatible streams, allowing you to either to save
the stream to disk or to pipe the output to a media player, or even both. fIcy,
among other uses, is ideal for batch/unattended recording of radio programs and
stream debugging.
.PP
The fIcy package includes:
.IP "\-" 4
fIcy itself, a stream separator/multiplexer,
.IP "\-" 4
fResync, a fast MPEG-resyncing utility,
.IP "\-" 4
fPls, a playlist frontend for fIcy.
.SH "OPTIONS"
.IX Header "OPTIONS"
.SS "fIcy options"
.IX Subsection "fIcy options"
.Vb 2
\&  \-d            Do not dump the output to stdout.
\&                Useful when only ripping.
\&
\&  \-E num        Enumerate files when song title [metadata] changes, starting at
\&                num. When 0, fIcy will try to find the highest unused file
\&                number automatically. Uses \-o as a prefix.
\&
\&  \-h            Help
\&
\&  \-c            Do not clobber files.
\&
\&  \-m            Use song title [metadata] when naming files. Uses \-o as prefix.
\&
\&  \-n            If the file exists create new one with .n as suffix.
\&
\&  \-p            When dumping to stdout consider writing errors as transient
\&                (that is: flush the output buffer until stdout is ready).
\&                Useful when you pipe the output to a media player and want to
\&                kill it while not interrupting the rip.
\&
\&  \-o file       Dump the output to file or use file as a prefix (depending on
\&                other settings). Hint: to dump without a prefix use "./".
\&
\&  \-s suffix     Use sfx as a suffix for new files.
\&                Hint: the .mp3/.m4a extension is NOT implicit.
\&
\&  \-t            Display song title [metadata] while ripping.
\&
\&  \-r            Remove/don\*(Aqt save partial chunks. This will skip the first
\&                chunk and remove the last one upon termination which are
\&                (supposedly) incomplete. To use in combination with \-m or \-E.
\&
\&  \-q file       Append "file name" sequence to file. The file name is written
\&                upon file completition. This may be used to trigger events and
\&                rejoin splitted parts with an external tool without \-E.
\&                fResync will use this file in the future.
\&
\&  \-x regex      Save only files whose title (NOT filename) matches against this
\&                (or one of these) extended regular expressions. Multiple \-x can
\&                be specified on the command line to form OR conditions. Dump
\&                unaffected.  Can be combined with \-X.
\&
\&  \-X regex      Do NOT save files whose title matches against this extended
\&                regular expression. Same semantics as \-x.
\&
\&  \-I file       Load include/exclude REs from file. Each line must be prefixed
\&                with + or \- to indicate whether it\*(Aqs a positive or negative
\&                expression (\-xX).
\&
\&  \-f expr       Filter titles through the specified coprocessor expression. The
\&                raw title is passed to the expression (doesn\*(Aqt include any
\&                additional prefixes/suffixes). As the result will be used
\&                internally, some limitations apply. Read carefully the
\&                Filtering_ section.
\&
\&  \-F file       Filter titles through the specified coprocessor script. Same
\&                semantics as \-f, but the expressions are loaded from a file
\&                instead. Conflicts with \-f.
\&
\&  \-C path       Specify the path of the external title rewriting coprocessor.
\&                Defaults to "sed". The executable must support the \*(Aq\-e\*(Aq, \*(Aq\-f\*(Aq
\&                flags and operate through stdin/out, like "sed".
\&
\&  \-M time       Maximum recording time. See Notes_.
\&
\&  \-i time       Maximum network idle time. Stops recording after the specified
\&                amount of time is passed without network activity. Defaults to
\&                0 (default tcp timeout).
\&
\&  \-a file       Read authentication credentials from file (the file must
\&                contain a line of the form user:password). Note that only the
\&                Basic HTTP authentication scheme is supported.
\&
\&  \-l num        Redirect follow limit. Defaults to 1. 0 disables redirection
\&                entirely.
.Ve
.SS "fResync options"
.IX Subsection "fResync options"
.Vb 4
\&  \-b            By default fResync maps the entire file into memory when
\&                operating. However this can create problems on loaded systems
\&                with large files or when simulating. This reverts to a
\&                buffered I/O mode. This flag is also implicit when simulating.
\&
\&  \-s            Simulate the process. Print on the standard output the starting
\&                sync offset and stream length, but don\*(Aqt modify the source
\&                file.
\&
\&  \-v            Verbose.
\&
\&  \-n frames     Require/decode at least n valid consecutive frames to validate
\&                the sync offset. Defaults to 6.
\&
\&  \-m len        Maximum frame length. Defaults to 1597. fResync uses this value
\&                to determine the maximal region of the file to be checked.
.Ve
.SS "fPls options"
.IX Subsection "fPls options"
.Vb 2
\&  \-P path       Specify a different name or full path for the fIcy executable
\&                (defaults to "fIcy").
\&
\&  \-v            Verbose.
\&
\&  \-R max        Specifies the maximal number of retries to do for each stream
\&                upon connection/read failure.
\&
\&  \-L max        Specifies the maximal number of loops to do for the entire
\&                playlist (\-1 for infinite).
\&
\&  \-T time       Wait time to pause after each failure.
\&
\&  \-M time       Maximum cumulative recording time. See Notes_.
\&
\&  \-i time       Maximum network idle time. Same as fIcy\*(Aqs when loading a
\&                playlist via http. Forwarded to fIcy.
\&
\&  \-a file       Read authentication credentials from file. Same as fIcy\*(Aqs when
\&                loading a playlist via http. The credentials are automatically
\&                forwarded to fIcy, but you can override them when needed.
\&
\&  \-l num        Redirect follow limit. Same as fIcy\*(Aqs when loading a playlist
\&                via http. Forwarded to fIcy.
\&
\&  \-d file       Run as a daemon, redirecting messages to file. fIcy\*(Aqs \-d
\&                option is enforced. As the process is chdir\-ed to the root
\&                directory you also have to specify absolute paths for all
\&                options, including fIcy\*(Aqs ones.
.Ve
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Use fIcy to display \s-1ICY\s0 titles while playing::
.PP
.Vb 1
\&        fPls http://example.com:8080/listen.pls \-t | mpg123 \-
.Ve
.PP
Rip a station until stopped::
.PP
.Vb 1
\&        fPls \-L\-1 http://netradio.invalid/listen.pls \-s.mp3 \-o./ \-cmrd
.Ve
.PP
Connect directly to the stream with server:port and /path::
.PP
.Vb 1
\&        fIcy \-s .mp3 \-o ./ \-md 123.123.123.123 8080 /path/to/stream
.Ve
.PP
Rip an .mp3 stream while playing, but allows the player to be restarted later
by using a named fifo (note that you can re/open \*(L"fifo\*(R" with any player)::
.PP
.Vb 3
\&        $ mkfifo fifo
\&        $ fIcy \-p ... > fifo
\&        $ mpg123 fifo
.Ve
.PP
Record your favourite program \*(L"\s-1XYZ\s0\*(R" usually on-air between 16:30\-17:00::
.PP
.Vb 3
\&        at 16:30
\&        fPls \-M 30m http://example.com/listen.pls \-o program.mp3 \-x XYZ
\&        ^D
.Ve
.PP
Cleanup a ripped and/or damaged mp3 file::
.PP
.Vb 1
\&        fResync file.mp3
.Ve
.SH "NOTES"
.IX Header "NOTES"
The output files produced by fIcy may miss audio framing information and
headers since the separation does not consider the audio data. For this reason,
your player 'may' (but should not) fail to reproduce the dump or output some
initial noise: this is expected. fResync can be used to cleanup \s-1MPEG\s0 files
after processing.
.PP
You can also use other tools such as mpgedit for cutting the file in arbitrary
positions without diminishing the quality. Assuming that your song spans across
three files (use \-q to know which ones), that's how to proceed::
.PP
.Vb 1
\&        cat 1.mp3 2.mp3 3.mp3 > temp.mp3 && xmpgedit temp.mp3
.Ve
.PP
Do *not* resync the files if you're going to post-process them this way:
fResync would remove at least one boundary frame on each file, while other
tools could also insert extra empty frames to silence the decoder!
.PP
The \-M flag supported by both fIcy and fPls accepts a time specification in
seconds, `HH:MM` or `N minutes/hours/days`. Time starts just after the
connection has been established, but without counting further delays. Also
beware that \-M specified in fPls means `cumulative recording time` (time
accumulates across retries/timeouts), while \-M specified in fIcy means `single
stream recording time` (recording stops at the first error or when the
specified time has elapsed).
.SH "FILTERING"
.IX Header "FILTERING"
Most online radio stations tend to put banners in the title that will be shown
in the player, and eventually result in the filename. To overcome to this (and
more), fIcy offers the possibility to rewrite each title through a normal sed
script via the \*(L"\-fF\*(R" flags. A real sed coprocess is used along the execution so
all of sed's power is available, but some limitations apply:
.PP
* Each line of input should result in one output line, and \s-1ONE\s0 \s-1ONLY\s0.
.PP
* Two consecutive identical titles will result in the second one
  being ignored (thus \s-1NOT\s0 splitting the stream). Consider this rule,
  as removing carefully the banner could result in a better separation.
.PP
* The resulting title will still apply for \-xXI as usual.
.PP
* Please note that the *title* is filtered, not the filename (which may
  still have some characters removed/modified). Use \-tv to see what is
  actually sent to the filter.
.PP
You can actually use any executable that works as a stream editor by specifying
the path with '\-C'. The executable must support the '\-e' (inline expression)
and '\-f' (script file) flags or, at least, ignore them. This allows for any
script or custom executable to be used when a \*(L"sed\*(R" script is considered
inadequate.
.SS "Filtering examples"
.IX Subsection "Filtering examples"
As an example, suppose your titles look like this::
.PP
.Vb 1
\&        Artist \- Title (radiobanner)
.Ve
.PP
You can write a sed expression or script containing::
.PP
.Vb 1
\&        s/ (radiobanner)$//
.Ve
.PP
to remove the trailing part. This facility can also be used to uniform file
names, invert Artist/Title positions and so on. Clever use of the pattern space
can also be used to merge albums. sed alone can be used to debug expressions,
eg::
.PP
.Vb 1
\&        echo "test title" | sed \-e \*(Aqexpr\*(Aq
.Ve
.PP
Refer to the \fIsed\fR\|(1) manual for a complete list of commands you can use.
.SH "DISCLAIMER"
.IX Header "DISCLAIMER"
We would like to remind you that saving streams containing copyrighted material
without explicit consent is *ILLEGAL*. For stream administrators, please see
our statement in the \s-1FAQ\s0.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
bfr <http://www.glines.org/software/bfr>
.PP
.Vb 1
\&        Audio\-oriented rebuffering tool. Ideal for lousy streams.
.Ve
.PP
mpgedit <http://www.mpgedit.org/>
.PP
.Vb 1
\&        Frame\-level mp3 cutting tool.
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
fIcy was written by Yuri D'Elia (\fIwavexx@users.sf.net\fR) and
David Leonardi (\fIdavid@mediavitamin.com\fR)
.PP
This manual page by B. Watson for the SlackBuilds.org project. It may
be used by anyone.