Master File Usage


    ~/lib/Artists/Master



I)   Using the 'Master' filtering files
II)  Master File Format
III) Using sort.pl





I) Using the 'Master' filtering files

If you have not used Calliope before, and you have a lot of artists not listed in 
the Master file, you may in fact wish to run the loader, then edit the Master
file, and then flush and reload the database with 'calliope flushdb -rs'.

The 'Master' file (found in ~/lib/Artists/) is a listing of
corrected bands and artists to be used as a correctional filter
by the loader (Loader.pm) for Calliope.  The files are used to provide
a 'corrected' name for every artist, other common (mis-)spellings
of the artist or band name, and known variations, as well as to deal with
compilation albums.

Their are two goals.  The first is to eliminate filing redundancies 
caused by the many ways people type information into mp3 lookup databases, 
such as CDDB / Freedb (how many Elvises do you really need?).  The second 
is to allow the loader to associate an album and/or song with (potentially) 
many artists.  You may also want to see Rename.pm for more on multiple artists 
as they occur on compilation songs.

You can tell loader not to use these filtering files by setting "UseCorrections"
to 0 in the conf file.

You can edit this data as you see fit to help file your music the
way you want.  You can also just load your music into the DB and use
the web interface to edit your artists.  If you add artists to this
file (thus making it more robust), please submit the file back to me.
Note that when you run loader, it will automagically insert artists it *didn't* find
at the top of the Master file, preceded by a comment '#'.  Such entries
may be new artists, or variations on previously known artists.  The
listing is alphabetical for readility, but otherwise, order doesn't matter. 

Simply edit, merge or delete these new entries for them to be used by the next
pass of the loader.  

It's probably worth noting that there is inevitably a fair amount of subjectivity
in this file (as provided by me anyway).  Should "Cliff Bruner's Texas Wanderers" be the
name of a band, or should the songs be associated with both "Cliff Bruner" and 
"His Radio Cowboys"?  Well, you can edit the file and decide for yourself.

The Master file subsumes and expands on the separate functions formerly
found in the 'fileunder', 'corrections', and 'propernames' 
files from Otto's loader functionality.

It's worth noting that even in ID3-only mode (set in the conf file for the 
loader), calliope will attempt to use the file name (not the id3 tag) for the
song if it's in a Compilation directory (defined in the conf file).



II) 'Master' File Format 

Each line represents an artist, band, or grouping of artists/bands,
and contains the type of artist, the artist's name as it should be filed 
alphabetically, as it would appear in print, and variations on these that 
are found in CDDB / FREEDB.  The line can be divided into several distinct 
regions:

  1||        [2]                  |          3                 <=>            4  [|5...]

  b||Alley Boys of Abberville, The|The Alley Boys of Abberville<=>the alley bosy of abberville

1) The first letter on each line, prior to the "||" divider, indicates
the type of artist.  Artist types include by default:

        ba Band
        cd Conductor
        cp Composer
        in Individual
        pf Performer
        oa Original Artist
        or Orchestra
        so Soloist
        * a grouping of artists (see below)

These types are defined in ~/etc/db/data.sql in the initial 'types'
data.  You can add additional types by editing data.sql prior to 
configuring Calliope, or through the web interface once Calliope is
set up.  The entry should be the first letter of the type, lower case.

The loader will also handle multiple artist associations.  This is
indicated by type = *.  The 'artist' and variations on that artist
are specified on the left, with a breakdown on the right, e.g.:

	*||Allison Krauss & Gillian Welch|Allison Krauss  Gillian Welch<=>Allison Krauss|Gillian Welch

This tells the loader to associate any song or album attributed to 
'Allison Krauss & Gillian Welch' with *both* Allison Krauss AND 
Gillian Welch (but not necessarily 'Allison Krauss & Gillian Welch').  
This requires that the individual artists/bands have
their own entries as well, that is, both Gillian Welch and Allison Krauss
must also have a line entry in Master.

It is also possible to have a multiple entry *also* be a band entry.
For instance:

	*||Hank Penny and His Radio Cowboys<=>Hank Penny|Hank Penny and His Radio Cowboys

Thus there will be an entry for Penny, Hank under 'P', as well as a 
listing for HP&TTW under 'H'.


Note:  On Capitalization

Capitalization only matters when specifying an Individual or Band's
correct name.  Thus, nothing on the right side of the '<=>' need be 
capitalized (though it can be).  Also, groupings do not need to be capitalized
(Allison Krauss  Gillian Welch == allison krauss  gillian welch).

2) If the artist also has an alternate "alphabetical" listing
(e.g. 'Cash, Johnny' or 'Orb, The'), that appears before the standard 
spelling, separated by an '|'.  This 'alphabetical' listing is optional,
therefore there may be only one way to present an artist (one entry on the
left of the'<=>').

Note that ', The' can be "stripped" during the loading process (if you
don't want it displayed) by changing UseThe in the config file.

3) Next is the Artist or Band name as it would appear in print, e.g.
'Johnny Cash', 'Belle & Sebastion', or 'The Orb'.  

4) Finally, any other variations are listed in lower case after the 
'<=>' divider, and separated by a '|'.  Other cases might include 
known mistaken spellings,  variant punctuations, or other names by 
which the artist might be known.   For instance:

   i||Presley, Elvis|Elvis Presley<=>elvis aaron presley|elvis|the king

Only the artist/band name, and its fileunder variation (if any) are 
stored in the database.  Any other variations are only used to identify a
song's artist for appropriate filing in the database.  





III) using sort.pl

sort.pl is a short script that sorts the Master file.  It first creates
Master.bk, then sorts the Master file into commented lines, artist groupings,
and individuals/bands, with each group being sorted alphabetically.  It further
eliminates blank and duplicate lines, and outputs the results to the Master file.

Usage:

	./sort

Use it after editing the Master file, generally by fixing the new artists at the
top of the file (those with comments before them), then sorting the file.  If you edit
entries and change spellings, you should also sort the file.

Note that sorting has no impact on the loaders functionality, and is strictly for
human readability.




###### END #######