MP3T - The MP3 Tag command line editor README
---------------------------------------------

0. Copyright

MP3T was written in 2000 by Martin Pitt (piware@piware.de). It
contains part of the source code of "KMP3TE", the KDE MP3 Tag editor,
written by Antoine Laydier.

This program is free software. You can use, distribute and modify it
under the terms and conditions of the "GNU General Public License"
(see file COPYING).

1. What is it?

mp3t is a command line based information tag editor/viewer for ISO
MPEG1, layer 3 audio streams, commonly known as MP3 files. I know
several graphical programs for editing and displaying the information
tag (which contains the song title, the artist name, album title,
year, genre and a comment), e. g. XMMS or KMP3TE. But these programs
fail if you want to do shell script processing, e. g. automated design
of your MP3 CD covers or (the other way round), equipping MP3s with
information from, for example, a CDDB database. These applications are
mp3t's main purpose.

2. Features

* Printing MP3 information tags in any format
* Change some or all tag fields noninteractively with command line
  parameters
* Set the tag fields interactively (keyboard input)
* Delete the info tag

3. Installation guide

If you got the source code, you have to compile the program first. It
doesn't come along with sophisticated configure scripts and the like
since it just uses the C standard library. I provided a Makefile for a
Unix system; it should also work with DJGPP (gcc DOS port).

Edit the Makefile first to change compilation parameters: you should
set up the variable PREFIX (maybe change it to /usr/local) and
LOCALEDIR (directory where gettext localisations are stored; this is
/usr/share/locale in Debian).

To compile, you need g++ and make. Just typing "make" will produce a
single executable "mp3t". "make install" will copy the binary, the
manpage and translations to the appropriate directories. "make
uninstall" will delete all copied files if you do not want to use mp3t
any more.

4. How to use

The general format for invoking mp3t is:

    mp3t [option] [option ...] mp3file [mp3file ...]

Both the mode of operation (print, set, input, or delete) and the
parameters for them are supplied with several options. Please execute
mp3t without parameters or with the option "-h" or "--help" to get a
description of all options. After the options you give a list of
all files you want to process.

Just a word about the special treatment of the "Genre" field in the
tag: These genres were predefined by the MPEG group and are stored as
a number (0 to (currently) 145). You can provide the genre either as a
number or as text. This works both with the command line parameter -g
(respective --genre) and in the interactive input mode. Call 
"mp3t --genres" to get a list of all available genres and their
assigned numbers.

5. Bugs / Todo

The input (interactive) mode is currently very uncomfortable. It just
uses simple system functions for string reading, which do not allow
range control, which means that you can type in more characters than
possible. The title, album, artist and comment fields are limited to
30 characters, the year field is just 4 characters long.

If you need to enter data interactively there are much more
sophisticated programs around. This is not mp3t's main purpose. But
nevertheless I'll try to improve this.

6. Contacting the author

If you have any suggestions, improvements, or found a bug in mp3t,
please feel free to contact me by eMail: piware@piware.de.
