GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
docs::mp3lint-tools(3) User Contributed Perl Documentation docs::mp3lint-tools(3)

mp3lint-tools - tools and tests available in mp3lint

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

 

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

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.

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

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.

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.

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).

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

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.

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.

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.

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.

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/

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.

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.

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

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.

Currently doesn't do anything with EXTINF comments.

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.

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)

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"

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)

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.

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.

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

Checks wav files by parsing the RIFF header.

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.

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.

See sections for individual tools, above.

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

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)

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

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.

2022-04-08 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.