find_mp3s

    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  => ...,
            ...
        },
        ...
    );