GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
MP3::Find(3) User Contributed Perl Documentation MP3::Find(3)

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

    # 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,
        exact_match => 1,
        sort => [qw(year album tracknum)],
        printf => '%2n. %a - %t (%b: %y)',
    );

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 "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: MP3::Find::Filesystem and MP3::Find::DB. You choose which one you want by passing its name as the argument to you "use" statement; MP3::Find will look for a MP3::Find::$BACKEND module. If no backend name is given, it will default to using MP3::Find::Filesystem.

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

Note the second: This whole project is still in the alpha stage, so I can make no guarentees that there won't be significant interface changes in the next few versions or so. Also, comments about what about the API rocks (or sucks!) are appreciated.

File::Find, MP3::Info, and Scalar::Util are needed for the filesystem backend (MP3::Find::Filesystem). In addition, if MP3::Tag is available, you can search by explicit ID3v2 tag frames.

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

    my @results = find_mp3s(%options);

Takes the following options:

"dir"
Arrayref or scalar; tell "find_mp3s" where to start the search. Directories in the arrayref are searched sequentially.
"query"
Hashref of search parameters. Recognized fields are anything that MP3::Info knows about. Field names can be given in either upper or lower case; "find_mp3s" will convert them into upper case for you. Value may either be strings, which are converted into regular exporessions, or may be "qr/.../" regular expressions already.
"ignore_case"
Boolean, default false; set to a true value to ignore case when matching search strings to the ID3 tag values.
"exact_match"
Boolean, default false; set to a true value to add an implicit "^" and "$" around each query string. Does nothing if the query term is already a regular expression.
"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 MP3::Info knows about; field names will be converted to upper case as with the "query" option.
"printf"
By default, "find_mp3s" just returns the list of filenames. The "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 "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 %s in Perl's "printf".

"no_format"
Boolean, default false; set to a true value to have "find_mp3s" to return an array of hashrefs instead of an array of (formatted) strings. Each hashref consists of the key-value pairs from "MP3::Info::get_mp3_tag" and "MP3::Info::get_mp3_info", plus the key "FILENAME" (with the obvious value ;-)

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

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

Better tests, using some actual sample mp3 files.

Other backends (a caching filesystem backend, perhaps?)

MP3::Find::Filesystem, MP3::Find::DB

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

mp3db is a (currently rather barebones) command line frontend for creating and updating a SQLite database for use with MP3::Find::DB.

See MP3::Info for more information about the fields you can search and sort on. See <http://id3.org/> for information about ID3v2 tags.

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

Peter Eichman <peichman@cpan.org>

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.

2011-06-08 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.