summaryrefslogtreecommitdiff
path: root/audio/mp3val/mp3val.1
blob: b042753f9d8f02852722092b7f9d3f2a944fd924 (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
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "MP3VAL 1"
.TH MP3VAL 1 "2014-09-22" "0.1.8" "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 "MP3val 0.1.8: Documentation"
.IX Header "MP3val 0.1.8: Documentation"
.IP "1. Introduction" 4
.IX Item "1. Introduction"
.PD 0
.IP "2. Why to use it?" 4
.IX Item "2. Why to use it?"
.IP "3. How to use it?" 4
.IX Item "3. How to use it?"
.IP "4. Interpreting the output" 4
.IX Item "4. Interpreting the output"
.IP "5. Licensing and copyright" 4
.IX Item "5. Licensing and copyright"
.PD
.SS "1. Introduction."
.IX Subsection "1. Introduction."
MP3val is a small, high-speed tool for \s-1MPEG\s0 audio files validation and
(optionally) fixing problems. It was primarily designed for
verification of \s-1MPEG 1\s0 Layer \s-1III \s0(\s-1MP3\s0) files, but supports also other
\&\s-1MPEG\s0 versions and layers. It can be useful for finding corrupted files
(e.g. incompletely downloaded).
.PP
MP3val supports:
.IP "\(bu" 4
\&\s-1MPEG\-1, 2, 2.5\s0; Layers I, \s-1II, III\s0
.IP "\(bu" 4
ID3v1 tags (must be at the very end of the file)
.IP "\(bu" 4
ID3v2 tags (must be at the very beginning of the file)
.IP "\(bu" 4
APEv2 tags
.PP
This program can be compiled both for Windows and major Unix systems.
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of the \s-1GNU\s0 General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
.PP
The latest version of MP3val (including sources) can be downloaded from
the official home page.
.SS "2. Why to use it?"
.IX Subsection "2. Why to use it?"
\&\s-1MPEG\s0 is a streamable format, that is, it is optimized for quick and
easy recovery from errors. \s-1MP3\s0 decoders are very tolerant to
inconsistencies in the input file. Most players even don't report to
user about stream errors. So, as a rule, user doesn't know whether his
files are valid or broken. But using broken files can eventually lead
to problems during playback on certain software/hardware.
.PP
MP3val can assure you that your files are consistent in the terms of
\&\s-1MPEG\s0 frames, that is, it ensures that the file can be easily split into
the frames and doesn't contain garbage. It checks also some other
issues, such as track length stored in the \s-1VBR\s0 header. Checking by
MP3val isn't a full test for compliance with existing formal and
informal standards. MP3val neither decodes audio data nor checks for
data validity in the frame.
.PP
MP3val can also fix most of the problems. Be careful: although MP3val
can repair even files with \s-1MPEG\s0 stream errors, it is recommended that
you find a \*(L"good\*(R" copy of this file, because a \*(L"click\*(R" sound usually
can't be removed, the repaired file will only look like good.
.SS "3. How to use it?"
.IX Subsection "3. How to use it?"
MP3val is a console program. Command-line syntax:
.PP
.Vb 1
\&        mp3val <files to validate> <options>
.Ve
.PP
\&\fI<files to validate>\fR \- \s-1MPEG\s0 audio file(s) name(s). Can
contain wildcards.
.PP
\&\fIOptions\fR:
.PP
\&\fBOption\fR
.PP
\&\fBDescription\fR
.PP
\&\-l\fI<log file>\fR
.PP
Log file name. If this argument is missing, all the information will be
written to stdout.
.PP
\&\-f
.PP
Try to fix errors.
.PP
\&\-si
.PP
Suppress \s-1INFO\s0 messages.
.PP
\&\-nb
.PP
Delete .bak files that were created during file rebuilding. Use this
option together with \-f.
.PP
\&\-t
.PP
Keep file timestamps. Use this option together with \-f.
.PP
\&\-p
.PP
Pipe mode (receive input file names from stdin). Intended for
interaction with frontends. \fI<files to validate>\fR is ignored
in this case.
.PP
\&\-v
.PP
Print version and exit
.PP
Example:
.PP
.Vb 1
\&        mp3val my_song.mp3 \-lout.log \-f
.Ve
.PP
MP3val will give information about the file with the name specified.
Any errors or inconsistencies will result in a \*(L"\s-1WARNING\*(R"\s0 message. This
doesn't necessarily mean that the file is corrupted. See the next
section for details. If the file doesn't look like a \s-1MPEG\s0 audio file,
an \fI\*(L"\s-1ERROR:\s0 invalid file format\*(R"\fR message will be generated.
.SS "4. Interpreting the output."
.IX Subsection "4. Interpreting the output."
\&\fB\s-1WARNING\s0 message\fR
.PP
\&\fBFixable?\fR
.PP
\&\fBComments\fR
.PP
\&\fIToo few \s-1MPEG\s0 frames (it's unlikely that this is a \s-1MPEG\s0 audio file)\fR
.PP
\&\-
.PP
Probably this is not a \s-1MPEG\s0 audio file, but MP3val has detected a
couple of \s-1MPEG\s0 frames in it. Most likely this is a false positive.
.PP
\&\fIGarbage at the beginning of the file\fR
.PP
+
.PP
There are some unknown data at the beginning of the file (before the
first \s-1MPEG\s0 frame). It can be an unsupported tag with metadata, but in
most cases it is only garbage. \*(L"Fixing\*(R" means here a removal of these
data.
.PP
\&\fIGarbage at the end of the file\fR
.PP
+
.PP
Like previous.
.PP
\&\fI\s-1MPEG\s0 stream error, resynchronized successfully\fR
.PP
+
.PP
Normally, each \s-1MPEG\s0 frame must be followed by a next \s-1MPEG\s0 frame (or a
metadata block), otherwise this message is generated. \s-1MPEG\s0 stream
errors can be caused by garbage in the middle of the file (e.g. the
file was split into several parts, the tags were appended, and then
these parts were improperly merged) or by a data loss during transfer
or storage. Note that \*(L"fixing\*(R" this error will remove garbage, but in
most cases \*(L"fixed\*(R" file will not sound better, that's why it is
strongly recommended to find a \*(L"good\*(R" copy of the file.
.PP
\&\fIThis is a \s-1RIFF\s0 file, not \s-1MPEG\s0 stream\fR
.PP
+
.PP
A common way for storing a \s-1MPEG\s0 audio file is simply to write \s-1MPEG\s0
frames one-by-one. \s-1MP1/MP2/MP3\s0 files are organized so. \s-1MPEG\s0 audio data
can also be encapsulated in the \s-1RIFF\s0 container (better known as \s-1WAV\s0
file). The \s-1RIFF\s0 container shouldn't be used unless the file has \*(L"\s-1WAV\*(R"\s0
extension.
.PP
\&\fIIt seems that file is truncated or there is garbage at the end of the
file\fR
.PP
+
.PP
This message is generated when the length of the last frame (according
to its header) is greater than the amount of data from its beginning to
the end of the file. As a rule, it means that the file was truncated,
however, there can be garbage at its end. \*(L"Fixing\*(R" means here a removal
of the last frame.
.PP
\&\fIWrong number of \s-1MPEG\s0 frames specified in Xing header\fR
.PP
+
.PP
\&\s-1MPEG\s0 audio files don't have any special header, each frame has its own
header instead. However, it can cause problems when \*(L"seeking\*(R" in
variable bitrate files, because a decoder can't determine the exact
place in the file corresponding to the selected time. That's why a \*(L"\s-1VBR\s0
header\*(R" is sometimes included in the first \s-1MPEG\s0 frame. This message is
generated if this header contains false information about the total
number of \s-1MPEG\s0 frames.
.PP
\&\fIWrong number of \s-1MPEG\s0 data bytes specified in Xing header\fR
.PP
+
.PP
This message is generated when the Xing header contains false
information about the total size of \s-1MPEG\s0 data in the file. See the
previous message.
.PP
\&\fIWrong number of \s-1MPEG\s0 frames specified in \s-1VBRI\s0 header\fR
.PP
+
.PP
Like with Xing header. \s-1VBRI\s0 is the other way to store \s-1VBR\s0 information
in the first \s-1MPEG\s0 frame, but it seems to be used much more rarely.
.PP
\&\fIWrong number of \s-1MPEG\s0 data bytes specified in \s-1VBRI\s0 header\fR
.PP
+
.PP
Like with Xing header. \s-1VBRI\s0 is the other way to store \s-1VBR\s0 information
in the first \s-1MPEG\s0 frame, but it seems to be used much more rarely.
.PP
\&\fI\s-1VBR\s0 detected, but no \s-1VBR\s0 header is present. Seeking may not work
properly\fR
.PP
\&\-
.PP
Files encoded with \s-1VBR\s0 should have a \s-1VBR\s0 header (either Xing or \s-1VBRI\s0),
otherwise seeking can be broken. This will be fixable in the future
versions.
.PP
\&\fIWrong \s-1CRC\s0 in ... frames\fR
.PP
+
.PP
Some frames in the file are protected by \s-1CRC,\s0 but the checksum is
wrong. It means that either the file was encoded or processed by broken
software, or it was broken during storage or transmission. MP3val
reports a number of frames with incorrect \s-1CRC,\s0 which can be used as a
hint (if this number equals or is about the total number of frames,
then it's likely due to a bad encoder). Note that only a minority of
files is protected by \s-1CRC.\s0
.PP
\&\fINon-layer-III frame encountered\fR
.PP
\&\-
.PP
MP3val was primarily designed for \s-1MP3\s0 files. That's why it warns about
\&\s-1MPEG\s0 frames with layers other than \s-1III.\s0 If it is an \s-1MP2\s0 or \s-1MP1\s0 file,
this warning should be ignored. If you want to fix this issue, you
should reencode the file.
.PP
\&\fIDifferent \s-1MPEG\s0 versions or layers in one file\fR
.PP
\&\-
.PP
Mixing different \s-1MPEG\s0 versions and/or layers in one file is not very
good. As in the previous case, this issue can be fixed only by
reencoding.
.PP
\&\fISeveral APEv2 tags in one file\fR
.PP
+
.PP
Normally there would be only one APEv2 tag in the file.
.PP
\&\fINo supported tags in the file\fR
.PP
\&\-
.PP
This is only a warning. It's a good practice to store metadata in tags.
.SS "5. Licensing and copyright"
.IX Subsection "5. Licensing and copyright"
Copyright (c) 2005\-2009 by Alexey Kuznetsov (ring0) and Eugen Tikhonov
(jetsys).
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of the \s-1GNU\s0 General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
.PP
Contacts: mp3val at ring0 dot pp dot ru