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.

cpanm Audio::DB

perl -MCPAN -e shell
install Audio::DB