Bulk ID3 Files

*** THIS IS AN ALPHA RELEASE AND SHOULD ONLY BE RUN AGAINST TEST FILES! ***


[Introduction to ID3 Tags]

In a nutshell, an ID3 tag is piece of information embedded in an MP3 file, typically at the beginning.  An ID3 tag is composed of smaller pieces of information called frames.  Each frame contains information about the track, such as the artist, title, album, etc.  Each frame has an ID which identifies what type of information is contained in the frame.  For example, the ID of a frame that typically contains the track's artist is TPE1.  Most likely a frame you want to keep.  In addition, a track's title is usually specified by a frame ID of TIT2.  These are common frames found in most tags.  There are many frame types, and a frame can contain any type of information*.  Frames often contain a lot stuff you might not expect.  Many tag editors don't show this extra information or allow access to it.  Bulk ID3 does.



[Introduction to Bulk ID3]

There are many good -- and free -- ID3 tag editors available.  These are often built directly into a media player, and are usually designed to allow the user to edit the currently playing track.  Bulk ID3 is different, and was created to allow en-masse updating of ID3 tags.  That is, Bulk ID3 allows an entire collection of MP3 files to be updated at once.  The essential purpose is to clean and organize a collection of MP3 files.  Bulk ID3 is not designed to add ID3 tags to files that don't have existing tags.

Bulk ID3 supports version 1.0, 2.3 and 2.4 ID3 tags.



[Description and Usage]

Bulk ID3 is a command line utility designed to facilitate precise control over ID3 tags in MP3 files.  Its usage and purpose are best illustrated by an example.


[Example 1] - Basic usage.

  	bulkID3 --frames=TIT2,TPE1 directory

	In the example above, Bulk ID3 will perform a series of actions:

	-- Process every MP3 file in 'directory' and its sub-directories.  
	-- Each file that contains a version 2.x ID3 tag will be stripped of all frames* (read: data elements) except the frames TIT2 and TPE1, which will be retained.  Typically the frames TIT2 and TPE1 represent the song's title and artist, respectively.  
	-- Upgrade all tags to version 2.4.
	-- Strip all version 1.x tags from the file.  
	-- Convert all text based tags to UTF-8 encoding.  
	-- Strip all padding following the tag.

	This process is somewhat invasive and CANNOT be undone, so be sure you know what you're doing.  Performing the operation against a set of test files first, is definitely recommended.
	
	Bulk ID3 supports all known frame types*.  If you find a frame type that Bulk ID3 does not support, please contact me and I'll add support for it.


[Example 2] - File renaming.

	bulkID3 --frames=TIT2,TPE1 --rename directory

	In example 2, since '--rename' is specified, Bulk ID3 performs the same operations as in example 1, and additionally will attempt to rename each file using the TIT2 (title) and TPE1 (artist) frames.  If suitable artist and title frames cannot be found, the file is not renamed.  The only rename format currently available is, 'title - artist.mp3' (e.g. Dave Matthews Band - Crash.mp3).  More flexible format options may be added in future releases.  


[Example 3] - Organizing files and directories.

	bulkID3 --frames=TIT2,TPE1 --rename --move directory

	In the above example, the '--move' flag causes Bulk ID3 to organize the MP3 files and directories as they're being processed.  Each file is moved to a sub-directory of 'directory', matching the file's artist.  Each artist directory is a sub-directory of the user supplied 'directory'.  If an artist directory does not exist, it is created (e.g. directory/Dave Matthews Band/Dave Matthews Band - Crash.mp3).  If a suitable artist frame cannot be found in the tag, the file is not moved.  When '--move' is specified, it is possible that some files may be processed more than once as a result of being relocated.  This is rare and harmless, save the time to re-process the file.

	Be careful with this option as it can produced non-intuitive results.  For example, if your MP3 collection resides in /home/user/media/music/mp3s and you specify /home/user for the directory argument, Bulk ID3 will start in /home/user and create the relocated directory structure in /home/user.  This will move most, if not all the MP3 files from /home/user/media/music/mp3s to /home/user/<artist>.


[Example 4] - Viewing tag data.

	bulkID3 --print-only directory

	In example 4 no tag modification takes place.  Bulk ID3 simply displays all available tag data.  This allows you to see everything ID3 related in your files.


* For a list of ID3 frames and their descriptions see http://id3.org/id3v2.4.0-frames.



[Web site]

sourceforge.net/projects/bulkid3



[Feedback and Bug Reports]

Comments, suggestions and bug reports are appreciated.  Please send to andrew (dot) laughlin (at) gmail.com.



[Credits]

Thanks to Jonathan Leffler.



[Disclaimer]

Absolutely no warranty is given or implied.