                    MP3TAG FAR Plugin module Version 1.02

Contents:

        1. About plugin.
        2. Installation.
        3. MP3 tags editing.
        4. Styles list.
        5. Adding MP3 tag info to description list file.
        6. Converting MP3 tag to track's filename and vice versa.
        7. Removing plugin.
        8. Comments.
        9. Copyright.


        1. About plugin.

Each MP3 file can contain an internal info about sound track recorded in it.
This info is called MP3 tag. It consists of track name, artist name, and
the like. This plugin allows you edit MP3 tags, add MP3 file information
to description list file and convert MP3 tag to track's filename and vice
versa.


        2. Installation.

1. Create folder MP3TAG in FAR plugin folder. For example: 
C:\Program Files\Far\Plugins\MP3TAG.
2. Copy all files from this archive to this folder.
3. Execute file MP3TAG.REG.
4. Restart FAR.
5. Check Options -> "Interface Settings" -> "History in dialog edit controls"
checkbox. This gives you more plugin functionality.


        3. MP3 tags editing.

Plugin works on selected files and, if there are no selected files, on the
current file. If two or more files are selected, they are edited in order 
their appearence in FAR panel.

Unobvious features:
- empty tags are skipped (tag with "Style" field only considered as empty)
- unmodified files are left highlighted;
- trailing spaces after track, artist, album and comment are removed;
- if any error occurs, editing is canceled;
- You can specify style by its name or its decimal code in the style field. 
In first case the style must be contained in the style base, but it mayn't
be in the style's edit history (because of FAR's history entry count 
restrictions);
- empty tags are filled by previous editable tag data (exclude track name) 
if checkbox "Fill dialog by previous tag data" is selected in plugin 
configuration dialog.


        4. Styles list.

Styles list is a set of Windows Registry values in the plugin key MP3TAG\Styles,
for example: HKEY_CURRENT_USER\Software\Far\Plugins\MP3TAG\Styles.
Each style is the name of the value with the type REG_SZ. Its value is style 
code.
If you want to add a style, you may edit Windows Registry manually or modify 
MP3TAG.REG file and execute it.

MP3TAG.REG contents example:
REGEDIT4
[HKEY_CURRENT_USER\Software\Far\Plugins\Mp3Tag\Styles]
"Hard Rock"="79"
"Rock & Roll"="78"
"Rave"="68"
"Jungle"="63"
"Punk"="43"
"House"="35"
"Classical"="32"
"Euro-Techno"="25"
"Soundtrack"="24"
"Industrial"="19"

When plugin starts, sixteen leading items of this list (such list)
are copied to the FAR's edit history key SavedDialogHistory\MP3_Style.
Unfortunately, there is no possibility to show a complete list of track 
styles in FAR's edit history list.
Note: styles included to the edit history list are the leading sixteen values 
names of described above MP3TAG.REG's MP3TAG\Style key. If you want to change 
this order, just delete MP3TAG\Styles Registry key, then edit MP3TAG.REG 
file and execute it.


        5. Adding MP3 tag info to description list file.

This feature only works on selected (highlighted) files. You must specify
description list file name, MP3's description template and template for
MP3 files without tag in order to build list.

Here is the list of available template macros (case insensitive):
%F Filename
%T Track
%A Artist
%B Album
%Y Year
%C Comment
%S Size
%% %

Example:
Filename: Files.Bbs
Template: %F %T: %A, "%B" (%C) [%Y]
No Tag:   %F (no description)

Created description list file Files.Bbs:
track01.mp3 Take On Me: A-ha, "The Hits Of A-ha" () []
track08.mp3 Hunting High And Low: A-ha, "The Hits Of A-ha" (remix) []
track09.mp3 (no description)
track10.mp3 (no description)
track12.mp3 Crying In The Rain: A-ha, "The Hits Of A-ha" () [198?]
track13.mp3 I Call Your Name: A-ha, "The Hits Of A-ha" () []
track16.mp3 The Sun Always Shines On TV: A-ha, "The Hits Of A-ha" () []

Unobvious features:
- selected but skipped files are left highlighted;
- if template contains a symbol after '%', both '%' and following symbol 
are skipped;                                
- only files with .mp3 extentions are allowed in this version.


        6. Converting MP3 tag to track's filename and vice versa.

Plugin works on selected files and, if there are no selected files, on the
current file. If two or more files are selected, they are edited in order 
their appearence in FAR panel. You must specify template and select the
direction of conversion.

Here is the list of available template macros (case insensitive):
%T Track
%A Artist
%B Album
%Y Year
%C Comment
%% %

Example: 
MP3 track Track01.mp3 has following MP3 tag:
Track   Aeroplane
Artist  Bjork
Album   Debut
Year    1993
Comment

Template: %T-%A-%B-%Y

Plugin will rename file Track01.mp3 to Aeroplane-Bjork-Debut-1993.mp3 if
you'll select "To Filename" button.
Backward conversion works in such manner. The only difference is you
should select "To Tag" button.

Note: During Filename -> MP3 tag conversion do not specify delimeters,
contained in tag fields. For example, if you've got "Come To Me Bjork.mp3"
filename and "%T %A" template, you'll get "Come" track-field and "To"
artist-field instead "Come To Me" and "Bjork".

Unobvious features:
- unmodified files are left highlighted. It means that renaming of file 
failed or there weren't MP3 tag fields extracted according the defined
template;
- if "Full template <-> filename match" checkbox is checked in plugin
configuration dialog, the filename must match whole template during 
Filename -> MP3 tag conversion. Otherwise, filename scanning stops after
first unmatch with template;
- if "Filename updates tag" checkbox is checked in plugin configuration
dialog, MP3 tag is replaced by newly composed tag. Otherwise it only
replaces fields extracted from filename;
- default MP3 style during Filename -> MP3 tag conversion is "unknown"
- the extension .mp3 is automatically added to filename during MP3 tag
-> Filename conversion and skipped during Filename -> MP3 tag conversion;


        7. Removing plugin.

1. Delete folder MP3TAG in FAR's plugin directory (because FAR opens
all dll's found in his plugin directory, you will be not able to do that 
while at least one copy of FAR is running).
2. Delete registry key HKEY_CURRENT_USER\Software\Far\Plugins\MP3TAG.


        8. Comments.

- plugin was tested under NT4SP4, FAR 1.61;
- style selection in edit history is based on undocumented FAR features;
- questions and bug reports are welcome at:
    2:5020/523.10@fidonet
    agord@usa.net;


        9. Copyright.

My thanks to coauthor (Alexey Kardashevsky, 2:5020/607.5, alexhome@aha.ru),
Dmitry Konyshev (2:5020/607.33, daekon@aha.ru). Special thanks to Peter
Valach (pvalach@altavista.net).

        MP3TAG FAR Plugin module Version 1.02, FREEWARE (C) 
                                               Alexander Gordeyev,
                                               2:5020/523.10,
                                               agord@usa.net
