NAME

mms-detagtor - show and search ID3 tag info of MP3 files

SYNOPSIS

How to get help: If one of the --help options is specified once a short overview will be printed; if specified twice you will get detailed information about command line options. --man gives you the whole manual.

mms-detagtor [ --find KEY=VALUE ] [ -l, --long ] [ -r, --recurse ] [ -v, --verbose STRING ] { FILE | DIRECTORY } ...

mms-detagtor -?, -h, --help | --man

mms-detagtor -V, --version

DESCRIPTION

mms-detagtor is part of the `mp3ManagementSuite' which is a collection of programs that help maintaining music collections.

You can decide which .mp3 files will be processed by passing names of files or directories. At least one file or directory is expected.

By default the versions of ID3 tags found within each file will be reported. With the --long option specified once or twice the contents of the tag fields will be shown. But the real strength of this program is its --filter option which enables you to find files that match some criteria, e.g. you could search for all files which have an entry in their `artist' field that matches your search pattern or you could search for files that have an ID3 tag version2 but no ID3 tag version1 and so on.

Please read the section ID3 TAG VERSIONS for general information about tags as well as some explanations how different tag versions are handled by this program.

OPTIONS

This paragraph describes the possible options that can be used to modify this program's behaviour. If a long option name requires an argument then the short form does so, too. Long names can be abbreviated but must stay unique. Short options can be bundled even if they have arguments; thus `-a12b34c' is equivalent to `-a 12 -b 34 -c'. To avoid ambiguity you can use ` -- ' to seperate the options from the list of directories and files.

-?, -h, --help

Prints the SYNOPSIS section of this manual and exits. If this option is passed twice the OPTIONS section will be printed, too.

--man

Prints the whole manual and exits.

-l, --long

If specified once: prints a one-line tag summary output. If specified twice: prints detailed tag information, one line per tag field.

--find KEY=VALUE

Filters those files that match the specified criteria. If this option is used multiple times a file must match all of the given criteria.

Both KEY and VALUE are case-insensitive. Valid KEYs will be explained below. It is recommended to enclose VALUE in quotes that protect your filter from shell expansion (see examples at the end of this section).

There are two types of filters, one for detecting tag versions and one for filtering by tag field contents:

You can find MP3 files with or without ID3 tag version 1 or 2 by using v1 or v2 as KEY and either true or false as VALUE. For example, --find v1=true --find v2=false will reveal all files that have a v1 tag and no v2 tag.

You can filter files based on the contents of their tag fields. Note that this type of --find works on v1 tags only and therefore implicates --find v1=true.

Possible field names to be used as KEY are:

  TITLE
  ARTIST
  ALBUM
  YEAR
  COMMENT
  TRACKNUM
  GENRE

The string you specify as VALUE will be interpreted as a regular expression. To avoid this start it with \Q and all meta characters will loose their special meaning.

Examples: Find songs by John Doe or John Foo, the `h' in their first name being optional: --find ARTIST='Joh?n (Doe|Foo)'. Find the song named So What? and do not treat the string as a regular expression, saving the question mark from being a meta character: --find title='\QSo What?'.

-r, --recurse

Enables recursive processing of subdirectories for each of the given directory arguments.

-v, --verbose STRING

Adjusts the level of output verbosity. There are five categories, ordered by severity. This setting means that all messages up to the given severity level will be reported; less severe messages will be suppressed.

STRING defaults to INFO which means that all messages from the categories FATAL, ERROR, WARN and INFO will be reported. Possible values for STRING are:

  FATAL
  ERROR
  WARN
  INFO
  MORE

-V, --version

Prints the program version and exits.

ID3 TAG VERSIONS

The so-called tag is a small optional part of an MPEG Layer 3 file that contains information about the audio part, e.g. the artist's name, a comment etc.

There are two major versions of MP3 tag formats, ID3v1 and ID3v2. All programs of the `mp3ManagementSuite' are focused on the ID3v1 tag (or ID3v1.1 if the TRACKNUM field is used). In most cases the presence of an ID3v2 tag will be simply ignored.

More specifically, it will never be read from or written to a version2 tag. There are only two actions that involve version2 tags: You can use mms-detagtor to find files depending on their tag version and you can use mms-settag to erase version2 tags.

This behaviour is due to the author's opinion that ID3v2 is totally superfluous. Most people are not even able to maintain the v1-tags of their music archive (except if they use tools like this ;)). Moreover, in comparison to v1-tags that are appended to the file, v2-tags are prepended and this means that the whole file must be rewritten every time a v2-tag is changed. Contrary opinions are respected but there are other tools for those people's requirements.

COPYRIGHT AND LICENCE

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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA