Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
docs::mp3lint-tools(3)User Contributed Perl Documentatiodocs::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
       A

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.

perl v5.24.1			  2017-07-02		docs::mp3lint-tools(3)

NAME | DESCRIPTION | TOOLS | au - Tool to check .au files | dir - Tool to check directories | filename - Tool to check filenames | filesys - Tool for misc filesys tests | flac - Tool to check .flac files | id3 - Tool to check id3 tags | m3u - Tool to check .m3u playlists | mp3check - Tool to check mp3 files using mp3_check (or checkmp3) | mp3info - Tool to check mp3 files using mp3info | ogg - Tool to check .ogg files | wav - Tool to check .wav files | WRITING TOOLS | BUGS | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mp3lint-tools&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help