NAME

mms-settag - set or erase the ID3 tag 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-settag [ --listgenres [STRING] ] | [ --purify [v1|v2|all] ] [ -r, --recurse ] [ -s, --simulate ] [ --settitle STRING ] [ --setartist STRING ] [ --setalbum STRING ] [ --setyear NUMBER ] [ --setcomment STRING ] [ --settracknum NUMBER ] [ --setgenre STRING|NUMBER ] [ -v, --verbose STRING ] { FILE | DIRECTORY } ...

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

mms-settag -V, --version

DESCRIPTION

mms-settag 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 set the ID3 tag according to the options given. Typically you will give an option like --setalbum 'The Number of the Beast' which will result in setting the ALBUM field of all files' tags to this string.

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.

--listgenres [STRING]

Prints all available genres and their index number and then exits. This option can be used to find a value for the --setgenre option. If you give a STRING as value it will be used as search pattern, i.e. you will see genres that match or contain your search string. The search is case-insensitive.

--purify [v1|v2|all]

Enables a program mode that clears all ID3 tag fields before writing any given values into it. Without using this option, affected tag entries are overwritten with their new value and the other entries remain unchanged.

As a special case you can use this option to completely remove ID3 tags from your files. This happens if you don't give any --set... option.

By passing one of the optional values you can specify which tags should be removed:

v1: DEFAULT: Only ID3v1 tags will be erased.
v2: ID3v2 tags will be removed; this is useful if you want to clean your collection from those tags.
all: Both types of tags will be erased.

-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 out which files will be affected. 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.

--set...

The options in this section let you define which tag fields should be set. They share some common behaviour: If you don't set one of these options the corresponding tag field will not be changed. If you use an option with the empty string as value (``'') the corresponding tag field will be cleared.

In order to clear all fields before writing data into the tag or even remove a tag completely consider using the --purify option.

--settitle STRING(30): Sets all files' TITLE field to STRING. If it exceeds the maximum length of 30 characters it will be truncated.
--setartist STRING(30): Sets all files' ARTIST field to STRING. If it exceeds the maximum length of 30 characters it will be truncated.
--setalbum STRING(30): Sets all files' ALBUM field to STRING. If it exceeds the maximum length of 30 characters it will be truncated.
--setyear NUMBER: Sets all files' YEAR field to NUMBER. This must be a 4-digit number; otherwise an error will be raised.
--setcomment STRING(30): Sets all files' COMMENT field to STRING. If it exceeds the maximum length of 30 characters it will be truncated. If the TRACKNUM field is already set or will be set by execution of this program, then only 28 characters are available.
--settracknum NUMBER: Sets all files' TRACKNUM field to NUMBER. If NUMBER is not between 1 and 255 an error will be raised.
--setgenre STRING|NUMBER: Sets all files' GENRE field to STRING which must be a valid genre title or genre index NUMBER; otherwise an error will be raised. Using a NUMBER is recommended because of brevity. You can find out all available genres with their index number by using the --listgenres option.

-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