docs::mp3lint-tools(3)

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

SEE ALSO
mp3lint(1), mp3lintskip(1), mp3lintsum(1), mp3lintrc(5), MP3::Archive(3), mp3-archive-tools(1)

perl(1), MP3::Tag(3), mp3info(1), mp3_check(1), checkmp3(1), ogginfo(1), flac(1), metaflac(1), md5sum(1), sort(1), diff(1)

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

COPYRIGHT
Copyright 2003 Ian Beckwith <ianb@nessie.mcc.ac.uk>

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.