
         **********************************
         *  Users Guide for EasyTAG 0.12  *
         **********************************

Last update: 11/26/2000
Copyright (C) 2000 Jérôme Couderc <j.couderc@ifrance.com>


             *************************
             *       Summary         *
             *************************

1. Introduction

2. EasyTAG Window
   2.1. Browser Frame
   2.2. File Frame
   2.3. ID3 Tag Frame
   2.4. Commands Frame

3. Options Window
   3.1. Common
   3.2. User Interface
   3.3. Misc
   3.4. Scanner
   3.5. Confirmation

4. Scanner Window
   4.1. Fill Tag
   4.2. Rename File
   4.3. Process Fields
   4.4. Mask Editor Frame

5. Miscellaneous Functions
   5.1. Run Xmms



             *************************
             *         Guide         *
             *************************

1. Introduction:
================

   EasyTAG is a little utility for editing and viewing tags of yours mp3 
files. A lot of functions were implemented to make easier the handling 
of tags, but the other ojective was also to keep it easy to use. The 
graphical user interface was based on GTK+ (Gimp Tool Kit) and give you 
all the needed informations about the mp3 file(s).


2. EasyTAG Window:
==================

   The main window had been divided into four functional parts

  +------------------------------------------------------------+
  | EasyTAG Window                                             |
  +---------------------+-------------------------+------------+
  |                     |                         |            |
  |                     |       File Frame        |            |
  |                     |                         |            |
  |                     +-------------------------+            |
  |      Browser        |                         |  Commands  |
  |       Frame         |                         |   Frame    |
  |                     |                         |            |
  |                     |      ID3 Tag Frame      |            |
  |                     |                         |            |
  |                     |                         |            |
  |                     |                         |            |
  +---------------------+-------------------------+------------+


   2.1) Browser Frame:
   -------------------

    2.1.1) Path entry:

      On the top of the frame, an entry allow you to type a path to 
browse, or copy&paste the selected path to fill manually the tag. When 
you have typed a path, press the enter key to load it.
  This entry is also updated when selecting next/previous file to show 
the path of the current displayed file (if 'browse sub-directory' mode 
is enabled).

     2.1.2) Tree Browser:

       Below the path entry is located the tree browser strictly 
speaking. The 'tree' of directories is an easy way to select the 
directory where are located yours mp3s to tag. Just select the directory 
to browse with your mouse. With this version of EasyTAG you can select 
only one directory at once, but you have the ability to browse also the 
sub-directories.
   When browsing a directory recursively (include sub-directories) a 
window, containing a stop button, appears over the browser. Click this 
button to stop the search. 
   The menu 'Browser' into the main menu bar is dedicated to it. You can
also open a popup menu when clicking the right mouse button on the tree 
browser.
   If the directory structure have changed (directories renamed, moved, 
deleted,...), you can update it when selecting the menu entry 'Refresh 
Tree'.

   2.2) File Frame:
   ----------------

     On the left top corner, is shown the position of the current file 
into the mp3 list and the length of this list. Next, an entry display 
the name of file. You can modify the file name manually or by using the 
scanner (see below). You can open a popup menu by right clicking over 
the entry with the mouse. And then, a block show informations about the 
mp3 file (MPEG version, layer version, bitrate, frequency, mode, size 
and duration) and the list (values in brackets).
     

   2.3) ID3 Tag Frame:
   -------------------

     This frame contains seven entries to display all items of ID3 tags 
(support of ID3v1 and ID3v1.1 specifications). On the right of each 
entry is placed a square button, to apply the text of the entry to all 
tags of the list (for instance, put the same artist to all files).
  You can open a popup menu by right clicking over the entry with the 
mouse.

     Tag may be written following two specification:
       - ID3v1  : title + artist + album + year + genre + comment
       - ID3v1.1: title + artist + album + year + genre + comment + track

  +----------+--------------+-------------------------------+
  |          |              |      Max length or value      |
  |   Item   |    Format    +---------------+---------------+
  |          |              |     ID3v1     |    ID3v1.1    |
  +----------+--------------+---------------+---------------+
  |  Title   |   Alphanum.  | 30 characters | 30 characters |
  +----------+--------------+---------------+---------------+
  |  Artist  |   Alphanum.  | 30 characters | 30 characters |
  +----------+--------------+---------------+---------------+
  |  Album   |   Alphanum.  | 30 characters | 30 characters |
  +----------+--------------+---------------+---------------+
  |  Year    |   Numeric    |   4 digits    |   4 digits    |
  +----------+--------------+---------------+---------------+
  |  Track   |   Numeric    |   not used    |     255       |
  +----------+--------------+---------------+---------------+
  |  Genre   | Predef. Num. |       255 items in list       |
  +----------+--------------+---------------+---------------+
  |  Comment |   Alphanum.  | 30 characters | 28 characters |
  +----------+--------------+---------------+---------------+

        * To select genre : open the list attached to the entry and 
choose one item (total 148), or press the first letter of the genre name 
(press X times the same key if genre is the Xth one beginning with this 
letter. A beep is emited when there is no more possibility).

        * Auto completion of date: when date is partially completed and 
year entry loose focus. For instance, if you are in year 1995, and if 
you type 3 => 1993, if 6 => 1986, if 94 => 1994, if 96 => 1896, and so 
on.


   2.4) Commands Frame:
   --------------------

     The frame contains all main commands to handle files. 
On the top, the entry with two little arrows allow you to select 
directly whatever item of the mp3 list. Just select (with up/down/page_up
/page_down arrow keys) or type the number and press the enter key).
Into rows containing two "similar" buttons, the left button process only
the displayed file. And the right button (icon with a circular arrow) 
process all files of the list.

   - 1rst row : select whatever file
   - 2sd  row : select first, previous, next, last file
   - 3rd  row : the first click opens the scanner window, then the next 
                clicks run
   - 4th  row : delete tag of the mp3 file
   - 5th  row : undo last changes, undo all changes
   - 6th  row : save file, save all files
   - 7th  row : quit EasyTAG


3. Options Window:
==================

   3.1) Common:
   ------------


   3.2) User Interface:
   --------------------


   3.3) Misc:
   ----------


   3.4) Scanner:
   -------------


   3.5) Confirmation:
   ------------------


4. Scanner Window:
==================

   On the top of this window, an option menu permits you to select which 
scanner to use: "Fill Tag", "Rename File" and "Process Fields". On the 
right of this menu, there is four icons. The first one opens the scanner 
window, the second one opens/closes the mask editor window, the third 
one shows/hides a frame containing the legend of codes used into 
scanners. 
The last icon closes the scanner window.

Note that the scanner window must be opened to be able to use a scanner.
To open the scanner window, use the main menu (Misc -> Open Scanner 
Window), or press buttons to 'Scan File' into commands frame. The first 
time opens the window, then the other times run the selected scanner as 
long as the window is opened.

   4.1) "Fill Tag" Scanner:
   ------------------------

   The scanner uses the file path (filename + path to the file) to fill 
the fields of the tag. You can select two modes for scanning tag. 

 The mode 1 is an older scanner and I don't recommend you to use it (it 
was created to implement quickly a scanner into the first version of 
EasyTAG and isn't flexible). Moreover it'll probably disappear in future
 version, and will be replaced totally by the mode 2. 
   This last mode is very flexible an allow you to select/create a mask 
to apply to the file using several codes. Note that the mask and the 
file path are parsed from the right to the left to permit you to scan 
parents directories of the file (example: %c_-_%i/%a/%b/%n_%t.mp3).

   You can click the third icon to show a legend frame containing the 
following codes:
   - %t: title   => the corresponding string is moved to the title field
   - %a: artist  => the corresponding string is moved to the artist field
   - %b: album   => the corresponding string is moved to the album field
   - %y: year    => the corresponding numeric value is moved to the year
                    field
   - %g: genre   => the corresponding numeric value is converted into 
                    genre
   - %n: track   => the corresponding numeric value is moved to the 
                    track field
   - %c: comment => the corresponding string is moved to the comment 
                    field
   - %i: ignored => the corresponding string isn't assign to a field

   The mask to scan tag has the following particularities:
     - two codes must be separated by a separator
     - each code must be used only one time into mask
     - the separator '%' isn't allowed

   * Options:
        If you activate the options to convert underscore into space, or
     spaces into underscore (Option window -> Scanner Tab) then a mask
     like '%n - %t.mp3' is equal to '%n_-_%t.mp3'.


   4.2) "Rename File" Scanner:
   ---------------------------

   This scanner handles informations of tag (title, artist, album, yaer, 
genre, track, comment) to rename file using a mask with codes. Note that
 the mask and the file path are parsed from the right to the left.

   You can click the third icon to show a legend frame containing the 
following codes:
     - %t: title   => the code is replaced by the title field text
     - %a: artist  => the code is replaced by the artist field text
     - %b: album   => the code is replaced by the album field text
     - %y: year    => the code is replaced by the year field text
     - %g: genre   => the code is replaced by the genre field text
     - %n: track   => the code is replaced by the numeric value of track
                      field
     - %c: comment => the code is replaced by the comment field text
     - %i: ignored => the code has no effect

   The mask to scan tag has the following particularities:
     - two codes may be consecutive
     - each code may be used severals times
     - the separator '%' isn't allowed

   * Options:
        If you activate the options to convert underscore into space, or
     spaces into underscore (Option window -> Scanner Tab) then a mask 
     like '%n - %t.mp3' is equal to '%n_-_%t.mp3'.


   4.3) "Process Fields" Scanner:
   ------------------------------

   This scanner provides some tools/functions to process texts into tag 
entries and the filename entry. Into each group of options (groups are 
separated by a horizontal line), you can select at max one option (none 
selected allowed).

   The first group allows you to convert usual character underscore '_' 
and expression '%20' into space, or space into underscore.
   The second group permits you to change the case of characters.
   The third group provides some special options.


   4.4) Mask Editor Frame:
   -----------------------

   To show this frame, just press the "Show/Hide Mask Editor" button 
when using "Fill Tag" or "Rename File" scanners. When selecting another 
scanner (as "Process Fields") this frame is automatically hidden, and 
the button desactivated.
   When the editor is opened, the list of masks attached to the current 
scanner is loaded into a main list.
Use the toolbar, on the right, to create, duplicate, append (default 
masks), remove, order or save masks.

When saving the new list of masks, it cleans up the list by removing 
duplicated and blank masks, and memorize the order.
At the present time, the mask selected by default is the first one of 
the list.


5. Miscellaneous Functions:
===========================

   5.1) Run Xmms:
   --------------

   When you activate the menu item "Run Xmms", the following command 
will be executed : 'xmms -p <current_path>'. So, it'll create a new 
playlist with all MP3 files in the directory (and subdirectories) 
<current_path>.
And this directory is the one which is selected into the browser 
(see Browser Frame).



