NAME

mms-filename2tag - generate ID3 tags from MP3 filenames

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

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

mms-filename2tag -V, --version

DESCRIPTION

mms-filename2tag 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 extract information for its ID3 tag based upon the filename. Normally you will therefore specify a file name pattern that a file must match in order to be processed. The ID3 tag will be modified only if all the necessary information can be gathered, otherwise this program 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 conversion mode affecting the case of tag field values that will be set using --pattern and/or --tracklist (default: no change). 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 expected filename format without file extension; .mp3 will be appended by this program. Only those files that match the given pattern will be processed; you will be warned about .mp3 files that did not match the pattern.

You can define the filename format by using placeholders like ((TITLE)). Using quotes around your pattern is stongly recommended in order to prevent shell interpretation of special characters. Possible placeholder names are:

  TITLE
  ARTIST
  ALBUM
  YEAR
  COMMENT
  TRACKNUM
  GENRE

Moreover, you may use IGNORE for parts of the filename that should not be written into a tag field, e.g. ((ARTIST)) - ((IGNORE)) - ((TITLE)).

The default pattern is ((IGNORE)) so that obmitting this parameter does no harm. However, a pattern should always be set unless you do not want to set the tag according to information contained in the filename. This may be desirable if you only want to set titles using the --tracklist feature.

--purify

Enables a program mode that erases all ID3 tag entries before writing the values that were extracted from the filename. Of course, this affects only those files that match the --pattern. Without using this option, affected tag entries are overwritten with their new value and the other entries remain unchanged.

-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 files that do not match the --pattern 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.

-t, --tracklist FILE

Defines a tracklist file that contains track titles. This will usually be the tracklist of an album. Each line contains the title of one track; its position (the line number) corresponds to the track number this title belongs to. Empty lines and lines starting with a hash (#) will be skipped. Of course, in order to find the corresponding file it is necessary that the file's TRACKNUM tag field is set.

It is possible to combine this feature with the --pattern option, but be aware that any ((TITLE)) placeholders of your pattern will be overridden with the title from the given tracklist.

When defining the tracklist file's location it is important to notice the difference between processing directories and processing single files that are explicitly specified on the command line. In the following, these two scenarios will be explained.

Directories: Processing of directories is done recursively. It can be assumed that the tracklist is meant to be different for each of these directories. Therefore a tracklist file named FILE is searched for within the currently processed directory. If FILE contains any path information it will simply be stripped off. Only the filename itself is considered.
Files: All files that are explicitly specified on the command line will have their titles set according to the given tracklist file. In this case, if FILE contains any path information, no matter if absolute or relative, it will be used to localize the tracklist file.

You may combine these scenarios by specifying both directories and filenames to be processed, but you should be aware of the differences. You will probably agree that this will almost never make sense. Instead, the --tracklist feature is typically used with either directories only or files only.

-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 [STRING]

Replaces certain characters with spaces when writing filename fragments to tag fields. The STRING argument is a regular expression; matching characters will be weeded. If STRING is omitted an underscore (_) will be used as default.

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