NAME

mp3lint - checks directories of audio files for problems

SYNOPSIS

mp3lint [-natsfiqdch] [-T tool] [-X tool] (file.mp3|dir)...

DESCRIPTION

mp3lint is a tool to check collections of audio files for various problems. It is highly configurable, allowing you to specify your preferred format for filenames, minimum bitrate, tests to ignore, etc. Formats checked are currently mp3, ogg, wav, flac, au, and m3u playlists. mp3lint is implemented as seperate tools (perl modules), each of which implements a set of tests.

To see which tools and tests are available, see mp3lint-tools(3).

To find out about configuring mp3lint, see mp3lintrc(5).

To find out about suppressing messages you don't care about, see mp3lintskip(1).

To find out about summarising the messages from mp3lint, see mp3lintsum(1)

QUICKSTART

For a first run, try mp3lint -n musicdir/

To check for supplementary programs used by mp3lint, use mp3lint -c

If the number of messages from mp3lint is overwhelming, use mp3lintsum(1) to summarise them.

Later, you will want to configure your .mp3lintrc to specify your filename formats, etc. (See mp3lintrc(5)) When you have done that, you can try again without the -n flag to run the filename tests too.

When you have fixed all the problems you can/want to fix, run mp3lint musicdir/ |mp3lintskip -v which will tell mp3lint to ignore all current warnings in future, and only tell you about new ones.

OPTIONS

-n: Skip filename related tests
-a: If it cannot work out from a files location whether to treat it as an album track or non-album track, it defaults to album track.
This is the same as setting the $format_default configuration variable (see mp3lintrc(5)) to "album", and overrides that setting.
-t: If it cannot work out from a files location whether to treat it as an album track or non-album track, it defaults to non-album (standalone) track.
This is the same as setting the $format_default configuration variable to "track", and overrides that setting.
-s: If it cannot work out from a files location whether to treat it as an album track or non-album track, it defaults to skipping all name-related tests.
This is the same as setting the $format_default configuration variable to "album", and overrides that setting.
-f: Fix problems, where possible. Currently it only fixes permissions (filesys:perms) and various filename formatting problems (filename:caps, filename:ext, filename:disc, filename:the and filename:paren).
WARNING: All the code for skipping messages (see mp3lintskip(1)) works by postprocessing the output, which means you cannot use it to disable particular fixes. Use -f with care, and make sure you are happy with your configuration (see mp3lintrc(5)) first.
-i: Ignore .mp3lintskip files
-q: Quick scan (avoid timeconsuming tests)
-d: Debug mp3lint
-T tool1,tool2: Just run named tools (default: run all tools)
-X tool1,tool2: Skip named tools
-c: Report on which of the supplementary programs used by mp3lint are installed. mp3lint will still work without them, but some tests will be disabled.
-h: Brief usage summary
file.mp3|dir: Files and/or directories to check. If given a directory, mp3lint checks all files and dirs in it recursively.

OUTPUT

All warnings display a single line message in a common format. This consists of either 4 or 5 fields, separated by colons (':').

The fields are as follows:

toolname:test:description:details:filename

The first 3 fields contain constant text, suitable for filtering. See mp3lintskip(1) and $lint_skip in mp3lintrc(5) for more information.

The details field is optional and does not appear in all messages.

Examples

With the details field:

wav:samplerate:low samplerate:8000 Hz (should be 44100Hz):./skipname/u-law.wav

without the details field:

filename:ext:uppercase extension:./skipname/mp3.WAV

Different tools have the same name for common tests, for instance the mp3info, flac, ogg, and wav tools all implement a samplerate test.

SOFTWARE NEEDED

To make full use of mp3lint, a number of pieces of software written by other people are needed. If something isn't installed, the relevant tests will silently be skipped (unless debug mode (-d) is on, in which case you will be warned).

To see which programs are installed, type mp3lint -c.

For debian, all needed software is listed as dependencies, so should be installed automatically. See below for more details

What you need and where to get it

perl

mp3lint was written using perl v5.6.1, but I've tried to avoid the latest features so it should hopefully run on any moderately recent perl 5. If perl isn't installed, look for a package from your OS vendor, or failing that, shake your head sadly and go to http://www.cpan.org/src/. Perl is not optional.

MP3::Archive

Available from http://nessie.mcc.ac.uk/~ianb/projects/libmp3-archive-perl/ Unlike the software that follows, MP3::Archive is required for mp3lint to work.

MP3::Tag (needed for "id3" tool)

This is a suite of perl modules for handling id3V1/2 tags. Hopefully it can be installed by typing (as root):

        # perl -MCPAN -e shell
        cpan> install MP3::Tag
        cpan> quit

If you have problems with the CPAN client, download MP3::Tag from http://www.cpan.org/modules/by-module/MP3/tagged-0.40.tar.gz (or any later version).

This follows the standard perl installation procedure as used by mp3lint, ie unpack, "perl Makefile.PL", "make", "make install". You will need to be root for "make install".

The tagged package has a web page at http://tagged.sourceforge.net/

Text::Autoformat (needed for "filename" tool)

This is Damian Conway's incredibly smart text formatting module. If installed, it is used for working out filename capitalisation. If not, a crude internal version is used.

It is available on CPAN, and can be downloaded and installed using the same methods as MP3::Tag, above.

If you have problems with the CPAN client, download Text::Autoformat from http://www.cpan.org/modules/by-module/Text/Text-Autoformat-1.12.tar.gz (or any later version).

mp3info (needed for tool "mp3info")

There are two programs called mp3info available on the net. This expects the one that is at http://ibiblio.org/mp3info It is also the version that Debian users get if they type "apt-get install mp3info"

mp3_check (needed for tool "mp3check")

mp3_check is available from sourceforge, see http://sourceforge.net/project/?group_id=6126

On debian systems, it is known as "checkmp3" and can be installed by typing "apt-get install checkmp3" as root. The "mp3check" tool searches for either name.

ogginfo (needed for tool "ogg")

Available from http://www.vorbis.com/download_unix.psp

flac, metaflac (needed for tool "flac")

Available from http://flac.sourceforge.net/download.html

Other Required software you probably have

File::Find, File::stat, Cwd: These perl modules are a part of the standard distributions
md5sum (needed for tool "flac"): If you don't already have it installed, look for a "coreutils" or "textutils" package from your OS vendor, or see http://www.gnu.org/coreutils/
sort (needed for test suite): Any self-respecting unix box has this. If not, look in the same places as for "md5sum", above.
diff (needed for test suite): Unless your vendor hates you, you should have this too. If not, go to http://www.gnu.org/software/diffutils/. On debian systems, type "apt-get install diff" as root.

Debian users

If mp3lint was installed using a tool like apt-get(1), all needed software will have been installed via dependencies. If not (eg, you downloaded the .deb and used dpkg):

        # apt-get install libmp3-tag-perl mp3info checkmp3 vorbis-tools flac diff

You will also need to install libmp3-archive-perl, available from the same place you got mp3lint (see AVAILABILITY, below).

FILES

.mp3lintrc, /etc/mp3lintrc: Configuration files, see mp3lintrc(5) for details.
.mp3lintskip, $HOME/.mp3lintskip-global: Warnings to skip. See mp3lintskip(1) for details.

ENVIRONMENT

$MP3LINTRC: If set, uses this instead of $HOME/.mp3lintrc
$HOME: Used to find .mp3lintrc and .mp3lintskip-global
$PATH: Used to find auxillary programs needed by various tools.

PORTABILITY

mp3lint was developed in perl under linux. It should be trivial to get it working on any POSIX based system. If you get it working with windows, let me know.

BUGS

None known. Please report any found to ianb@nessie.mcc.ac.uk

I am especially interested in how well the code for filename formats works for other people's naming styles.

AUTHOR

Ian Beckwith <ianb@nessie.mcc.ac.uk>

AVAILABILITY

The latest version can be found at:

http://nessie.mcc.ac.uk/~ianb/projects/mp3lint/

COPYRIGHT

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.

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.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.