
         **********************************
         *  Users Guide for EasyTAG 0.31  *
         **********************************

Last update: 06/30/2004
Copyright (C) 2000-2004 Jrme Couderc <j.couderc@ifrance.com>


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

1. Introduction

2. EasyTAG Window
   2.1. Browser Frame
   2.2. File Area
   2.3. Information Area
   2.4. ID3 Tag Frame
   2.5. Buttons

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 Audio Player



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

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

   EasyTAG is a little utility for editing and viewing tags of your
mp3 files. A lot of functions have been implemented to make the
handling of tags easier, but another ojective was also to keep it easy
to use.
   EasyTAG doesn't change your files until you tell it to. It keeps a
record of the changes you want to make, lets you review them and then
writes the changes when you tell it to.
   The graphical user interface was based on GTK+ (Gimp Tool Kit)
and gives you most of the information you need about the file(s).
   Were supported MP3, MP2 files (ID3 tag), FLAC files (FLAC Vorbis 
tag), Ogg Vorbis files (Ogg Vorbis tag), and MusePack, Monkey's Audio 
files (APE tag).




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

   EasyTAG has two main 'views', you can change the way the main
window looks by clicking on the 'show tree browser / display by artist
album' button. This the tree browser layout:

  +------------------------------------------------------------+
  | EasyTAG Window                                             |
  +---------------------+----------------------+---------------+
  | Path Area                                  |               |
  +---------------------+----------------------+               |
  |                     |                      |               |
  |                     |                      |  Information  |
  |                     |                      |     Area      |
  |                     |                      |               |
  |      Browser        |      File Area       +---------------+
  |       Area          |                      |               |
  |                     |                      |   ID3 Tag     |
  |                     |                      |  Information  |
  |                     |                      |               |
  |                     |                      |               |
  |                     |                      |               |
  +---------------------+----------------------+---------------+

   this is the artist/album layout:

  +------------------------------------------------------------+
  | EasyTAG Window                                             |
  +---------------------+----------------------+---------------+
  | Path Area                                  |               |
  +---------------------+----------------------+               |
  |      Artist Area    |                      |               |
  |                     |                      |  Information  |
  | 3 columns showing:  |                      |     Area      |
  |Artist #Album #Files |                      |               |
  |                     |      File Area       +---------------+
  +---------------------+                      |               |
  |   Album Area        |                      |   ID3 Tag     |
  |                     |                      |  Information  |
  | 2 columns showing:  |                      |               |
  |Album       # Files  |                      |               |
  |                     |                      |               |
  +---------------------+----------------------+---------------+



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

    2.1.1) Path entry:

      On the top of the window, an entry area allows you to enter a
new path to browse or select select an old one from a drop-down list.
This text box is also updated when selecting next/previous file to
show the path of the current displayed file (especially useful if
'browse sub-directory' mode is enabled).

    2.1.2) Browser Area:

      The 'tree' of directories is an easy way to select the directory
where your files are located. Just select the directory to browse with
your mouse. You can select only one directory at once, but you have
the ability to browse also the sub-directories. (see preferences)
      When browsing a directory recursively (ie including
sub-directories) it can take a while to search for all the files so a
window containing a stop button appears over the browser. Click this
button to stop the search.
      The 'Browser' menu in the main menu bar always acts on this
area. You can also open a popup menu by clicking the right mouse
button on the tree browser.
      If the directory structure have changed (directories renamed,
moved, deleted,...), you can update it by selecting the menu entry
'Refresh Tree'.

      If you change the directory you're looking at, EasyTAG will ask
you if you want to save any changes you've made to the tags.


   2.2) File Area:
   ---------------

    This area shows the files that Easytag has found.

    Files are shown in red if EasyTAG has changed the tag information
but not yet saved it. The background colour is alternated for each
album so you can see what album a file belongs to.

    There is a menu that appears when you click the right mouse button.
it lets you:
    * select/deselect all the files or invert the selection
    * start a music player (if you don't remember a track too well!)
    * change the order the files are shown in
    * start the scanner (see later)
    * search the tags or filenames
    * delete files
    * refresh/reload the files
    * run another program against the selected files
    * change the sort order, including by tag

    Each action (deleting, undoing, setting a field, ...) will be applied
only to the selected files. It is the case when using the scanner for
example.

    When typing the first character of a file, it will try to find it 
and select him.


   2.3) Information Area:
   ----------------------

    At the top left corner, is shown the position of the current file 
in the list of tracks and the length of this list. Next to it is a text 
box with the name of the file so  you can  modify the file name manually.
Also, by right clicking over this box, you can open a popup menu that lets
you:
    * use the scanner (see below)
    * perform some text 'fixes' (like changing spaces to underscores)

    Finally a block shows informations about the file (eg MPEG version,
layer version, bitrate, frequency, mode, size and duration) and the
list (values in brackets are for all files in the file area).


   2.4) ID3 Tag Frame:
   -------------------

    This frame contains eight entry areas to display the common ID3
tags (support of ID3v1, ID3v1.1 and ID3v2 specifications). To the
right of each field is a square button which sets that field for all
selected files on the file area (for instance, put the same artist to
all files).
    You can open a popup menu by right clicking over the entry with 
the mouse - this also lets you perform some text 'fixes' (like changing
spaces to underscores)

    Tags are written according to the preferences setting

        * To select genre : open the list attached to the entry and 
choose one item (total 148), or start to type the genre name - you can
then use the up/down arrows to pick an entry.

        * 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. (Nb. Preference setting)


   2.5) Buttons:
   -------------

    The buttons provide shortcuts to some functions :
Arrows: select first, previous, next, last file
Green button : the first click opens the scanner window, then the next clicks run
Paintbrush   : delete all tags from the file
Curly arrows : undo last changes, undo all changes
Floppy disk  : save tag changes
Head         : toggle beteen browser and artist/album view
Full list    : select all files
partial list : invert selection
Round cross  : stop activity
Door         : 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 five icons. The first one opens the scanner 
window, the second one opens the preference tab for the scanner, the third
one opens/closes the mask editor window, the fourth 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 'Scanner' in the menu bar. 
Also press buttons to 'Scan File' in the toolbar. 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 scanner 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).
If the tag was already filled, nothing will happen, except if you activate 
the option 'Overwrite fields when scanning tag' in the scanner tab of the
preferences window.

   You can click the fourth 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.

   If the tag was already filled, nothing will happen, except if you activate 
the option 'Overwrite fields when scanning tag' in the scanner tab of the
preferences window.

   You can click the fourth 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 Audio Player:
   ---------------------

   When you activate the menu item "Run Audio Player", the following command 
will be executed : 'xmms -p <current_selected_files>', to load the selected
files into XMMS. In the preferences windows, an entry allows you to use an 
other player.
   If you want to enqueue only the selected files to the current playlist of
XMMS, you can use the popup menu entry 'Open file(s) with...' and type the 
command 'xmms -e'. You can also do it over a directory to load all he files
of this directory.
