NAME

MP3::Archive - Parse filenames in a music archive

SYNOPSIS

    use MP3::Archive qw(:all);
    my $archive=MP3::Archive->new([$config]);

    if($archive->validate($file)) { ... }
    if($archive->isalbum($file))  { ... }
    if($archive->istrack($file))  { ... }
    print("File: $file",
          "\nTracknum: ",  $archive->tracknum($file),
          "\nArtist: ",    $archive->artist($file),
          "\nDirartist: ", $archive->dirartist($file),
          "\nAlbum: ",     $archive->album($file),
          "\nDiralbum: ",  $archive->diralbum($file),
          "\nTrack: ",     $archive->track($file),
          "\nExtension",   $archive->ext($file),"\n");
    print("Correct path: ",
          $archive->makepathname($fromfile,$artist,$album,$GUESS),"/",
          $archive->makefilename($fromfile,$tracknum,$artist,$album,$track,$ext),"\n");
    my $delim=$archive->delim($file,$ALBUM);
    my $fileformat=$archive->getfileformat($file);
    my $dirformat=$archive->getdirformat($file);
    my $m3uformat=$archive->getm3uformat($file);

DESCRIPTION

MP3::Archive is a module to encapsulate the parsing and creation of filenames containing music metadata (artist, album, etc).

For instance, with the default setup, it would be able to parse the metadata out of the pathname:

music/albums/Beck/Mutations/01 - Beck - Mutations - Cold Brains.mp3

It uses formats to describe the allowed filename patterns, defined in the config files /etc/mp3archiverc and $HOME/.mp3archiverc, and/or application-specific config files.

See MP3::Archive::Config(3) for details.

PUBLIC METHODS

Many of these methods take the optional argument $tracktype. This specifies whether to treat the track as an album track, non album track, or try to guess it from the pathname of $file. If $tracktype is not supplied, it defaults to guessing the track type.

Possible values for $tracktype are $ALBUM, $TRACK, $GUESS. These constants are all defined in MP3::Archive. They can be accessed either as eg $MP3::Archive::ALBUM or exported either individually or all together with:

"use MP3::Archive ':all';"

new

Creates an instance of MP3::Archive

Takes one optional argument, a reference to a "MP3::Archive::Config" object. If this is not supplied, a default Config instance is created.

This enables you to pass a subclass of "MP3::Archive::Config" to allow for your own applications configuration. See mp3lint(1) for an example.

tracknum($file[,$tracktype)

Parses and returns the track number from a file. If called in list context, also returns the offset of the tracknumber in $file.

artist($file[,$tracktype])

Parses and returns the artist name from a file. If called in list context, also returns the offset of the artist in $file.

dirartist($file[,$tracktype])

Parses and returns the artist name from the pathname to a file (not the filename itself).

album($file[,$tracktype])

Parses and returns the album name from a file. If called in list context, also returns the offset of the album in $file.

diralbum($file[,$tracktype])

Parses and returns the album name from the pathname to a file (not the filename itself).

track($file[,$tracktype])

Parses and returns the track name (song title) from $file. If called in list context, also returns the offset of the track name in $file.

ext($file[,$tracktype])

Returns extension of $file.

validate($file[,$tracktype])

Returns 1 if the filename of $file successfully matches one of its acceptable formats.

Also returns 1 if the file/path has no defined formats to test against.

isalbum($file)

Returns 1 if $file is an album track, 0 otherwise. Does not use $format_default.

istrack($file)

Returns 1 if $file is a non-album track, 0 otherwise. Does not use $format_default.

format

Returns a reference to the associated "MP3::Archive::Format" object;

config

Returns a reference to the associated "MP3::Archive::Config" object;

getfileformat($file[,$tracktype])

Returns the format appropriate for a file of this type and location.

getdirformat($file[,$tracktype])

Returns the format for the directory portion of a file of this type and location.

getm3uformat($file[,$tracktype])

Returns the format for a playlist (m3u) file in the specified location.

makefilename($file,$tracknum,$artist,$album,$track,$ext[,$tracktype])

Returns a correctly formatted filename with the fields filled in.

makepathname($fromfile,$artist,$album[,$tracktype])

Returns the pathname (without filename) that $fromfile belongs in.

delim($file[,$tracktype])

Returns the correct field delimiter for this type of file.

INTERNAL METHODS

filepart($file)

Returns the filename with the path stripped off. Can be called as a static method.

getformat($file,$type[,$tracktype])

Returns the appropriate format for the specified file and type.

Accepted types are "file", "dir", and "m3u".

This is a helper method for the above get.*format methods.

arraymatch($file,$array)

Canonicalises $file path, then does a regexp match on each element of $array. Returns 1 if match, else 0

BUGS

Formats may not be general enough, I would be interested in feedback from people with other file naming conventions.

AUTHOR

Ian Beckwith <ianb@nessie.mcc.ac.uk>

AVAILABILITY

The latest version can be found at:

 B<http://nessie.mcc.ac.uk/~ianb/projects/libmp3-archive-perl/>

COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This module is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.