1. License
2. Requirements
3. Goal
4. First Time Use
5. Usage Basics
6. Playlist Strings
7. Example Playlist Strings
8. Version History

The ID3Browse software, source-code and documentation is distributed under the following Open Source license:

This software requires Windows 95 or better. I have tested it on Win98, Win2000 and WinXP. It should work on Windows 95, ME, and NT, too.

The program needs about 10megs of free memory to run on a library of 15,000 MP3s.

The goal of this software is to automatically generate playlists organized in directories from any information found in ID3 tags. The core use of this is to emulate ID3 based browsing for File-System based MP3 players such as Archos' portable MP3 and AV players.

This could have been done in a very simple way supporting the standard Album, Artist, Genre, and Song sorting schemes typically hard coded into Media libraries and MP3 players. However, I wanted to make a utility that was much more flexible; that allowed you to generate playlists in directory structures in nearly anyway you can think of.

To generate some standard ID3-based browsing directories and playlists, follow the simple quick-start guide below. This will make an ID3 directory on the root of your hard drive with many directories and playlists inside it. It will not delete, move, copy or otherwise modify your MP3s.

Quick Start:

1. Copy ID3Browse.exe and the .bat files to your hard drive (or MP3 player) with all your MP3 files (anywhere on that hard drive will do)
2. Double click on the "Generate Standard ID3 Based Browsing.bat" file on the hard-drive you copied it to (this only works if the bat file is on the same drive as all your MP3s).
3. Wait a few minutes while the ID3 directories and playlists are created
4. When it is done you will see the message: "ID3Browse - done!" and some statistics.
5. Press a key to close the window - that's it!

The batch file in step 3 above creates 4 standard ways to browse your MP3s:

• By Artist
• By Album
• By Genre
• By Year

Disconnect your MP3 player and browse the ID3 directory - you should find it very much like browsing your whole collection by ID3 tags! Whenever you add MP3s, just re-run this program. If you delete MP3s, delete the ID3 directory and re-run this program.

Want more? With ID3Browse you can set up just about any way to browse your MP3s based on ID3 tags. Read on if you want to learn how.

The Basic Idea

ID3Browse generates M3U files and directories. To do this, it first makes a list of every MP3 in every ScanDir (root directories you provide) and their sub-directories. Then, for each MP3 file in that list, it adds the MP3 to the playlist specified by the PlaylistString. When all MP3s have been processed, duplicates are removed from every playlist (each MP3 will appear in each playlist at most once), the playlists are sorted by track number (or whatever custom sort you want), and, finally, every playlist is written to disk, creating all necessary directories as it goes.

You can specify more than one PlaylistString. In the case of multiple PlaylistStrings, each MP3 is added to the playlist specified by each PlaylistString. (Aside: The maximum number of playlists that could possibly be generated is the number of MP3s times the number of PlaylistStrings.)

A PlaylistString is the path and name of the M3U playlist file every MP3 will be added to. The only thing special is that PlaylistStrings may contain certain keywords (words that start with the pipe, '|' character) which will be replaced with actual information from the MP3's ID3 tag (or other sources). In this way one PlaylistString may represent many M3U files. For example, the playlist string "\ID3\Genre\|Genre" will generate the playlist "\ID3\Genre\Rock.m3u" for an MP3 with the Genre of Rock in its ID3 tag and "\ID3\Genre\Disco.m3u" for one with Disco for its genre.

Using ID3Browse

ID3Browse is a command-line tool. You control its various options with command-line parameters. It is probably easiest to start by copying one of the sample ".bat" files provided with ID3Browse and making changes and seeing what they do. Below is a description of how the command-line parameters work:

Usage: C:\> id3browse ScanDir(s) [*.id3b ConfigFile(s)] [/options] [/playlist="PlaylistString"]

1. ScanDirs, config files, options, and playlists may appear in any order
2. One or more ScanDirs must be provided
3. Zero or more Playlists can be provided
4. Parts in brackets '[]' are optional (don't actually type the []s)

ScanDirs: ID3Browse scans every scan dir for MP3s.

ConfigFiles are text files with the extension .id3b. They simply contain a list of ID3Browse command-line options, one per line. Any ID3Browse command-line option - include other ConfigFiles - can be listed and will be interpreted as if they were typed in on the command-line.

Boolean Options (off by default):

• /AllowBackslashes - Don't remove backslashes from FormatVariable values (see Playlist Strings below)

Normally, if there is a Backslash (\) in the string resulting from a FormatVariable, they are replaced with '!' characters since otherwise they would create extra sub-directories. However, if this is what you want, use this setting.

• /CommentPlaylists - Output comments in the playlist files.

This is most useful to see how your SortStrings are working. Normally SortStrings are not displayed so you might be confused why your tracks are being sorted in a certain order. By turning on the /CommentPlaylists option and viewing your playlists with a text editor, you can see exactly how ID3Browse is sorting your playlists. If it isn't sorting them the way you want, you can set a different /SortBy setting.

• /DriveLetters - enables outputting drive-letters in playlist entries
• /IgnoreDir - ignores all files in dir or its subdirs
• /IgnoreID3v1 - ignore ID3 v1 tags
• /IgnoreID3v2 - ignore ID3 v2 tags
• /IgnoreTagless - ignores files with no ID3 tags (or only ignored id3 tags)
• /PreferID3v1 - use ID3 v1 tags over v2 tags (default is v2 over v1 tags)

If all your v2 tags are up to date, but your v1 tags are a mess, or visa versa, you may just want to ignore the "not-up-to-date" tag-set. Alternatively, you may wish to just swap the priority. By default, all v2 tag values take priority over v1 tag values.

• /ReadOnly - do all the prep-work but don't actually create any dirs or playlists

This is useful, particularly in combination with the /Verbose option, to test your ID3Browse options without writing anything to disk.

• /TagReport - show a tag-report when done

The TagReport is displayed at the end of your ID3Browse run and it tells you a bit about what is in your MP3 files. It tells you how many of each type of tag it found as well as what types of fields (or frames) within those tags that it found.

• /Verbose - show everything ID3Browse is doing in detail

Settings:

• /MaxPlaylistSize=# - set the maximum number of files to put in a playlist. Default: no maximum

If a MaxPlaylistSize is set then any playlist that is larger is broken apart into multiple files. These split playlists are numbered by adding its number to the end of the M3U's name (complete with 0-padding when necessary so alphabetical listing still sorts them correctly).

• /MinPlaylistSize=# - playlists smaller than Min are not created. Default: 1
• /MiscPlaylistName=string - merge all too-small playlists into one. Default: (too-small playlists are discarded)

When a playlist has fewer files than MinPlaylistSize, it is simply not created. Instead of discarding all too-small playlists, you can merge them into miscellaneous playlists, one per directory. Just set the /MiscPlaylistName setting when you set your /MinPlaylistSize to do this.

• /SortBy=format_string - default M3U sort (SortString may contain any character or FormatVariable). Default: |Artist|Album|04TrackNum

By default, playlists are sorted by Artist, Album and Track Number. However, you can set up your own custom sort however you want. The /SortBy format string looks just like a /playlist string in that you can use characters and FormatVariables. A SortBy string is generated for every MP3 in every Playlist. Once the playlist is ready to be written to disc, the list is sorted alphabetically by the MP3's SortBy strings.

Note: Each /playlist string can override the default /SortBy format string with its own, unique format by adding a '|SortBy=" clause to the end of the /playlist string.

• /UnknownString=string - string to use for unknown values. Default: (Unknown)

  When a FormatVariable cannot find the requested information (for example if there is no Artist entry for an MP3 and the |Artist FormatVariable was used), then the /UnknownString is used. By default the text "(Unknown)" is inserted.

A playlist string is the Path and Name (without the .m3u extension) of the playlist to be created. Every MP3 scanned (with an ID3 tag), is added to the playlist specified by each playlist-string. The magic happens when you have FormatVariables in your playlist string that cause different MP3s to be placed into different playlists.

Quick Info:

• A playlist string is indicated by a /playlist="playlist_string" on the command-line.
• Playlist strings should always be quoted.
• Playlist strings may contain 0 or more FormatVariables (see below).
• PlaylistStrings may also have an optional "|SortBy=" clause that overrides the default SortBy string specified by the /SortBy option. Each playlist's tracks are sorted alphabetically by the track's SortStrings.
• Example: /playlist="ID3\Artist\|Artist\|Album"
• There are many more examples at the end of this file...

Playlist string variables are the key to making ID3Browse useful. When an MP3 is processed, all the FormatVariables in each PlaylistString are replaced with their corresponding values out of that mp3's id3 tag and file information . The result, for each playlist string, is a specific playlist string - the playlist that MP3 will be added to.

FormatVariables are formatted as follows:

• |[0][-][MinWidth][.MaxWidth]Keyword

Keywords:

If a particular MP3 is missing the ID3 Frame requested by the keyword (or the Directory# or MultiGenre#), the value "(Unknown)" is used (or whatever string you set with the /UnknownString option). Files with unknown FormatVariable values can be ignored (not added to that specific playlist) with the /ignoreunknowns option.

For each variable, there are options on how it is formatted. The key things you can control are: the minimum number of characters it will be, the maximum number of characters, the alignment, and the character to use when the variable is shorter than the minimum number of characters (PadChar). The Format options are:

• Leading zero [0] sets the PadChar='0' and toggles the justification.
• Leading minus [-] toggles the justification.
• [MinWidth] - a positive integer - guarantees a least MinWidth characters will be used.
• [.MaxWidth] - a positive integer - guarantees no more than MaxWidth characters will be used
• Defaults: Left justified, MinWidth=0, PadChar=a space, no MaxWidth
• Example: |03.3NumTracks (right justified, pad with zeros, must be exactly 3 characters wide)

There are no limitations on the strings in ID3 tags, but the characters \, /, :, *, ?, <, >, and | are illegal in Windows file names. In the case of any illegal Windows file-name character, ID3Browse replace it with an exclamation mark: '!' (if /allowbackslashes is on, '\' are left alone). Any control character (< ascii value 32) is replaced with a space: ' '. All other characters are left alone.

The best way to really understand ID3Browse is through a bunch of examples, so below I have provided many. For every example I provide the exact /playlist="..." command-line option, an example generated playlist, and the 'verbose' description of the playlist string (a wordy, yet precise, computer-generated description).