- Timestamp:
- 01/30/06 01:03:14 (19 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/lib/MP3/Find/Base.pm
r1 r2 21 21 my $invocant = shift; 22 22 my $class = ref $invocant || $invocant; 23 my $self = {}; 23 my %options = @_; 24 my $self = \%options; 24 25 bless $self, $class; 25 26 } … … 40 41 (); 41 42 42 43 43 foreach (keys %QUERY) { 44 44 # so we don't have spurious warnings when trying to match against undef 45 45 delete $QUERY{$_} unless defined $QUERY{$_}; 46 # package everything uni oformly, so subclasses don't need to unpack46 # package everything uniformly, so subclasses don't need to unpack it 47 47 $QUERY{$_} = [ $QUERY{$_} ] unless ref $QUERY{$_} eq 'ARRAY'; 48 48 } … … 90 90 =head1 NAME 91 91 92 MP3::Find - Search and sort MP3 files based on their ID3 tags92 MP3::Find::Base - Base class for MP3::Find finders 93 93 94 94 =head1 SYNOPSIS 95 95 96 use MP3Find; 97 98 print "$_\n" foreach find_mp3s( 99 dir => '/home/peter/cds', 100 query => { 101 artist => 'ilyaimy', 102 title => 'deep in the am', 103 }, 104 ignore_case => 1, 105 match_words => 1, 106 sort => [qw(year album tracknum)], 107 printf => '%2n. %a - %t (%b: %y)', 108 ); 96 package MyFinder; 97 use base 'MP3::Find::Base'; 98 99 sub search { 100 my $self = shift; 101 my ($query, $dirs, $sort, $options) = @_; 102 103 # do something to find and sort the mp3s... 104 my @results = do_something(...); 105 106 return @results; 107 } 108 109 package main; 110 my $finder = MyFinder->new; 111 112 # see MP3::Find for details about %options 113 print "$_\n" foreach $finder->find_mp3s(\%options); 109 114 110 115 =head1 DESCRIPTION 111 116 112 This module allows you to search for MP3 files by their ID3 tags. 113 You can ask for the results to be sorted by one or more of those 114 tags, and return either the list of filenames (the deault), a 115 C<printf>-style formatted string for each file using its ID3 tags, 116 or the actual Perl data structure representing the results. 117 118 =head1 REQUIRES 119 120 L<File::Find>, L<MP3::Info>, L<Scalar::Util> 121 122 L<DBI> and L<DBD::SQLite> are needed if you want to have a 123 database backend. 124 125 =head1 EXPORTS 117 This is the base class for the classes that actually do the 118 searching and sorting for L<MP3::Find>. 119 120 =head1 METHODS 121 122 =head2 new 123 124 Really simple constructor. If you pass it a hash of options, it 125 will hang on to them for you. 126 127 =head2 search 128 129 This is the one you should override in your subclass. If you 130 don't, the base class C<search> method will croak. 131 132 The C<search> method is called by the C<find_mp3s> method with 133 the following arguments: the finder object, a hashref of query 134 parameters, an arrayref of directories to search, and a hashref 135 of miscellaneous options. 136 137 The search method should return a list of hashrefs representing 138 the results of the search. Each hashref should have the following 139 keys (all except C<FILENAME> are derived from the keys returned 140 by the C<get_mp3tag> and C<get_mp3Info> functions from L<MP3::Info>): 141 142 FILENAME 143 144 TITLE 145 ARTIST 146 ALBUM 147 YEAR 148 COMMENT 149 GENRE 150 TRACKNUM 151 152 VERSION -- MPEG audio version (1, 2, 2.5) 153 LAYER -- MPEG layer description (1, 2, 3) 154 STEREO -- boolean for audio is in stereo 155 156 VBR -- boolean for variable bitrate 157 BITRATE -- bitrate in kbps (average for VBR files) 158 FREQUENCY -- frequency in kHz 159 SIZE -- bytes in audio stream 160 OFFSET -- bytes offset that stream begins 161 162 SECS -- total seconds 163 MM -- minutes 164 SS -- leftover seconds 165 MS -- leftover milliseconds 166 TIME -- time in MM:SS 167 168 COPYRIGHT -- boolean for audio is copyrighted 169 PADDING -- boolean for MP3 frames are padded 170 MODE -- channel mode (0 = stereo, 1 = joint stereo, 171 -- 2 = dual channel, 3 = single channel) 172 FRAMES -- approximate number of frames 173 FRAME_LENGTH -- approximate length of a frame 174 VBR_SCALE -- VBR scale from VBR header 175 126 176 127 177 =head2 find_mp3s 128 178 129 my @results = find_mp3s(%options); 130 131 Takes the following options: 132 133 =over 134 135 =item C<dir> 136 137 Where to start the search. This can either be a single string or 138 an arrayref. Defaults to your home directory. 139 140 =item C<query> 141 142 Hashref of search parameters. Recognized fields are anything that 143 L<MP3::Info> knows about. Field names can be given in either upper 144 or lower case; C<find_mp3s> will convert them into upper case for 145 you. Value may either be strings, which are converted into regular 146 exporessions, or may be C<qr[...]> regular expressions already. 147 148 =item C<ignore_case> 149 150 Ignore case when matching search strings to the ID3 tag values. 151 152 =item C<exact_match> 153 154 Adds an implicit C<^> and C<$> around each query string. 155 156 =item C<sort> 157 158 What field or fields to sort the results by. Can either be a single 159 scalar field name to sort by, or an arrayref of field names. Again, 160 acceptable field names are anything that L<MP3::Info> knows about. 161 162 =item C<printf> 163 164 By default, C<find_mp3s> just returns the list of filenames. The 165 C<printf> option allows you to provide a formatting string to apply 166 to the data for each file. The style is roughly similar to Perl's 167 C<printf> format strings. The following formatting codes are 168 recognized: 169 170 %a - artist 171 %t - title 172 %b - album 173 %n - track number 174 %y - year 175 %g - genre 176 %% - literal '%' 177 178 Numeric modifers may be used in the same manner as with C<%s> in 179 Perl's C<printf>. 180 181 =item C<no_format> 182 183 Causes C<find_mp3s> to return an array of hashrefs instead of an array 184 of (formatted) strings. Each hashref consists of the key-value pairs 185 from C<MP3::Info::get_mp3_tag> and C<MP3::Info::get_mp3_info>, plus 186 the key C<FILENAME> (with the obvious value ;-) 187 188 @results = ( 189 { 190 FILENAME => ..., 191 TITLE => ..., 192 ARTIST => ..., 193 ... 194 SECS => ..., 195 BITRATE => ..., 196 ... 197 }, 198 ... 199 ); 200 201 =back 179 The method that should be called by the program doing the searching. 180 181 See L<MP3::Find> for an explanation of the options that can be passed 182 to C<find_mp3s>. 202 183 203 184 =head1 TODO 204 185 205 More of a structured query would be nice; currently everything 206 is and-ed together, and it would be nice to be able to put query 207 keys together with a mixture of and and or. 208 209 Searching a big directory is slo-o-ow! Investigate some sort of 210 caching of results? 211 212 The current sorting function is also probably quite inefficient. 186 More format codes? Possibly look into using L<String::Format> 213 187 214 188 =head1 SEE ALSO 189 190 L<MP3::Find>, L<MP3::Find::Filesystem>, L<MP3::Find::DB> 215 191 216 192 See L<MP3::Info> for more information about the fields you can 217 193 search and sort on. 218 194 219 L<File::Find::Rule::MP3Info> is another way to search for MP3220 files based on their ID3 tags.221 222 195 =head1 AUTHOR 223 196
Note: See TracChangeset
for help on using the changeset viewer.