NAME

mp3lint-tools - tools and tests available in mp3lint

DESCRIPTION

This file documents the tools available in mp3lint, and the tests provided by each tool.

TOOLS

au - Tool to check .au files

Checks au files (Sun/NeXT/DEC audio) by parsing the header.

Tests

data: Tests if file is a valid au file.
samplerate: Tests sample rate of au file is at least $lint_minsamplerate Hz.
Variables:

$lint_minsamplerate: Minimum sample rate in Hz (number, default 44100)

samplesize: Test samplesize of au file is at least $lint_minbitsize bits.
Variables:

$lint_minbitsize: (number, default 16)

channels: Tests file is stereo.

dir - Tool to check directories

Directory related tests. All tests performed by this tool are disabled if the -n option is given to mp3lint.

Tests

tracknums

Tests for non-consecutively numbered tracks.

artist

Checks the filename and directory versions of the artist name match.

To allow for multi-artist compilations, if the directory matches the regular expression $lint_various no warning is issued.

Variables:

$lint_various: (string (regular expression), default "\/Various\/")

album: Checks the filename and directory versions of the album match.

filename - Tool to check filenames

Tests various (often pedantic) features of the filename. All tests performed by this tool are disabled if the -n option is given to mp3lint.

Tests that test/fix directories are very cautious about whether to treat that directory as part of the music metadata. They err on the side of caution, and only check the directories if they match up with music files inside them.

This can cause directories to be unexpectedly skipped, if the filenames it finds within them are not valid. It also means you may need to run mp3lint more than once with the -f (fix) option, first to fix files, then to fix directories.

Tests

format

Checks to see the filename is in a valid format. See mp3lintrc(5) for details of how to specify filename formats. Only works on filenames.

disc

If the filename or directory name contains something resembling (Disc 1), checks the spelling of "Disc", and that it is followed by a space then a number.

Possibly the most pedantic and debatable test, hence it is in the default list of tests to skip ($lint_skip)

If -f (fix) is enabled, it attempts to correct the problem.

ext

Checks the extension of the file. Complains if it is uppercase or .mp2

.mp2 files are often .mp3 files mislabelled, plus MPEG Layer 2 files are generally playable by most mp3 (Layer 3) players, so the utility of a .mp2 extension is dubious.

If -f (fix) is enabled, renames the file to correct the problem.

space

Checks if the filename (minus the extension) or directory name ends in a space, eg "Fade Into .mp3". This is often a sign that the filename has been truncated, preserving the extension.

the

Complains if the artist name begins with The.

This is another debatable test, so it is in the default list of messages to skip ($lint_skip)

It is arguably a good idea to remove "The" from the start of artist names, as it is often debatable whether or not they should have one, and it leads to extra confusion trying to find songs.

An exception is made for The The, for obvious reasons.

If -f (fix> is enabled, the file or directory is renamed to remove the leading "The ".

caps

Does a check of the filename or directory name capitalisation.

As it is quite picky, it is in the default list ($lint_skip) of messages to skip.

If installed, it uses Text::Autoformat to work out the correct format, otherwise it falls back on a crude internal method.

If -f (fix) is enabled (and Text::Autoformat is installed), it renames the file or directory to correct the capitalisation.

Variables:

$lint_case: (string, default "highlight")
Capitalisation style to use. Available values:

highlight: Capitalises everything except "unimportant" words. This is the default.
title: Capitalises every word.
sentence: Capitalises the first word.
upper: Uppercases everything.
lower: Lowercases everything.

paren: Checks that brackets in the filename or directory name balance. Arguably pedantic, but it is useful for catching truncated filenames, eg "Foo (remixed by Fatb.mp3"
If -f (fix> is enabled, it renames the file/directory to correct mismatched parentheses, but leaves unclosed parentheses alone as probably a symptom of a deeper problem (truncated filenames).

filesys - Tool for misc filesys tests

Various checks that don't belong anywhere else and are related to the file system.

Tests

empty: Checks for zero-length files.
access: Checks for non-existant or unreadable files and broken symbolic links.
perms: Checks permissions. If -F (fix) is specified, attempts to fix incorrect permissions.
Variables:

$perms_file: (octal number, default 0644 (rw-r--r--))
$perms_dir: (octal number, default 0755 (rwxr-xr-x))

For details on the encoding of permissions, see chmod(1), but briefly, the value consists of a leading 0, then 3 digits, one each for the user, group, and everyone else. Each digit is the sum of the values 4 for write, 2 for read, and 1 for execute.

For instance, if you wanted full access for yourself, read and execute for your group, and no access for anyone else, you would use (r+w+x = 4+2+1 =) 7 for user, (r+x = 4+1=) 5 for group and 0 for world (everyone else). Putting this together, we get 0750

Example values:

        0700 = rwx------
        0751 = rwxr-x--x
        0604 = rw-----w-
        0124 = --x-w-r--

If you want to let other users on your machine read your files, use 0644 (rw-r--r--) for $perms_file and 0755 (rw-r--r--) for $perms_dir. If you want to keep your files private, use 0600 (rw-------) for $perms_file and 0700 (rwx------) for $perms_dir

Directories need to have their "x" flag set if you want people to be able to change into them.

It is essential that $perms_dir and $perms_file start with a 0, eg 0755 not 755, for them to correctly be interpreted as octal values.

flac - Tool to check .flac files

Checks .flac files using flac and metaflac from the flac distribution at http://flac.sourceforge.net/download.html

It also uses md5sum(1), see mp3lint(1) for more details on needed software.

Tests

tracknum: Tests for presence of a vorbis TRACKNUMBER comment, and compares it to the filename. If the -n option is given to mp3lint, this test only checks that the tracknum is a valid number, not that it matches the filename.
artist: Tests for presence of a vorbis ARTIST comment, and compares it to the filename. The filename test is suppressed if the -n option is given to mp3lint.
album: Tests for presence of a vorbis ALBUM comment, and compares it to the filename. The filename test is suppressed if the -n option is given to mp3lint.
track: Tests for presence of a vorbis TITLE comment (track name), and compares it to the filename. The filename test is suppressed if the -n option is given to mp3lint.
channels: Tests if flac is stereo
samplerate: Tests samplerate is at least $lint_minsamplerate Hz.
Variables:

$lint_minsamplerate: (number, default 44100 Hz)

samplesize: Tests sample bitsize is at least $lint_minbitsize bits.
Variables:

$lint_minbitsize: (number, default 16 bits)

md5sum: Decompresses and checksums audio using md5sum, and compares it to the md5 checksum for the original data, stored in the STREAMINFO metadata block.
Assumes the original uncompressed audio was signed and little-endian.

Bugs

Does not yet handle flac files embedded in .ogg files.

Does not yet parse id3 tags. Although the reference implementation only supports them to the extent of noticing and skipping them, some players use them.

id3 - Tool to check id3 tags

Checks ID3 tags in mp3 files using the MP3::Tag module

If your machine is set up correctly, the module 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/

Tests

tag: Checks for the existence of an id3 tag.
tracknum: Tests for a tracknumber tag (id3 v1.1 and v2.0+ only). Checks it is numeric and matches the filename. If the -n option is given to mp3lint, the filename test is skipped.
artist: Tests for an artist tag and compares it to the filename. This test is suppressed if the -n option is given to mp3lint.
album: Tests for an album tag and compares it to the filename. This test is suppressed if the -n option is given to mp3lint.
track: Tests for a song tag (track name) and compares it to the filename. This test is suppressed if the -n option is given to mp3lint.
compare: If a file has both id3v1 and id3v2 tags, tests they are the same.
warnings: Shows warnings generated by the MP3::Tag module, generally about unsupported id3 tag versions/features.

Caveats

The id3v1 tag format has very short fixed length fields. This often means that data is unavoidably truncated.

All tests that compare id3v1 data allow for this by only comparing up to the length of the id3v1 data. This currently affects the tests compare, artist, album, and track.

ID3v2.4 is not yet supported.

m3u - Tool to check .m3u playlists

Checks m3u playlists, although will also work if they are just lists of files.

Tests

playlist: Checks all the files mentioned in the m3u file exists. Attempts to be (slightly) smart about relative pathnames and backslashes for pathname delimiters. Complains if it finds drive letters in the filenames mentioned.

Bugs

Currently doesn't do anything with EXTINF comments.

mp3check - Tool to check mp3 files using mp3_check (or checkmp3)

Tests integrity of mp3 files using the mp3_check command. If quick mode (-q) is enabled, silently returns without doing anything.

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

See mp3lint(1) for more details on installing needed software.

Tests

framecheck: Tests integrity of mp3 with mp3_check. As mp3info and mp3_check often give different numbers of broken frames, both tests are run, and there are options to specify a minimum number of broken frames before complaining.
Variables:

$lint_maxbadframes_mp3check: number of bad frames to accept before complaining
(number, default 0)

mp3info - Tool to check mp3 files using mp3info

Tests mp3 files using the mp3info command. If quick mode (-q) is enabled, only does a full mp3 scan if the mp3 is variable bit rate (vbr).

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"

Tests

channels: Tests mp3 is stereo.
samplerate: Tests mp3 samplerate is at least $lint_minsamplerate Hz.
Variables:

$lint_minsamplerate: minimum samplerate to accept (number, default 44100)

bitrate: Tests mp3 is at least $lint_minbitrate_mp3 kbps. To allow for vbr mp3s with an average bitrate slightly lower than the target, you may wish to lower it slightly, eg for 128kbps, specify 120. Variables:

$lint_minbitrate_mp3: minimum bitrate to accept (number, default 120)

framecheck: Tests for broken mp3s. As mp3info and mp3_check often give different numbers of broken frames, both tests are run, and there are options to specify a minimum number of broken frames before complaining.
Variables:

$lint_maxbadframes_mp3info: number of bad frames to accept before complaining (number, default 0)

ogg - Tool to check .ogg files

Checks Ogg Vorbis files. Requires the program "ogginfo", available from http://www.vorbis.com/download_unix.psp

On debian systems, it can be installed by typing "apt-get install vorbis-tools" as root.

Tests

header: Tests integrity of Ogg header.
short: Tests if Ogg is truncated.
tags: Tests for corrupt comment tags
tracknum: Tests if Ogg has a TRACKNUMBER comment, that it is a number, and matches the filename. If the -n option is given to mp3lint, this test only checks that the tracknum is a valid number, not that it matches the filename.
artist: Tests if Ogg has a ARTIST comment, and that it matches the filename. The filename test is suppressed if the -n option is given to mp3lint.
album: Tests if Ogg has a ALBUM comment, and that it matches the filename. The filename test is suppressed if the -n option is given to mp3lint.
track: Tests if Ogg has a TITLE comment (track name), and that it matches the filename. The filename test is suppressed if the -n option is given to mp3lint.
serial: Tests if Ogg has multiple streams in it by the presence of multiple serial numbers.
bitrate: Tests Ogg nominal (requested) bitrate is at least $lint_minbitrate_ogg kbps.
Variables:

$lint_minbitrate_ogg: (number, default 100 kbps)

channels: Tests if Ogg is stereo.
samplerate: Tests Ogg samplerate is at least $lint_minsamplerate Hz.
Variables:

$lint_minsamplerate: (number, default 44100 Hz)

stream: Tests integrity of Ogg stream[s] in file.

Bugs

Does not yet handle flac files embedded in .ogg files.

wav - Tool to check .wav files

Checks wav files by parsing the RIFF header.

Tests

allow: If $lint_allow_wav is set to zero, complains if it finds a .wav file. This is useful if the only use you have for wav files is while ripping, so a .wav file means a problem with your ripping process.
Variables:

$lint_allow_wav: Whether to complain (boolean (1/0), default 1)

samplerate: Tests sample rate of wav file is at least $lint_minsamplerate Hz.
Variables:

$lint_minsamplerate: Minimum sample rate in Hz (number, default 44100)

samplesize: Test samplesize of wav file is at least $lint_minbitsize bits.
Variables:

$lint_minbitsize: (number, default 16)

channels: Tests file is stereo.
data: Tests if file is a valid WAV file, and if it is an mp3 hiding in a wav file or is some other sort of non-pcm audio.

WRITING TOOLS

To add a new tool to mp3lint, create a module under the namespace MP3::Archive::Lint::Tools::. This should inherit from MP3::Archive::Lint::Tool. You will need to implement the following methods:

new: Your constructor will get passed a reference to a MP3::Archive::Lint::Conf object. You should pass this to the base class constructor with something like:
"my $self=$class->SUPER::new($config) bless($self,$class);"
initscan: "initscan" is called once per file being tested. You should do any per-file initialisation here.

The following methods and variables will be useful:

$self->settests("test1", "test2"): In either "initscan" or "new", you should call "settests" to set the list of tests to run. "settests" expects an array of test names (as strings). After "initscan" has been called, those tests are called in order. Tests are simply methods in your tool.
$self->{file}: The full path and filename of the current file/dir.
$self->{path}: The canonicalised path component of the current file, minus the filename.
$self->{filename}: The filename of the current file, minus the path.
$self->{qfile}: $self->{file}, but quoted with single quotes so it can safely be passed through the shell.
$self->{skipnametests}: Flag, whether to skip filename-related tests or not.
$self->{isalbum}, $self->{istrack}: Flags, whether to treat the current file an an album track. (Both zero=unknown).
$self->config(): Returns the current "MP3::Archive::Lint::Conf" object. Useful config methods:

$self->config->get($varname): Returns the value of the configuration variable $varname or undef if not found.
$self->config->skipnametests(): Returns a boolean whether to skip filename-related tests or not.

$self->archive(): Returns the current MP3::Archive(3) object.

The best plan is probably to start with an existing tool and work from there. Wav.pm is probably a good starting point, as it is simple and fairly representative.

BUGS

See sections for individual tools, above.

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

AUTHOR

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

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.