id3autosort - ID3-based MP3 sorting utility
-------------------------------------------

id3autosort is a lightweight, multi-platform, Python-based script that
allows the user to organize their MP3 library based on the ID3 information
stored inside their MP3s. It supports all current ID3 tag implementations,
including ID3v1, ID3v1.1, ID3v2.2, ID3v2.3 and ID3v2.4.

The idea for id3autosort dates back to summer 2007. After discovering the
joys of LimeWire, my music library had ballooned to over 800 mp3s. I realized
that I could find a specific song easily when listening to music on my
computer, since my music player sorted by ID3 tags; but when I was selecting
songs to listen to on my mp3 player I realized just how unorganized my
library really was.

With a determination to organize my collection I embarked on this venture,
planning to organize each mp3 by artist and album. I realized this could take
days or even weeks by hand, so I set out to find a program to do this for
me. When I found that there were no tag-based mp3 organization programs for
Linux, I decided to write one myself. Unfortunately I was not proficient in
Python back then, and while I decided to organize my library by hand then
the idea remained in my mind.

Flash forward to 2009: I had just downloaded a free compilation album and
wanted to get it in my library, but I didn't want to do for this album what
I did for my library two years ago. At this point I remember this project
from two years ago and, being much better at Python, decide to revisit it
to see what I could do. Two days later, id3autosort was born.

Author
------
Jeremy Brown <code@mischivous.com>

Examples
--------
The default behavior is to sort the MP3s into an Artist/Album hierarchy, so
if you had some MP3s you wanted to move from a "music" folder to a
"newmusic" folder, and the "music" folder looked like:

05) G-Unit - Stunt 101.mp3
pinksowhat.mp3
daft_punk_discovery_one_more_time.mp3
Nine-Black-Alps-Shot-Down-9.mp3

If all the songs are properly tagged, from the folder that contains the
"music" folder, you would run the program with:

id3autosort.py music newmusic

and the program will:

a) Create the "newmusic" folder (if it already does not exist)
b) Sort the MP3s into their corresponding folders inside "newmusic", which
   will have the result:

newmusic_
	 |
	 Daft Punk_
	 |	   |
	 |	   Discovery_
	 |		     |
	 |		     daft_punk_discovery_one_more_time.mp3
	 G-Unit_
	 |	|
	 |	Beg For Mercy_
	 |		      |
	 |		      05) G-Unit - Stunt 101.mp3
	 Nine Black Alps_
	 |		 |
	 |		 Everything Is_
	 |			       |
	 |			       Nine-Black-Alps-Shot-Down-9.mp3
	 Pink_
	 |    |
	 |    Funhouse_
	 |	       |
	 |	       pinksowhat.mp3

Of course, you can change the way id3autosort sorts MP3s with the use of
the corresponding flag:

-a	Sort in Artist Only structure
-l	Sort in Album Only structure
-r	Sort in Artist - Album structure
-t	Sort in Artist/Artist - Album structure

So if you only wanted to sort your music by artist, you would run the
program with:

id3autosort.py -a music newmusic

Which will have the result:

newmusic_
	 |
	 Daft Punk_
	 |	   |
	 |	   daft_punk_discovery_one_more_time.mp3
	 |
	 G-Unit_
	 |	|
	 |	05) G-Unit - Stunt 101.mp3
	 |		      
	 Nine Black Alps_
	 |		 |
	 |		 Nine-Black-Alps-Shot-Down-9.mp3
	 |			       
	 Pink_
	 |    |
	 |    pinksowhat.mp3

Known Bugs
----------
  Non-standard Characters
  -----------------------
  * The ID3 reader this script is based on can only understand the English
    alphabet and Arabic numerials.

  Musical Tastes
  --------------
  * The ID3 reader this script is based on uses the word "None" to say when
    there is no tag corresponding to the one requested and to skip the mp3;
    therefore music by the band None will not be sorted.

Todo List
---------
If you are interested in helping out, please check out this list and
send me patches :)

 * Documentation !!
 * Find a new ID3 reader that works with non-standard characters
 * Find a new ID3 reader that works with the band None
 * Allow for the ability to sort by Genre
 * Create small GUI
 * Create Windows executable with said GUI

License
-------
This program is licensed under the 3-clause BSD license. I would appreciate
it if you give me a quick email if you find it useful :) More details in the
LICENSE file included with this distribution.
