NAME
Audio::DB - Tools for generating relational databases of music files
SYNOPSIS
use Audio::DB;
my $mp3 = Audio::DB->new(-user => 'user',
-pass => 'password',
-host => 'db_host',
-dsn => 'music_db',
-adaptor => 'dbi::mysql');
$mp3->initialize(1);
$mp3->load_database(-dirs =>['/path/to/MP3s/'],
-tmp =>'/tmp/');DESCRIPTION
Audio::DB is a series of modules for creating relational databases of music files directly from data stored in ID3 tags or from flatfiles of information of track information. Once created, Audio::DB provides various methods for creating reports and web pages of your collection. Although it's nutritious and delicious on its own, Audio::DB was created for use with Apache::MP3::DB, a subclass of Apache::MP3. This module makes it easy to make your collection web-accessible, complete with browsing, searching, streaming, multiple users, playlists, ratings, and more!
USAGE
There are three central modules that you will be interacting with. Audio::DB::Build, Audio::DB::Web, and Audio::DB::Reports. Audio::DB itself provides a generic factory interface for building these objects. Audio::DB returns an appropriate object for the desired task at hand.
Creating A New MP3 Database
Creating a new database is as easy as:
use strict;
use Audio::DB;
my $mp3 = Audio::DB->new(-user =>'user',
-pass =>'password',
-host =>'db_host',
-dsn =>'music_db',
-create =>1);
$mp3->initialize(1); # Populates the database with schema
my $stats = $mp3->load_database(-dirs =>['/path/to/MP3s/'],
-tmp =>'/tmp/');Appending To A Preexisting MP3 Database
Appending new mp3s to a preexisting database is as easy as:
use strict;
use Audio::DB::Build;
my $mp3 = Audio::DB->new(-user =>'user',
-pass =>'password',
-host =>'db_host',
-dsn =>'music_db');
$mp3->update_database(-dirs =>['/path/to/MP3s/'],
-tmp =>'/tmp/');REQUIRES
Perl Modules:
MP3::Info for reading ID3 tags, LWP::MediaTypes for distinguising types of readable files, DBD::SQLite for SQLite support; DBD::mysql for interacting with MySQL databases.
MySQL must be installed if you wish to use MySQL as your RDBMS.
EXPORTS
No methods are exported.
METHODS
new
Title : new
Usage : Audio::DB->new(-adaptor => 'dbi::mysql',
-user => 'user',
-pass => 'password',
-host => 'db_host',
-dsn => 'dbi:mysql:music_db',
-task => '[build|web|reports]');
Function : create a new Audio::DB:: object
Returns : new Audio::DB::Build,Audio::DB:Web,or Audio::DB::Reports object
Args : lists of adaptors and arguments
Status : Public
These are the arguments:
-adaptor Name of the adaptor module to use. Currently only supports
dbi:mysql. defaults to dbi:mysql if not provided.
-dsn The DBI data source, e.g. 'music_db'. Can also be specified
as -database.
-create Optional. If passed boolean true, the database will be created
if it does not already exist. (Requires create privileges for the
provided user).The commonly used dbi-adaptor is passed the following arguments via the new method:
-user[name] username for authentication
-pass[word] the password for authentication
-host where the database lives
<other> Any other named argument pairs are passed to
the adaptor for processing.The adaptor argument must correspond to a module contained within the Audio::DB::Adaptor namespace. For example, the Audio::DB::Adaptor::dbi::mysql adaptor is loaded by specifying 'dbi::mysql'. By Perl convention, the adaptors names are lower case because they are loaded at run time.
Audio::DB currently supports dbi::mysql and dbi::sqlite. dbi::sqlite is a small standalone SQL server that is usually sufficient for most Audio::DB tasks. This makes it the perfect option for including Audio::DB in embedded applications. If you are interested in adding other adaptors, please contact me.
SEE ALSO
Also see the documentation for Audio::DB::Build for information on building databases, Audio::DB::Web, a module that provides a web browsable interface to the database, and Audio::DB::Reports, for methods that generate reports on your collection.
BUGS
This module implements a fairly complex internal data structure, which in itself rests upon lots of things going right, like reading ID3 tags, tag naming conventions, etc. On top of that, I wrote most of this in a Starbucks full of screaming children.
TODO
Need a resonable way of dealing with tags that can't be read
Lots of error checking needs to be added. Support for custom data schemas, including new data types like more extensive artist info, paths to images, etc.
Keep track of stats for updates. Fix update - needs to use mysql (these are the _check_artist_db routines that all need to be implemented)
Robusticize new for different adaptor types
Add in full MP4 support make the data dumps rely on the schema in the module put the schema into its own module
AUTHOR
Copyright 2002-2004, Todd W. Harris <harris@cshl.org>.
This module is distributed under the same terms as Perl itself. Feel free to use, modify and redistribute it as long as you retain the correct attribution.
ACKNOWLEDGEMENTS
Chris Nandor <pudge@pudge.net> wrote MP3::Info, the module responsible for reading MP3 tags. Without, this module would be a best-selling pulp romance novel behind the gum at the grocery store checkout. Chris has been really helpful with issues that arose with various MP3 tags from different taggers. Kudos, dude!
Lincoln (Dr. Leichtenstein) Stein <lstein@cshl.org> wrote much of the original adaptor code as part of the l<Bio::DB::GFF> module. Much of that code is incorporated here, albeit in a pared-down form. The code for reading ID3 tags from files only with appropriate MIME-types is borrowed from his <Apache::MP3> module. This was a much more elegant than my lame solution of checking for .mp3! Lincoln tolerates having me in his lab, too, even though I use a Mac.