NAME

mms-tag2filename - generate MP3 filenames from ID3 tag

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-tag2filename [ -c, --case NUMBER ] [ --pattern STRING ] [ -r, --recurse ] [ -s, --simulate ] [ -v, --verbose STRING ] [ -w, --weed ] { FILE | DIRECTORY } ...

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

mms-tag2filename -V, --version

DESCRIPTION

mms-tag2filename 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.

For each file it will generate a file name based upon the information within the file's ID3 tag. It will only rename the file if all the necessary information can be gathered, otherwise it will report an error message and leave the file unchanged.

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 possible options and exits.

--man

Prints the whole manual and exits.

-c, --case NUMBER

Sets the case conversion mode affecting the generated filename (default: no changes). NUMBER can be:

  0     all characters in lower case
  1     Capitalize the first character, the rest will be lower case
  2     Capitalize The First Character Of Each Word, Even_This-Way

--pattern STRING

Sets a custom pattern for the desired filename without file extension; .mp3 will be appended by this program. You can define any filename format by using placeholders like ((TITLE)). Using quotes around your pattern is stongly recommended in order to prevent shell interpretation of special characters. Default is ((ARTIST)) - ((TITLE)). Possible placeholder names are:

  TITLE
  ARTIST
  ALBUM
  YEAR
  COMMENT
  TRACKNUM
  GENRE

-r, --recurse

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

-s, --simulate

Read-only mode, no changes will be made. Helps finding missing ID3 tags and similar problems. This mode is a bit more verbose than the `real' mode because in a simulation you will probably want to see what would happen. More precicely, operations that would change a file will be reported as INFO while simulating, but in `real' mode you will have to switch to MORE to get such an operation reported.

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

-w, --weed

Enables the removal of some special characters that may be used within tag fields but cannot or should not occur in filenames. The --weed switch can be given multiple times; the more switches the more will be weeded. The replacement character is the underscore.

Some basic weeding is always done for the following forbidden characters: \ / : * ? `` < > |

One or more --weed switches will replace spaces with underscores. If there are two or more spaces in a row these will be converted to a single space first.

Two or more --weed switches result in the additional replacement of the following characters: ( ) [ ] ! $ % & =

Three or more --weed switches will also replace these characters: . , ; + ~ # ^

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