README-File for MP3ext V2.1b   (21.10.1997)

What's it for?
--------------
MP3Ext is an extension for the Explorer. It adds a new page to the
properties-menu of MP3-files. It shows all info about the mp3-file, e.g.
the playlength, bitrate, sample-frequency, and the ID3-Tag if the file
has got one. You can even edit the ID3-Tag, and scan whole directories.


Installation
------------
Quite simple: Extract all the files of the zip archive in a temporary folder
(which you probably have already done; otherwise you can't read this file),
then right click on the file MP3ext.inf and choose "Install".
There is no need to configure the language; it is chosen automatically,
depending on the language of the operating system.
finished!

Update: If you want to update the program, there is no need to do an uninstall
of the previous version. Simply install the new version; the old entries will
be replaced!

If there is a request for a disk, or something like that, then the directory
from which you install contains long filenames. Just copy the files to a
directory with short names (e.g. C:\TEMP\) and do the installation from there.
After installation, you can delete the files from the Temp-Directory.

IMHO:
I kept the file as small as possible. I think the result is quite good:
A 28k DLL. (v 1.0 was even 10k!). And this includes 6 different languages!
(1 language uses ~1k). I didn't used these big installer, which make the
distribution grow by 400k, so there is this small .inf-file. And there are no
unnecessary files included (msvcrt.dll is a standard lib).

So to all you programmers out there: It is possible to write small windows
applications! QED.


Usage
-----
The upper fields are general MP3-information which is read-only.
The lower part is the ID3-Tag, which can be changed. The strings are limited
due to the specification to a maximum of 30 characters. Except the year, which
is 4 chars long. Input is rejected, if you want to type more.
The UNDO-Button restores the information, that means it rereads the file. The
Cln-Button below the UNDO-Button removes the ID3 Tag. This is done immediately!
The Scan-Button is described below.

Multiple files:
Since V2.1 multiple files are supported. Therefore there are some things, which
need to be explained: You are given the total time, and the avarage time of
all MP3 files. The number of read files is given too (including the number of
files which actually have an ID3-Tag). If the MP3-files have different
properties, i.e. you have selected a file with a bitrate of 128000
and 56000 the bitrate field displays "128k, 56k". The same applies to the other
fields too (Mode, Layer, Freq, Version). Since this multi-info-feature uses
much space I am using abbreviations, such as 128k for 128000 or 44k1 instead
of 44100. For the mode field the abbreviations are the following:
JS=Joint-Stereo, S=Stereo, DC=Dual-Channel, SC=Single-Channel

Editing multiple files:
The first file, which is being scanned is displayed. In fact it's the file
which is the selected one (the one you right-clicked on).
On the left side of the edit-fields you have a check-mark. If this is checked,
the associated edit field gets enabled, and you can change it, or use the
drop-down list, which contains the strings of all scanned files which have
a valid string in this field.
The only exception is the genre, which has a predefinied list.
If you are saving, only the fields which are checked will be replaced in the
file's ID3-Tag. This way you can for example change the comment for a bunch of
files without changing their title.

Keep in mind that the files in subdirectories are scanned on every action.
The only action which is a seperate thread is the reading of the files. If
you write the ID3-Tag you have to wait until it is finished, then they are
all read again!
Since you can scan directories, I moved the scanning to a seperate thread.
You can see if the scanning is in progress, if there is a "s" in the "# Files"
field.

Scan-button:
This function scans the filename of the files, and tries to figure out the
title and the artist. If they are found the file is checked, for an ID3-Tag,
and if the corresponding field is empty, they are filled in, and the ID3-Tag
will be saved.
Now, how is the file analyzed?
1) all underscores ('_') are replaced by spaces (' ').
2) The filename is scanned for the following syntax (this order)
             a)  (artist)[-]title.mp3
             b)  artist-title.mp3  or artist.title.mp3
             c)  title.mp3
3) The found strings are all capitalized, i.e. the first letter is converted
   to uppercase. Then they are copied to the ID3-Tag if it's empty.

Annotations to the format:
- For format a, you can use any bracket you want i.e. {,[ or ( and ),],}
  respective. The dash after the closing bracket is optional.
  Blanks around the dash will be removed. 
- For format b, there must be exactly one dash in the file.
  Blanks around the dash will be removed. If the dash isn't found
  it is checked for a dot. and then for an ASCII-char 250.
- If a and b fail, the complete filename (without the extension) is used as
  the title. (Format c)

Here some examples:
filename: "pink floyd - time.mp3"    --> artist="Pink floyd", title="Time"
filename: "[ACDC]-For_those_about_to_rock_(we_salute_you).mp3"
      --> artist="ACDC", title="For those about to rock (we sa"
(title gets cut because only 30 chars are allowed!!!) 
filename: "(acdc) - Hells-Bells.mp3" --> artist="Acdc", title="Hells-Bells"
filename: "testing.mp3"              --> artist="", title="Testing"


Other languages
---------------
Since Version 2.0 MP3ext supports multiple languages. If you want to know,
which languages are currently supported, take a look at the properties of
this DLL, then choose the version-page, and select the "languages". You'll
now see, which languages are supported by this DLL.
If you want to add further languages, feel free, to contact me.
(email only). Then I'll send you the part which needs to be translated.

Current Languages:
German   - myself
English  - myself
French   - Gilles Reichert      mailto:snark@ping.be,
                                WWW: http://www.ping.be/snark
Swedish  - Fredrik Andersson    mailto:kryo@geocities.com
Finnish  - Pasi Ruhanen         mailto:pasiru@dlc.fi
Spanish  - Marcelo Montenegro   mailto:floyd@elbbs.com.ar
Dutch    - Maarten van der Meer mailto:Webmaster@maarten.demon.nl
Polish   - Adam Lesie          mailto:ditalesi@pbg.pl
                                WWW:http://friko.onet.pl/ld/adlee
Italian  - Carlo Di Bennardo    mailto:c.dibennardo@na.flashnet.it


Registration
------------
It's freeware, so no fee is necessary. But any donations are welcome :-).


Contact
-------
If you have any further questions, here is my adress:
email: amiga2@info2.rus.uni-stuttgart.de
snail-mail:
Michael Mutschler
Somborer Weg 11
71067 Sindelfingen
Germany

The latest version will always be available at:
http://tick.informatik.uni-stuttgart.de/~mutschml/MP3ext/MP3ext.html


Bugs
----
"I don't see the page on my system?"
Since the inf-File installation doesn't provide the possibility to read
things from the registry, I had to add the handler to entrys which the
extension ".MP3" points to, on my own. At the moment the following keys get
registered: MP3_auto_file, winamp.file, winamp file, mp3file,
XAudio.MPEGAudioFile
These are all, which I currently know.

"All the Registry entries are OK, but there is still no page displayed"
Check out if you have msvcrt.dll in your windows\system (NT: winnt\system32)
Directory. If not, get it at: (133kb)
http://tick.informatik.uni-stuttgart.de/~mutschml/MP3ext/msvcrt.zip

Due to the limitations of the "miserable" specification of the ID3-Tag,
all the strings have a maximum of 30 characters; except the year, which
is 4 chars long. The genre is a predefined list, not extendable. So don't
ask me for further categories...
Perhaps one should define a better specification....

Now, this is the method to add other players:
1. Start RegEdit
2. Look for the Key "HKEY_CLASS_ROOT\.MP3". This key has a name. Remember it.
   e.g: it could be "MyMP3File"
3. Edit the file MP3ext.inf (just double-click it, to edit it with notepad)
4. go to the section [Strings] at the bottom of the file
5. Add another line for the new player with the name found in (2) :
   e.g: MP3Player88 = "MyMP3File"
6. got to the section [ThisDll.AddReg].
7. There you have to copy the two lines with "%MP3Player1%" in it, and append
   it below the other players. Now rename "%MP3Player1%" to the playerstring
   used in the section [Strings].
   e.g:
   HKCR,%MP3Player88%\ShellEx\PropertySheetHandlers\MP3Page,,,%MP3extClass%
8. save the inf-file, and just do a new installation. finished
9. Mail me about the new entry so I can add it to the next release of this
   program.

another method is to add the handler manually. The disadvantage is, it doesn't
get uninstalled when MP3ext is removed. You have to do that on your own too.
But I am working on it: you can use my dll to do that for *.MP3, *.MP2, *.MSF.
Be aware, this feature is experimental!

So if you want to register the filetype for another player, first do an uninstall,
then register the extension for the player, then do an install.

Installation:
get a DOS-Prompt where MP3ext.dll is found, then enter this command:
rundll32 mp3ext.dll,Install

Uninstall:
get a DOS-Prompt where MP3ext.dll is found, then enter this command:
rundll32 mp3ext.dll,UnInstall



History
-------
- = change   + = new feature    ! = Bug fix
V1.0   Initial release

V2.0  + The ID3-Tag is now editable
      + .MP3s get registered, if not registered before
      + Multilanguage support. Tough thing (I had to do more than I want,)
        but it finally works.
		+ added "clean" button

V2.1  + added multiple file support
      + new languages: french  (thanks to Gilles Reichert)
                       swedish (thanks to Fredrik Andersson)
                       finnish (thanks to Pasi Ruhanen)
                       spanish (thanke to Marcelo Montenegro)
      + added playerlink "winamp file" for the older version of winamp
      - Comboboxes (Drop down boxes) now use the extended-UI-Style:
        you can open the list with the arrow down key instead of pressing F4
      + Directory support.
      + Scan-Button
      - Input limits for the fields
      - The fields get cleaned before writing
      - when read, the strings get trimmed
      - Analyzation sets a default Genre ("Other") when creating an ID3-Tag
      - scanning for the sync in a MP3-file is better
      - improved support for MP2 (now *.MP2 & *.MSF files get scanned too
        when directories are read)
      + partial automatic registering of MP3-files (see section bugs)

V2.1a ! fixed bug when showing multiple files, and klicking OK, no more single
        MP3s were displayed furthermore
      ! better scanning for the sync in MP3s (no crash anymore)

V2.1b ! fixed spanish translation
      ! rewritten inf-file; should fix problems on Win95-Systems
      + scan now scans a template of "artist.title.mp3"
      + new translations: dutch   (thanks to Maarten van der Meer)
                          polish  (thanks to Adam Lesie)
                          italian (thanks to Carlo Di Bennardo)
      ! when doing the scan-function, all files would get an ID3-Tag.

