Quick Navigator

Search Site

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

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  MP3::ARCHIVE::CONFIG (3)

.ds Aq ’


MP3::Archive::Config - Configuration handling for MP3::Archive



    my $conf=MP3::Archive::Config->new([\%newopts]);
    my $opts=$conf->parseconfig($conf->readconfigfile($file);
    my $value=$conf->get("conf_var_name");


MP3::Archive::Config handles the configuration for MP3::Archive. By default, it uses /etc/mp3archiverc and ~/.mp3archiverc (or <B>B>$ENV<B>{MP3ARCHIVERC}B> if defined) for configuration (as well as reasonable defaults), but it can optionally use application-specific config files as well as or instead of the defaults.

The config file format is a fragment of perl which sets the configuration variables.

The user configuration file is automatically created the first time <B>newB> is called. See new in METHODS for details.


What files are consulted depends on the options passed to <B>newB>. See new in METHODS for more details. The order is as follows:
1 Internal defaults are set.
2 Unless $apprconly is set in new(), the default config files are loaded:
2.1 /etc/mp3archiverc is loaded.
2.2 If $ENV{MP3ARCHIVERC} is defined and exists, it is loaded.
2.3 Else, ~/.mp3archiverc is loaded.
3 If $sysrc is set in new() it is loaded.
4 If $rcenv is set in new(), and $ENV{$rcenv} is defined and exists, it is loaded.
5 Else, if $rcfile is set in new() it is loaded.
If you use mp3lint(1), and want to share the configuration, then either create .mp3archiverc as a symbolic link to .mp3lintrc, with:

<B> ~$ ln -sf ~/.mp3lintrc ~/.mp3archivercB>

or change .mp3archiverc so it just says:

<B>require $ENV{HOME}/.mp3lintrc;B>

which will effectively include .mp3lintrc into .mp3archiverc. For this to work, the last line of .mp3lintrc should be 1;, or at least evaluate to true


Formats are used to specify valid filenames and to specify where the artistname, albumname, etc are located.

Formats are regular expressions (see perlretut(1) and perlre(1)), but with <B>ARTISTB>, <B>ALBUMB>, <B>TRACKB>, <B>TRKNUMB> and <B>EXTB> as placeholders for the artist, album, track name (song title), track number and extension respectively.

There are two types of formats.

Variables beginning with $formats_ are lists of permissible formats for parsing a filename, each of which are regular expressions (see perlretut(1) and perlre(1) for details). The formats are references to arrays, which essentially means you can have as many as you want, separated by commas, and they must start and end with <B>[B> and <B>]B> respectively. The individual formats should be quoted with single quotes (<B>’B>).

Variables beginning with $format_ are single formats that are ordinary strings, not regular expressions, and are used when creating filenames. They don’t have <B>[B> and <B>]B> round them, but still should be quoted with single quotes (<B>’B>), and there should be only one of them, not a list.


These are from the default setup.

$formats_album=[TRKNUM - ARTIST - ALBUM - TRACK\.EXT,
                         ARTIST - ALBUM - TRKNUM - TRACK\.EXT];

This defines two acceptable formats for album tracks. The first one would match eg:

01 - Talk Talk - Spirit Of Eden - The Rainbow.mp3

and the second one would match eg:

DJ Shadow - Endtroducing - 07 - Stem-Long Stem.mp3

$formats_track=[ARTIST - TRACK\.EXT];

This defines one acceptable format for non-album tracks. This would match eg:

Radiohead - Paranoid Android (Live at the 10 Spot).ogg

$format_write_album=TRKNUM - ARTIST - ALBUM - TRACK.EXT;

This can be though of as the reverse of $formats_album. It defines the format to be used when creating a file, so in this example, given TRKNUM 02, ARTIST Dead Can Dance, ALBUM Aion, TRACK Saltarello, and EXT wav, it would produce the filename:

 02 - Dead Can Dance - Aion - Saltarello.wav


<B>B>$formats_album<B>B> This specifies acceptable formats for album tracks.



See above for details.

<B>B>$formats_track<B>B> This specifies acceptable formats for non-album tracks.


$formats_track=[ARTIST - TRACK\.EXT];

See above for details.

<B>B>$formats_album_dir<B>B> This specifies how to extract info from the directory of an album track.


$formats_album_dir= [ARTIST - ALBUM$,ARTIST\/ALBUM$];

This would match

<B>/Spiritualised - Lazer Guided Melodies/B>


<B>/Spiritualised/Pure Phase/B>

both at the end of the pathname.

<B>B>$formats_track_dir<B>B> This specifies how to extract info from the directory of a non-album track.


$formats_track_dir= [ARTIST$];

This specifies the last portion of the pathname is the artist.

<B>B>$formats_album_m3u<B>B>, <B>B>$formats_track_m3u<B>B> Specifies the format of m3u playlist filenames for album and non-album tracks.


$formats_album_m3u= [ARTIST - ALBUM\.EXT];

$formats_track_m3u = [ARTIST\.EXT];

<B>B>$format_default<B>B> How to treat tracks that are not in $paths_album or $paths_track. This can be <B>albumB>, <B>trackB>, or anything else, which means don’t test the files at all (eg <B>skipB>).



<B>B>$format_delimiter_album<B>B>, <B>B>$format_delimiter_track<B>B> These specify the delimiters for album and non-album tracks. This allows extra checks, eg to make sure there are the right number of fields (eg, if the delimiter is ‘-’ and you have a track named Stem - Long Stem, so the file is called

07 - DJ Shadow - Entroducing - Stem - Long Stem.mp3

then the extra dash will cause you problems, but specifying a delimiter will allow mp3lint to determine there are too many fields.


$format_delimiter_album= - ;

$format_delimiter_track= - ;

<B>B>$paths_album<B>B>, <B>B>$paths_track<B>B> These are used to determine from its pathname whether a file should be treated as part of an album. They are regular expressions, so the same warnings about quoting apply as to formats. This also means that they are substring matches, so the defaults below match any pathname that contains a component called <B>albumsB> or <B>tracksB>. Although there is only one path each in the default, they can be lists of multiple paths (or portions of paths) to match.




This means that any pathname containing /albums or /tracks will be treated accordingly (eg /music/groovy-albums/).

<B>B>$archive_root<B>B> $archive_root is currently only used to define the $path_write_* variables (below), but its use may be expanded in the future.



On any sane unix system, $ENV{HOME} expands to your home directory.

<B>B>$path_write_album<B>B>, <B>B>$path_write_track<B>B> $path_write_album and $path_write_track are used to determine the canonical pathname for files, for tools like movemusic(1).

The defaults are defined relative to $archive_root (see above).


$path_write_album="$archive_root/cut/albums/"; $path_write_track="$archive_root/tracks/";

<B>B>$format_write_album<B>B>, <B>B>$format_write_track<B>B>, <B>B>$format_write_album_m3u<B>B>, <B>B>$format_write_track_m3u<B>B>, <B>B>$format_write_album_dir<B>B>, <B>B>$format_write_track_dir<B>B>, These variables are analogous to the $formats_* variables above, but they are used for constructing filenames rather than parsing them to extract information. They are not regular expressions, they are ordinary strings, and there is only one of each rather than a list (array). The same magic variables (TRKNUM, ARTIST, ALBUM, TRACK) are used and are replaced with the actual data.


$format_write_album=TRKNUM - ARTIST - ALBUM - TRACK.EXT;

$format_write_track=ARTIST - TRACK.EXT;

$format_write_album_m3u=ARTIST - ALBUM.EXT;






Creates an instance of MP3::Archive::Config

Takes an optional reference to a hash of options:
defaults A scalar containing perl code for additional default options.
rcfile An additional application-specific and user-specific config file.
rcenv The name of an environment variable, which, if defined and exists, is used instead of rcfile.
sysrc An additional system-wide (ie in /etc or /usr/local/etc) application-specific config file.
apprconly If non-zero, skips /etc/mp3archiverc and $HOME/.mp3archiverc, and just uses the application-specific config files defined above.
If it doesn’t exist, the user config file is created, containing the defaults. This file is either $ENV{$rcenv}, $rcfile, or ~/.mp3archiverc, depending what is defined.


Sets options. Takes a hashref of options to set. Preserves any options not mentioned.


Returns the value of the configuration variable $item, or undef if it is not defined.


Reads in $file and returns it as one long string. Returns undef on failure.

Can be called as a static method (eg $conf=MP3::Archive::Config::readconfigfile($file)).


Parses the perl code in $code and returns a reference to a hash containing the variables defined therein.

If there is a problem with the perl in $code, it sets $self->{parseerror} to the error message, and returns undef.

parseconfig works by eval-ing the perl code within the context of a package with an empty symbol table, then reading the contents of that symbol table.


Writes the config data $config to $file.

$config is expected to be a string of perl code.

Can be called as a static method (eg MP3::Archive::Config::writeconfigfile($file,$config)).


<B>B>$MP3ARCHIVERC<B>B> If set, uses this instead of $HOME/.mp3archiverc
<B>B>$HOME<B>B> Used to find .mp3archiverc


None known. Please report any found to

I am especially interested in how well the code for filename formats works for other people’s filenames.


MP3::Archive(3), MP3::Archive::Format(3), mp3lint(1), mp3-archive-tools(1)


Ian Beckwith <>
Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 MP3::ARCHIVE::CONFIG (3) 2003-12-06

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