source: mp3-find/trunk/lib/MP3/Find.pm @ 5

package MP3::Find;

use strict;
use warnings;

use base qw(Exporter);
use vars qw($VERSION @EXPORT);

use Carp;

$VERSION = '0.01';

@EXPORT = qw(find_mp3s);

my $finder;
sub import {
    my $calling_pkg = shift;
    # default to a filesystem search
    my $finder_type = shift || 'Filesystem';
    my $package = "MP3::Find::$finder_type";
    eval "require $package";
    croak $@ if $@;
    $finder = $package->new;
    __PACKAGE__->export_to_level(1, @EXPORT);
}

sub find_mp3s { $finder->find_mp3s(@_) }


# module return
1;

=head1 NAME

MP3::Find - Search and sort MP3 files based on their ID3 tags

=head1 SYNOPSIS

    # select with backend you want
    use MP3::Find qw(Filesystem);
    
    print "$_\n" foreach find_mp3s(
        dir => '/home/peter/cds',
        query => {
            artist => 'ilyaimy',
            title => 'deep in the am',
        },
        ignore_case => 1,
        match_words => 1,
        sort => [qw(year album tracknum)],
        printf => '%2n. %a - %t (%b: %y)',
    );

=head1 DESCRIPTION

This module allows you to search for MP3 files by their ID3 tags.
You can ask for the results to be sorted by one or more of those
tags, and return either the list of filenames (the deault), a
C<printf>-style formatted string for each file using its ID3 tags,
or the actual Perl data structure representing the results.

There are currently two backends to this module: L<MP3::Find::Filesystem>
and L<MP3::Find::DB>. You choose which one you want by passing its
name as the argument to you C<use> statement; B<MP3::Find> will look for
a B<MP3::Find::$BACKEND> module. If no backend name is given, it will
default to using L<MP3::Find::Filesystem>.

B<Note:> I'm still working out some kinks in the DB backend, so it
is currently not as stable as the Filesystem backend.

=head1 REQUIRES

L<File::Find>, L<MP3::Info>, and L<Scalar::Util> are needed for
the filesystem backend (L<MP3::Find::Filesystem>).

L<DBI>, L<DBD::SQLite>, and L<SQL::Abstract> are needed for the
database backend (L<MP3::Find::DB>).

=head1 EXPORTS

=head2 find_mp3s

    my @results = find_mp3s(%options);

Takes the following options:

=over

=item C<dir>

Where to start the search. This can either be a single string or
an arrayref. Defaults to your home directory.

=item C<query>

Hashref of search parameters. Recognized fields are anything that
L<MP3::Info> knows about. Field names can be given in either upper
or lower case; C<find_mp3s> will convert them into upper case for 
you. Value may either be strings, which are converted into regular
exporessions, or may be C<qr[...]> regular expressions already.

=item C<ignore_case>

Ignore case when matching search strings to the ID3 tag values.

=item C<exact_match>

Adds an implicit C<^> and C<$> around each query string. Does nothing
if the query is already a regular expression.

=item C<sort>

What field or fields to sort the results by. Can either be a single
scalar field name to sort by, or an arrayref of field names. Again,
acceptable field names are anything that L<MP3::Info> knows about;
field names will be converted to upper case as with the C<query>
option.

=item C<printf>

By default, C<find_mp3s> just returns the list of filenames. The 
C<printf> option allows you to provide a formatting string to apply
to the data for each file. The style is roughly similar to Perl's
C<printf> format strings. The following formatting codes are 
recognized:

    %a - artist
    %t - title
    %b - album
    %n - track number
    %y - year
    %g - genre
    %% - literal '%'

Numeric modifers may be used in the same manner as with C<%s> in
Perl's C<printf>.

=item C<no_format>

Causes C<find_mp3s> to return an array of hashrefs instead of an array
of (formatted) strings. Each hashref consists of the key-value pairs
from C<MP3::Info::get_mp3_tag> and C<MP3::Info::get_mp3_info>, plus
the key C<FILENAME> (with the obvious value ;-)

    @results = (
        {
            FILENAME => ...,
            TITLE    => ...,
            ARTIST   => ...,
            ...
            SECS     => ...,
            BITRATE  => ...,
            ...
        },
        ...
    );

=back

=head1 BUGS

There are probably some in there; let me know if you find any (patches
welcome).

=head1 TODO

Better tests, using some actual sample mp3 files.

Other backends (a caching filesystem backend, perhaps?)

=head1 SEE ALSO

L<MP3::Find::Filesystem>, L<MP3::Find::DB>

L<mp3find> is the command line frontend to this module (it
currently only uses the filesystem backend).

See L<MP3::Info> for more information about the fields you can
search and sort on.

L<File::Find::Rule::MP3Info> is another way to search for MP3
files based on their ID3 tags.

=head1 AUTHOR

Peter Eichman <peichman@cpan.org>

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2006 by Peter Eichman. All rights reserved.

This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=cut