path: root/audio/mp3val/mp3val.1

.\" 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