## MP3val 0.1.8: Documentation

1. Introduction
2. Why to use it?
3. How to use it?
4. Interpreting the output
5. Licensing and copyright

### 1. Introduction.

MP3val is a small, high-speed tool for MPEG audio files validation and (optionally) fixing problems. It was primarily designed for verification of MPEG 1 Layer III (MP3) files, but supports also other MPEG versions and layers. It can be useful for finding corrupted files (e.g. incompletely downloaded).

MP3val supports:

- MPEG-1, 2, 2.5; Layers I, II, III
- ID3v1 tags (must be at the very end of the file)
- ID3v2 tags (must be at the very beginning of the file)
- APEv2 tags

This program can be compiled both for Windows and major Unix systems.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

The latest version of MP3val (including sources) can be downloaded from the official home page.

### 2. Why to use it?

MPEG is a streamable format, that is, it is optimized for quick and easy recovery from errors. MP3 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.

MP3val can assure you that your files are consistent in the terms of MPEG 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 VBR 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.

MP3val can also fix most of the problems. Be careful: although MP3val can repair even files with MPEG stream errors, it is recommended that you find a "good" copy of this file, because a "click" sound usually can't be removed, the repaired file will only look like good.

### 3. How to use it?

MP3val is a console program. Command-line syntax:

    	mp3val <files to validate> <options>

<files to validate> - MPEG audio file(s) name(s). Can contain wildcards.

Options:

Option | Description
-l<log file> | Log file name. If this argument is missing, all the information will be written to stdout.
-f | Try to fix errors.
-si | Suppress INFO messages.
-nb | Delete .bak files that were created during file rebuilding. Use this option together with -f.
-t | Keep file timestamps. Use this option together with -f.
-p | Pipe mode (receive input file names from stdin). Intended for interaction with frontends. <files to validate> is ignored in this case.
-v | Print version and exit

Example:

    	mp3val my_song.mp3 -lout.log -f

MP3val will give information about the file with the name specified. Any errors or inconsistencies will result in a "WARNING" 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 MPEG audio file, an "ERROR: invalid file format" message will be generated.

### 4. Interpreting the output.

WARNING message | Fixable? | Comments
Too few MPEG frames (it's unlikely that this is a MPEG audio file) | - | Probably this is not a MPEG audio file, but MP3val has detected a couple of MPEG frames in it. Most likely this is a false positive.
Garbage at the beginning of the file | + | There are some unknown data at the beginning of the file (before the first MPEG frame). It can be an unsupported tag with metadata, but in most cases it is only garbage. "Fixing" means here a removal of these data.
Garbage at the end of the file | + | Like previous.
MPEG stream error, resynchronized successfully | + | Normally, each MPEG frame must be followed by a next MPEG frame (or a metadata block), otherwise this message is generated. MPEG 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 "fixing" this error will remove garbage, but in most cases "fixed" file will not sound better, that's why it is strongly recommended to find a "good" copy of the file.
This is a RIFF file, not MPEG stream | + | A common way for storing a MPEG audio file is simply to write MPEG frames one-by-one. MP1/MP2/MP3 files are organized so. MPEG audio data can also be encapsulated in the RIFF container (better known as WAV file). The RIFF container shouldn't be used unless the file has "WAV" extension.
It seems that file is truncated or there is garbage at the end of the file | + | 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. "Fixing" means here a removal of the last frame.
Wrong number of MPEG frames specified in Xing header | + | MPEG audio files don't have any special header, each frame has its own header instead. However, it can cause problems when "seeking" 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 "VBR header" is sometimes included in the first MPEG frame. This message is generated if this header contains false information about the total number of MPEG frames.
Wrong number of MPEG data bytes specified in Xing header | + | This message is generated when the Xing header contains false information about the total size of MPEG data in the file. See the previous message.
Wrong number of MPEG frames specified in VBRI header | + | Like with Xing header. VBRI is the other way to store VBR information in the first MPEG frame, but it seems to be used much more rarely.
Wrong number of MPEG data bytes specified in VBRI header | + | Like with Xing header. VBRI is the other way to store VBR information in the first MPEG frame, but it seems to be used much more rarely.
VBR detected, but no VBR header is present. Seeking may not work properly | - | Files encoded with VBR should have a VBR header (either Xing or VBRI), otherwise seeking can be broken. This will be fixable in the future versions.
Wrong CRC in ... frames | + | Some frames in the file are protected by CRC, 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 CRC, 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 CRC.
Non-layer-III frame encountered | - | MP3val was primarily designed for MP3 files. That's why it warns about MPEG frames with layers other than III. If it is an MP2 or MP1 file, this warning should be ignored. If you want to fix this issue, you should reencode the file.
Different MPEG versions or layers in one file | - | Mixing different MPEG versions and/or layers in one file is not very good. As in the previous case, this issue can be fixed only by reencoding.
Several APEv2 tags in one file | + | Normally there would be only one APEv2 tag in the file.
No supported tags in the file | - | This is only a warning. It's a good practice to store metadata in tags.

### 5. Licensing and copyright

Copyright (c) 2005-2009 by Alexey Kuznetsov (ring0) and Eugen Tikhonov (jetsys).

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

Contacts: mp3val at ring0 dot pp dot ru