MP3Shell - Manage a database of your MP3 collection
Currently documented version is 1.17. Note that commands and interface may change in future releases.
mp3shell [options]
Options:
-h or -h or -help brief help message
-man or -manual full documentation
-v version
-create create databases if they do not exist
These are the only command line options currently
availlable. All other functionality has to be accessed
interactively through the shell.
In order to use mp3shell, you need the following modules installed on your system: (Beside, of course, Perl 5.6.1 or later.)
Config::IniFiles Data::Dumper DB_File File::Basename File::Copy File::Find File::Path Getopt::Long MP3::ID3v1Tag MPEG::ID3v2Tag Pod::Select Pod::Usage Storable Term::ReadKey Text::ParseWords Time::HiRes Tie::Hash::Abbrev
Note that this application may well function with different versions of the listed modules, but the generated database files might not work with older versions. Specifically, this limitation applies to the DB_File and Storable modules.
Currently, this program has only been tested on MS Windows. It may or may not work on other platforms, but the databases created using DB_File are more likely than not unportable. Additionally, some of the path and file name munging done in the scancd and copy routines may not be portable to other systems. I appreciate any feedback on this issue.
I have a rather large collection of MP3s on 21 CDs. (That may not be large compared to some people's collections, but I neither have a 180GB harddrive nor a big pipe to download music with. Those songs came from my own music CDs.) Those MP3s were archived in no particular order, so when I wanted to listen to all songs of a specific artist, I used to have to search all 21 CDs. I got sick of that, so I wrote this.
MP3Shell is an application that allows you to manage a large collection of MP3 music files on CDs. It can automatically scan CDs for MP3s and WAVs and collect information on those files from ID3V1 and ID3V2 tags. The files are indexed by artist, song title, album, the CD they were found on, the year the songs were created, genre, and filename.
The application allows you to search the database using regular expressions. See also CONCEPTS. The records that match will be stored in a queue of currently selected songs. You can then have the selected records pretty-printed to your terminal or have the application copy the associated files from the MP3 CDs to your harddrive.
The queue simply is a container for all currently selected records. Many commands just operate on the queue without further specification. For example, 'show' pretty-prints the currently enqueued records to your terminal and 'copy' transfers the selected files to your harddrive.
You may store any number of queues into the archive for later use. Please see the 'store', 'recall', 'archive', 'remove', and 'erasearchive' commands for details.
The queue archive is stored in the configuration file.
Configuration is kept in a file called 'mp3shell.cfg' that will be searched for in the current direcory and the directories in the special '@INC' variable. Never mind that @INC thing.
The database is spread across multiple files. The names of those files can be reviewed in the configuration file. The database files will be searched for in the current directory and the directories in the special '@INC' variable. Again, don't bother worrying about @INC if you never heard of it. It's for the binary distribution with enclosed databases.
The format string is a central concept that is important to several commands including 'show' and the sort family of commands.
There are several special notations about this string that will be replaced with corresponding record values by the show command. (and the sort commands internally)
$ARTIST The artist associated with the record $TITLE The song title associated with the record $SIZE The file size associated with the record $FILE The file name associated with the record $ALBUM The album name associated with the record $YEAR The year associated with the record $KEY The internal key associated with the record (keys are unique) $GENRE The genre associated with the record $CD The CD no. associated with the record
Additional formatting may be achieved by adding more information between the $ sign and the keyword. This additional information may be either a positive or a negative integer number. This integer number is then used as a fixed field length. Negative numbers are left justified, positive numbers are right justified.
Example:
format "$-3CD| $12ARTIST - $TITLE"
This record:
title = 'Alive'
artist = 'Pearl Jam (live)'
from cd = 12
will become:
"12 | Pearl Jam (l - Alive"
This section of the documentation has not yet been written. I suggest you read perlrequick for a brief introduction to regular expressions.
The following commands are availlable in the shell:
addselect, archive, copy, copydir, erasearchive, extendedsort, format, help, persistance, quit, recall, remove, scancd, select, set, show, size, sort, store
The commands will be listed alphabetically, so you might have to jump around in the docs to get the basics.
addselect performs a selection similar to the select command, except that the current queue will be retained and the results of the current select will be appended to the queue. (Only unique records, though.) Options:
-s Perform case sensitive search. The -k and -r switches are not availlable with addselect.
For more information, please see 'help select'.
This command displays all entries in the queue archive.
This command takes one, two or no arguments and has the following syntax: copy SOURCEDIR DESTINATIONDIR
SOURCEDIR and DESTINATIONDIR may be omitted and default to the values user.cddir and user.mp3dir set in the configuration file. (See also the manual entry on the set command.)
The program will then query you to insert the data CDs in ascending order. It will try to locate the music files on the CDs and copy the files to the specified destination directory without preserving the directory structure present on the data CD. If you wish do leave the directory structure intact, use the copydir command.
The copydir command works similar to the copy command except that it also copies the directory structures on the source CDs.
See also the manual entry on the copy command.
This command erases the complete queue archive.
Please look at the help for the sort command for simple (reverse) asciibetical or numerical sorting.
extendedsort may be used to sort by several criteria. The format string is split on every occurrance of the pipe '|' character. The separate sections are then sorted with descending precedence. Every section may have its own sorting attributes like asciibetical vs. numerical sorting and reverse sorting. By default, every section will be sorted asciibetical in ascending order.
You may specify the way to sort every section by providing one argument string of n's and r's separated by commas. "nr,r,n,,,r" will sort the first section numerically, highest first, the second section will be sorted asciibetically but reversed, the third will be sorted numerically, ascending. The fourth and fifth section will be sorted normally and the sixth section will be sorted in reverse order. All sections thereafter will be sorted normally (asciibetically, that is).
Note that due to a bug, pipes in the record data will screw this over because they are treated as delimiters. Using them in record data luckily is rather rare. So don't do that for now. !!!FIXME!!!
Format without argument prints out the current format string. Format with an argument sets the format string to the string specified. Please see CONCEPTS for more detail on what format strings are.
Displays help. If passed a command name as an argument, it displays more specific help for that command.
Saves the current queue and the changes to the configuration.
This command exits the shell and saves the current queue and configuration if the user.save_cfg_on_exit option has been set (default).
Restores a queue in the queue archive to the current working queue. Requires a parameter denoting the entry name in the queue archive. You may list the current archive contentsa using the 'archive' command.
Deletes an entry from the queue archive. Requires a parameter denoting the entry name in the queue archive.
Please use this command with care and backup your database beforehand.
scancd will scan a directory structure for MP3s and WAVs, try hard to determine all required data (artist, song title, etc.) and save the data in the database. If artist and song title could not be determined, the file will be skipped.
The routine used to determine song information reads the ID3v2 tag and takes all availlable information from there. Then, it fills the blanks with information from the ID3v1 tag. If, however, artist and song title could still not be determined, it resorts to a rather questionable method of searching for data: It analyzes the file name. Unfortunately, there are a lot of frequently used syntaxes for (descriptive) names of music files, but in my experience, the most often seen syntax is
"\s*ARTIST\s*-\s*SONGTITLE\s*\.mp3"
Where the "\s*" denote any amount of whitespace. If you happen to name your songs the other way round or completely different, the routine may either not work at all (Good Thing), or just get it wrong and insert bogus records into the database which is a very Bad Thing. That is why you need to have a quick glance at the filenames before using scancd.
scancd takes two required arguments:
scancd CDDIR CDNUMBER
where CDDIR is the root directory to scan and CDNUMBER is the CD identifier to associate the found songs with.
CDNUMBER does not have to be unique in respect to the previously scanned CDs, but unless you want to ruin usability of the copy command, you should assign unique CD numbers.
Example usage: (CD drive is f: and previously, 20 CDs have been scanned.)
scancd "f:/" 21
By default, select deletes the current queue and fills it according to the new selection. Synopsis: (normal shell quoting applies.)
select [OPTIONS] [DB:REGEX ...]
Options:
-r Reset current queue before selecting; precedence over -k!
-k Do not reset current queue but instead perform search on
elements in queue only.
-s Perform case sensitive search.
Where "DB" is the name of the database to select from and
"REGEX" is a valid Perl regular expression that will be applied
to all records in the database. Please see CONCEPTS for an
introduction to simple regular expressions.
Valid databases are: title, cd, artist, album, year, genre. Additionally, there is a meta-database 'all' that will be internally translated to searching in all of the above databases. Examples:
select "artist:^Pearl Jam" "year:^197.$" Selects all records whose artist name starts with "pearl jam" as well as all songs from the 1970's. select -k -s title:Alive Selects all records in the current queue whose titles contain the word "Alive" (note the captial A) and removes all other records from the queue.
This command can be used to set various options some of which may also be set using dedicated commands such as the format string with the format command.
set is provided as a tool for the advanced user to quickly review or edit user configuration without editing the configuration file by hand. Note, however, that you cannot set all options in the configuration file using the set command.
Syntax for set: Without arguments, set displays all accessible settings. With one argument of the form "sectionname.parametername", set displays one specific setting. With two arguments, the first being of the same form as mentioned above, the corresponding option will be set to the second argument.
You may use the "-p" flag anywhere to pipe the output through the pager.
By default, this inserts the appropriate values in the current format string for every record in the queue.
If the -p option has been specified, the output will be page-wise.
Please see CONCEPTS for more information on format strings.
Calculates and displays the cumulated size of the records in the queue.
Sorts the current queue asciibetically by the records' format string. Eg. to sort by artist, set the format string to "$ARTIST" using the format command. Then use the sort command. Afterwards, you may set the format string to whatever you want the output to look like.
There are two valid options to the sort command:
-n perform numerical sort. "1974" will be higher than "99".
(This is not the case in an asciibetical sort because 9 is
higher than 1.)
-r perform reverse sort.
For more involved searching, please look at the help for the extendedsort command.
Saves the current queue to the queue archive. Requires a parameter denoting the entry name in the queue archive. The entry names may only contain of alphanumeric characters and the underscore.
The command does not prompt you for confirmation if you overwrite existing archive entries.
This section will explain how to create stand-alone executables that contain their databases.
It is usually pretty hard to create stand-alone executables from Perl programs of some complexity. You'd normally try to use perlcc which comes with Perl 5.6 or newer and try to create C code from your Perl source. If that didn't fail anyway, you'd end up with a huge chunk of C code you'd have trouble compiling anyway.
That is why some companies are able to sell programs that don't actually compile Perl sources as perlcc does, but package them with the interpreter instead. Naturally, this will not yield a noticable speed improvement and inflict humongeous file sizes upon the unsuspecting user. In return, those packagers provide some functionality a compiler does not: You may package additional files with the executable.
There are currently two competing products I know of and feel comfortable recommending. Both of these are not freely availlable, sorry. On one hand, there is perl2exe from IndigoStar. On the other hand, there is ActiveState's perlapp (part of the Perl Dev Kit). I happen to own a license for the latter, so I can't help but explain how to create stand-alones with perlapp only. Get me a license for perl2exe and I will... Nevermind, you won't get me one, will you?
Once packaged, the database cannot be permanently modified anymore (for example using the scancd command). That's because upon execution, the database is extracted from the executable and then opened like it would be if you were running the Perl sources. As a matter of fact, you might be able to add records to the databases, but these changes will not be reflected by the packaged executable. And your database may be wiped by any system cleanup that deletes temporary files. The database will then be reextracted from the package.
In the distribution of mp3shell, there should be a simple Perl script that calls perlapp with the correct parameters to create an executable of all required database files and modules. That is, unless you modify the default filenames. The script should be called "createexe.pl".
Just put the previously filled databases and the Perl sources into a directory and run createexe.pl. If you have perlapp installed, you should end up with an executable containing the database. Try copying it to a different directory and running it.
Steffen Mueller, mail at steffen-mueller dot net
Copyright (c) 2003 Steffen Mueller. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the Artistic License or the GNU General Public License for more details.
This program relies heavily on a lot of modules. Without some of the following modules, this program would not be here for you to use:
Config::IniFiles, DB_File, File::Basename, File::Copy, File::Find, File::Path, Getopt::Long, MP3::ID3v1Tag, MPEG::ID3v2Tag, Pod::Usage, Pod::Select, Term::ReadKey, Text::ParseWords, Time::HiRes, Tie::Hash::Abbrev
And, of course: