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

Last change on this file since 42 was 42, checked in by peter, 13 years ago

incremented version to 0.07

File size: 5.5 KB
Line 
1package MP3::Find;
2
3use strict;
4use warnings;
5
6use base qw(Exporter);
7use vars qw($VERSION @EXPORT);
8
9use Carp;
10
11$VERSION = '0.07';
12
13@EXPORT = qw(find_mp3s);
14
15my $finder;
16sub import {
17    my $calling_pkg = shift;
18    # default to a filesystem search
19    my $finder_type = shift || 'Filesystem';
20    my $package = "MP3::Find::$finder_type";
21    eval "require $package";
22    croak $@ if $@;
23    $finder = $package->new;
24    __PACKAGE__->export_to_level(1, @EXPORT);
25}
26
27sub find_mp3s { $finder->find_mp3s(@_) }
28
29
30# module return
311;
32
33=head1 NAME
34
35MP3::Find - Search and sort MP3 files based on their ID3 tags
36
37=head1 SYNOPSIS
38
39    # select with backend you want
40    use MP3::Find qw(Filesystem);
41   
42    print "$_\n" foreach find_mp3s(
43        dir => '/home/peter/cds',
44        query => {
45            artist => 'ilyaimy',
46            title => 'deep in the am',
47        },
48        ignore_case => 1,
49        exact_match => 1,
50        sort => [qw(year album tracknum)],
51        printf => '%2n. %a - %t (%b: %y)',
52    );
53
54=head1 DESCRIPTION
55
56This module allows you to search for MP3 files by their ID3 tags.
57You can ask for the results to be sorted by one or more of those
58tags, and return either the list of filenames (the deault), a
59C<printf>-style formatted string for each file using its ID3 tags,
60or the actual Perl data structure representing the results.
61
62There are currently two backends to this module: L<MP3::Find::Filesystem>
63and L<MP3::Find::DB>. You choose which one you want by passing its
64name as the argument to you C<use> statement; B<MP3::Find> will look for
65a B<MP3::Find::$BACKEND> module. If no backend name is given, it will
66default to using L<MP3::Find::Filesystem>.
67
68B<Note:> I'm still working out some kinks in the DB backend, so it
69is currently not as stable as the Filesystem backend.
70
71B<Note the second>: This whole project is still in the alpha stage, so
72I can make no guarentees that there won't be significant interface changes
73in the next few versions or so. Also, comments about what about the API
74rocks (or sucks!) are appreciated.
75
76=head1 REQUIRES
77
78L<File::Find>, L<MP3::Info>, and L<Scalar::Util> are needed for
79the filesystem backend (L<MP3::Find::Filesystem>). In addition,
80if L<MP3::Tag> is available, you can search by explicit ID3v2
81tag frames.
82
83L<DBI>, L<DBD::SQLite>, and L<SQL::Abstract> are needed for the
84database backend (L<MP3::Find::DB>).
85
86=head1 EXPORTS
87
88=head2 find_mp3s
89
90    my @results = find_mp3s(%options);
91
92Takes the following options:
93
94=over
95
96=item C<dir>
97
98Arrayref or scalar; tell C<find_mp3s> where to start the search.
99Directories in the arrayref are searched sequentially.
100
101=item C<query>
102
103Hashref of search parameters. Recognized fields are anything that
104L<MP3::Info> knows about. Field names can be given in either upper
105or lower case; C<find_mp3s> will convert them into upper case for
106you. Value may either be strings, which are converted into regular
107exporessions, or may be C<qr/.../> regular expressions already.
108
109=item C<ignore_case>
110
111Boolean, default false; set to a true value to ignore case when
112matching search strings to the ID3 tag values.
113
114=item C<exact_match>
115
116Boolean, default false; set to a true value to add an implicit
117C<^> and C<$> around each query string. Does nothing if the query
118term is already a regular expression.
119
120=item C<sort>
121
122What field or fields to sort the results by. Can either be a single
123scalar field name to sort by, or an arrayref of field names. Again,
124acceptable field names are anything that L<MP3::Info> knows about;
125field names will be converted to upper case as with the C<query>
126option.
127
128=item C<printf>
129
130By default, C<find_mp3s> just returns the list of filenames. The
131C<printf> option allows you to provide a formatting string to apply
132to the data for each file. The style is roughly similar to Perl's
133C<printf> format strings. The following formatting codes are
134recognized:
135
136    %a - artist
137    %t - title
138    %b - album
139    %n - track number
140    %y - year
141    %g - genre
142    %% - literal '%'
143
144Numeric modifers may be used in the same manner as with C<%s> in
145Perl's C<printf>.
146
147=item C<no_format>
148
149Boolean, default false; set to a true value to have C<find_mp3s> to
150return an array of hashrefs instead of an array of (formatted) strings.
151Each hashref consists of the key-value pairs from C<MP3::Info::get_mp3_tag>
152and C<MP3::Info::get_mp3_info>, plus the key C<FILENAME> (with the obvious
153value ;-)
154
155    @results = (
156        {
157            FILENAME => ...,
158            TITLE    => ...,
159            ARTIST   => ...,
160            ...
161            SECS     => ...,
162            BITRATE  => ...,
163            ...
164        },
165        ...
166    );
167
168=back
169
170=head1 BUGS
171
172There are probably some in there; let me know if you find any (patches
173welcome).
174
175=head1 TODO
176
177Better tests, using some actual sample mp3 files.
178
179Other backends (a caching filesystem backend, perhaps?)
180
181=head1 SEE ALSO
182
183L<MP3::Find::Filesystem>, L<MP3::Find::DB>
184
185L<mp3find> is the command line frontend to this module (it
186currently only uses the filesystem backend).
187
188L<mp3db> is a (currently rather barebones) command line
189frontend for creating and updating a SQLite database for
190use with L<MP3::Find::DB>.
191
192See L<MP3::Info> for more information about the fields you can
193search and sort on. See L<http://id3.org/> for information about
194ID3v2 tags.
195
196L<File::Find::Rule::MP3Info> is another way to search for MP3
197files based on their ID3 tags.
198
199=head1 AUTHOR
200
201Peter Eichman <peichman@cpan.org>
202
203=head1 COPYRIGHT AND LICENSE
204
205Copyright (c) 2006 by Peter Eichman. All rights reserved.
206
207This program is free software; you can redistribute it and/or
208modify it under the same terms as Perl itself.
209
210=cut
Note: See TracBrowser for help on using the repository browser.