NAME
arename - automatically rename audio files by tagging information
SYNOPSIS
arename [OPTION(s)] FILE(s)...
OPTIONS AND ARGUMENTS
--compare-versions
Prints the version of the arename script and the version of the
Perl module, that contains most of the code. These versions
should be the same. If not, that would indicate a possibly
broken installation.
--copy (short option: -c)
Copy files instead of renaming (moving). This can be useful to
copy tracks from your audio archive to a portable device for
example.
--debug (short option: -D)
Enable debugging output. This is likely to be very noisy. You
probably want to use the --verbose option (setting: verbose) in
addition to this.
--disable-hooks (short option: -H)
Do not make use of hooks of any sort (neither global nor local
ones).
--disable-profiles (short option: -N)
Do not use configuration profiles (see below). Overwrites the
useprofiles setting.
--dryrun (short option: -d)
Go into dryrun mode. This means, that no action will be taken.
arename will print what it would do, if called without -d.
--enable-hooks
Explicitly enable hooks.
--force (short option: -f)
Overwrite files if needed.
--help (short option: -h)
Display a short help text.
--list-cfg (short option: -L)
List the current configuration in the actual configuration
format.
--list-profiles (short option: -S)
Print a list of profile names defined in the active
configuration. (This is primarily used by the zsh completion
for the --profile option.)
--quiet (short option: -q)
Make the output way more quiet, when processing files.
This option conflicts with the verbose option.
--read-local (short option: -l)
Read a local config file (./.arename.local). Overwrites the
uselocalrc configuration setting.
--stdin (short option: -s)
Read filenames from stdin after processing files given on the
command line. It reads one file name per line, which means
that file names containing newlines are not supported.
--uber-quiet (short option: -Q)
Be even more quiet (this option will suppress, if a file is
skipped. Except for files, that are skipped because they would
overwrite something).
This option implies --quiet.
--version (short option: -V)
Display version information.
--verbose (short option: -v)
Enable verbose output.
--rc <file>
Read file instead of ~/.arenamerc.
--post-rc <file>
Read file after ~/.arenamerc and before ./.arename.local.
--prefix <prefix> (short option: -p)
Define a prefix for destination files.
--profile <profile(s),...> (short option: -P)
Define a list of one or more profiles to use forcibly, no
matter if they would be activated normally or not.
--compilation-template <template> (short option: -T)
Define a template, that will be used for files that contain a
compilation tag.
--template <template> (short option: -t)
Define a generic template (for all files that do not contain a
compilation tag).
--userset <variable=value> (short option: -u)
Set a user defined variable to a given value (see "User defined
variables" below).
FILE(s)...
Input files, that are subject for renaming.
A word about option name stability: With arename version 3.0 we are now
using Getopt::Long for parsing command lines options. That change was
made, because the meaningful single letter options where used up. Every
option is available via a --long-option. That interface will remain
stable. So, if you want to use arename in scripts, those are the
options you should use. There are currently no plans of removing or
changing any further short options, but there are no guarantees. If it
is indeed better to change a short option, we will do so.
A list of options that changed from arename 2.x to 3.0 can be found in
the project’s CHANGES file.
DESCRIPTION
arename is a tool that is able to rename audio files by looking at a
file’s tagging information. It uses this information to assemble a
consistent destination file name. The user can define the format of the
destination filename by the use of template strings.
Templates can be defined in the "Configuration files", by the template
and comp_template settings (See "SETTINGS" below).
By default, arename will refuse to overwrite destination files, if the
file in question already exists. You can force overwriting by supplying
the --force option.
In order to see what would happen instead of actually modifying files,
you can use the --dryrun option. This way you can avoid problems, that
would occur if the situation (e.g. the information in the files or your
configuration) is not exactly as you expected it.
Supported file formats
arename currently supports three widely used audio formats, namely MPEG
Layer3, ogg vorbis and flac (Free Lossless Audio Codec). The format,
that arename will assume for each input file is determined by the
file’s filename-extension (.mp3 vs. .ogg vs. .flac). The extension
check is case-insensitive.
.mp3 files may contain different types of tags, namely id3v1 and id3v2.
Id3v1 is a very limited format. Therefore arename will use the id3v2
tag when it finds it. Which means you should make sure that the id3v2
tag has all the information you need, if you use files with both id3v1
and id3v2 tags.
Inputting a *lot* of files
arename can be used to keep the file names of whole audio archives in
sync. However, that means that you will have to tell the script the
location of many files, thousands maybe.
In order to do that you will face the problem, that on most UNIX-like
systems, the length of the argument list for external programs is
limited (recent Linux versions, as an exception, do not have that
limitation anymore).
So, even if your shell can do recursive globbing like ksh or zsh, this
will most likely get you into trouble (for more than just a few files):
% arename -d **/*.mp3
There are several ways to overcome that limitation, of course.
The first solution is to use find in connection with arename’s -s
option:
% find . -name "*.mp3" -print | arename -d -s
This will break for file names that contain newlines, because --stdin
will read one file name per line from the standard input stream.
Another way of using find to deal with this problem is to use find’s
-exec option:
% find . -name "*.mp3" -exec arename -d '{}' '+'
This will work for every possible file name. No matter if it has spaces
or newlines in it. The + at the end of the call causes find to call the
external program (arename in this case) with as many arguments as
possible, without exceeding the limit. This requires a POSIXly correct
find. GNU find for instance, did not support the + way for a long time.
If you are stuck with an old version, you can exchange the + with a ;
(note, that a semicolon must be quoted in any case), or use GNU’s xargs
tool instead.
A last solution for zsh users would be zargs (which requires ’autoload
zargs’ in your zsh configuration):
% zargs -- **/*.mp3 -- arename -d
GENERAL USAGE
When you are first confronted with arename and you try to get started
with the documentation you might argue, that a 1000+ lines manual, that
is not filled with too many examples is hardly starter-friendly.
Therefore, this section was introduced to give you the bare minimum of
information in order to use the program without going through too much
fuzz.
If you are really afraid of documentation, you could of course just
read the output of the --help option and see which options to provide
in order to get what you want. Then again, you will soon be pissed by
the weird default values arename uses.
You will probably want other templates. After all, the ability to have
these expanded strings is one of the points to use arename in the first
place. They are described in the TEMPLATE section; and reading that
section is the minimum effort you will want to go through.
After that, you can open the file ~/.arenamerc in your favourite text
editor and resemble the following text (and presumably change the few
values in there to your liking):
# as soon as you get pissed by too much output, while arename is
# running, uncomment the following line:
#quiet
# now you certainly want your own templates, so define them here
# one for your normal files
template &artist - &album - &tracknumber. &tracktitle
# and another one for files that orignate from compilations
comp_template va - &album - &tracknumber. &artist - &tracktitle
If you want more automation or more customization, you will not get
around reading the manual below. If you need to solve special problems,
the "HOOKS" part even further below is for you.
ENVIRONMENT VARIABLES
ARENAME_LOAD_QUIET
When set to 1, arename will not output any startup messages;
not while reading the configuration or hook files, nor will
arename emit messages about whether it is in copy mode or on a
dry-run or similar.
However, if warnings or errors are encoutered while loading the
configuration, those messages are still emitted, of course.
Any other value but 1 - and that includes ARENAME_LOAD_QUIET
being absent from the environment - will cause arename to start
up in its normal manner.
FILES
arename’s behaviour can be altered by a number of files it reads when
starting up.
Normal configuration tasks are done in (how convenient) "Configuration
files", described below.
If you need more control, or want to solve special problems you are
having, you can do so by supplying Perl code in "Hook definition
files".
arename can be configured to read configuration files as well as hook
definition files from the current working directory. This feature is
disabled by default, because they can be a security issue on multiuser
systems.
There are no such things as system wide configuration files in arename.
For all setup files arename tries to find (except for the local ones)
four different locations are tried. If the $XDG_CONFIG_HOME/arename
directory exists, all files are expected to be there. If that directory
does not exist, ~/etc/arename/ and if that is not there ~/.arename are
are tried instead. If those directories could not be found either,
arename will try to find the file it is looking for directly in the
user’s home directory.
The default for $XDG_CONFIG_HOME is ~/.config.
The first setup directory we find always wins. arename does not
consider more than one setup directory.
If, for example, ~/etc/arename/ exists and we are looking for the
normal configuration file (see below), but ~/etc/arename/rc could not
be found, we do not try to find it in ~/.arename/ or the user’s home
directory.
Configuration files
arename uses up to three configuration files. As for most programs, the
script will try to read a configuration file, that is located in the
user’s home directory. In addition to that, it will try to load local
configuration files, if it finds appropriately named files in the
current directory (and the uselocalrc feature is enabled):
$XDG_CONFIG_HOME/arename/rc
~/etc/arename/rc
~/.arename/rc
~/.arenamerc
per-user normal configuration file.
./.arename.local
per-directory local configuration file (only read if uselocalrc
is set or the --read-local option is given on the command
line).
The per-user normal configuration file can be substituted by another
file, if specified via the --rc option.
Last but not least, you can specify an intermediate configuration file,
that is read in between the normal and the per-directory file, via the
--post-rc option.
File format
The format of the aforementioned files is pretty simple. It is parsed
line by line. Empty lines, lines only containing whitespace and lines,
whose first non whitespace character is a hash character (#) are
ignored.
There are two different types of settings: boolean and scalar settings.
Booleans can be set like this:
<setting> [true|false]
If the value is omitted, true is assumed. true and false are recognized
case insensitively, and a value of 1 is synonymous to true, as is 0 to
false.
Scalar settings are done in a very similar way:
<setting> <value>
If the value is omitted, string values will be set to an empty string
and numeric values will be set to zero.
In both cases, setting and value are separated by one or more
whitespace characters. The value will be the rest of the line (all of
it, including trailing whitespace).
If the value part starts with a backslash, that backslash is left out
of the value. That makes it possible to define templates with leading
whitespace.
If a line contains only a string within square brackets, that string is
the start of a section. Section names are matches for starts of file
names. That means, the settings following such a section definition
will only applied for input file names that start with the same string
as the section name. Where file name means the string, handed over to
arename. The string ~/ at the beginning of a section name is expanded
to the user’s home directory.
You may start as many sections as you would like.
A section named /foo/bar/ supersedes a section named /foo/ for a file
named /foo/bar/baz.ogg. So, the longest match wins.
Another possible configuration file entry is a user variable, which is
defined via the set command. These settings are very different from the
normal settings. Therefore, they are defined in a different way. That
way is described in the "User defined variables" subsection below.
Last but not least, you may define so called profiles, see below.
Configuration profiles
Profiles are a very flexible and context sensitive way of using
multiple configuration files at once. With profiles, local
configuration files (and local hook definition files) can be
substituted in a secure way; even on multi-user systems.
Reading local files (configs and hook-files) is still supported for
backwards compatibility (see uselocalrc and uselocalhooks options).
However, you are strongly encouraged to use profiles whenever you can.
As normal configuration files and global hook-files, profile-related
files are searched in one of the setup directories described above.
They are using the following naming conventions:
$XDG_CONFIG_HOME/arename/profile.PROFILENAME
~/etc/arename/profile.PROFILENAME
~/.arename/profile.PROFILENAME
~/.arename.PROFILENAME
Profile related configuration files; read if PROFILENAME is
active.
They are read after a intermediate config file defined by
--post-rc and a local config file (if enabled).
$XDG_CONFIG_HOME/arename/profile.PROFILENAME.hooks
~/etc/arename/profile.PROFILENAME.hooks
~/.arename/profile.PROFILENAME.hooks
~/.arename.PROFILENAME.hooks
Profile related "Hook definition files" (see below for
details); read if PROFILENAME is active.
These files are read, between global and local hook-definition
files.
In order to define profiles, you need to use the profile keyword:
profile <name> <pattern>
Where name is a string, that is used in the place of PROFILENAME in the
file location lists above. This name may contain of the following
character range: a-zA-Z0-9_-
pattern is part of a Perl regex pattern (see perlreref and perlretut
manpages). The pattern will be anchored at the beginning and is open at
the end, somewhat like this pseudocode:
if ($working_directory =~ m/^PATTERN/) { use_this_profile(); }
Example:
profile music /mnt/audio/music/
Will cause the profile music to be active when the working directory is
/mnt/audio/music/ or below. So, do not be afraid. You can use profiles
without understanding regular expressions.
Like many other values in arename’s configuration, a leading backslash
of a pattern will be ignored to allow patterns, that start in white
spaces. Furthermore, if a pattern starts in ~/, that string is
replaced by the user’s home directory.
You may add as many patterns to a profile name, as you want:
profile music /mnt/audio/music/
profile music /mnt/extern/audio/music/
The above activates the music profile in /mnt/audio/music/ and
/mnt/extern/audio/music/, for example.
More than one profile can be activated at the same time. If that is
true, the according configuration files are read in lexical order.
Sections versus Profiles
Since arename provides two context sensitive configuration facilities,
you might ask yourself when to use which, when you are confronted with
both for the first time.
First of all, profiles are more powerful. They may even introduce new
hooks for arename to use. But that is not the conceptual difference
between the two.
sections are sets of configuration settings, that are considered for
each and every input file and they are only enabled for input files,
whose name matches the section name.
profiles on the other hand are sets of configuration and hook-
definition files, whose inclusion in the current arename run is decided
at the beginning of the program’s execution (not for every input file)
- namely, if the name of the current working directory matches one of
the profile’s patterns.
That means, that if you need to introduce slight configuration changes
based on an input file’s name you want to use a section.
If you need to make broader configuration changes, considering the name
of the current working directory, profiles are the way to go.
Of course, profile configuration files may introduce new sections, too.
Configuration file example
# switch on verbosity
verbose
# canonicalize file names before working with them
canonicalize
# the author is crazy! use a sane template by default. :-)
template &artist - &album (&year) - &tracknumber. &tracktitle
# activate the 'music' profile below /mnt/audio/music/.
profile music /mnt/audio/music/
# force files from /foo/bar/ to stay below that directory
[/foo/bar/]
prefix /foo/bar
Hook definition files
$XDG_CONFIG_HOME/arename/hooks
~/etc/arename/hooks
~/.arename/hooks
~/.arename.hooks
Defines global hooks, that are in effect in every directory if the
usehooks option is set to true.
./.arename.hooks.local
This allows you to define special hooks, that will only be applied
for processes that run in the directory the local file is found
(and if the uselocalhooks option is set to true).
For details about hooks in arename, see "HOOKS" below.
SETTINGS
The following settings are supported in all configuration files.
Not all of them are usable in sections. The ones you can use in
sections are: All default_* options, force, prefix, sepreplace, tnpad,
comp_template and template.
canonicalize
If set, a given file name will be transformed to its cleaned up
absolute path. You may want to set this, if you are using
sections in the configuration. If you do not use sections, all
this will give you is a performance penalty. (default value:
false)
checkprofilerc
If set, arename will check if there is a configuration file for
a profile as soon as it reads a profile definition in the setup
and only consider the profile if it found the according config
file. Profiles without config file will cause a warning if this
is set, which may cause the dryrun option to be set if the
warningsautodryrun option is set.
If unset, profiles without config file will not cause warnings.
You will see messages about missing configuration files, if a
profile without config file is active. (default: true)
comp_template
Defines a template to use with files that provide a compilation
tag (for ’various artist’ CDs, for example). This setting can
still be overwritten by the --compilation-template command line
option. (default value: va/&album/&tracknumber - &artist -
&tracktitle)
debug Enable debugging by default. This is probably only useful, if
you want debugging to be enabled as soon as possible, when you
are trying to chase bugs. Do not set this for normal execution.
(default value: false)
default_*
default_artist, default_album, default_compilation,
default_genre, default_tracknumber, default_tracktitle,
default_year
Defines a default value, for the given tag in files, that lack
this information. (default value: undefined)
hookerrfatal
If this is set to false, arename will continue execution even
if reading, parsing or compiling a hooks file failed. (default
value: false)
prefix Defines a prefix for destination files. Setting this to
’/foo/bar’ results in destination files named
’/foo/bar/Expanded Template.ogg’
This setting can still be overwritten by the --profile command
line option. (default value: .)
quiet Switches on quietness. This makes the output a lot more
compact. (default value: off)
quiet_skip
Be quiet about skips. Even if quiet is set, arename will report
files it does not process, because renaming would not change
their names. With this option, these skipped files will not be
reported. This implicitly sets ’quiet’. (default value: off)
sepreplace
Tagging information strings may contain slashes, which is a
pretty bad idea on most file systems. Therefore, you can define
a string, that replaces slashes with the value of this setting.
(default value: _)
template
Defines a template to use with files that do not provide a
compilation tag (or where the compilation tag and the artist
tag are exactly the same). This setting can be overwritten by
the --compilation-template command line option. (default value:
&artist[1]/&artist/&album/&tracknumber - &tracktitle)
tnpad This defines the width, to which the track number field is
padded with zeros on the left. Setting this to zero disables
padding. (default value: 2)
usehooks
If set to true, use hooks defined in ~/.arename.hooks.
(default value: true)
uselocalhooks
If set to true, use hooks defined in ./.arename.hooks.local.
(default value: false)
uselocalrc
If set to true, read a local configuration file
(./.arename.local), if it exists. (default value: false)
useprofiles
If set to true, configuration profiles will be used. If false,
they are not. (default value: true)
verbose Switches on verbosity by default. This makes arename’s output
really noisy. This is probably only useful for debugging or if
you are really interested in what is going on. (default value:
false)
warningsautodryrun
Switches on the dryrun option (if not enabled already), as soon
as the configuration file parser encounters non-fatal warnings.
This option was introduced to avoid destructive behaviour due
to incorrect lines in any of the configuration files. (default
value: true)
User defined variables
You can use the set command in arenamerc files. This way the user can
define his own variables. The namespace is seperate from arename’s
normal settings. (That means, you cannot, for example, overwrite the
internal template variable with this command.)
The synax is quite simple (and different to normal settings on
purpose!):
set varname = value
There may be an arbitrary amount of whitespace around the equal sign
(including no whitespace at all). If you want to have a value that
starts in a whitespace character, you may start the value with a
backslash character (just like with the normal settings, a leading
backslash is always ignored).
You may also set user defined variables on the command line by using
the --userset option:
% arename --userset variable0=value
% arename -u variable0=value
User defined variables are useful to make hooks configurable (see
"HOOKS" below).
It is, however, not allowed to define this kind of variable within the
scope of a section. Doing so will trigger a warning, which will pull
arename into dryrun, depending on whether warningsautodryrun is set or
not.
TEMPLATE FORMAT
arename’s templates are quite simple, yet powerful.
At simplest, a template is just a fixed character string. However, that
would not be exactly useful. So, the script is able to expand certain
expressions with information gathered from the file’s tagging
information.
The expressions can have two slightly different forms:
&identifier
The simple form.
&identifier[length]
The "complex" form. The length argument in square brackets
defines the maximum length, to which the expression should be
expanded.
That means, if the Artist of a file reveals to be ’Frank
Zappa’, then using ’&artist[1]’ will expand to ’F’.
Available expression identifiers
The data, that is expanded is derived from tagging information in the
audio files. For .ogg and .flac files, the tag checking arename does is
case insensitive and the first matching tag will be used.
album Guess.
artist Guess again.
compilation
For .ogg and .flac this is filled with information found in the
’albumartist’ tag. For .mp3 this is filled with information
from the id3v2 TPE2 frame. If the mp3 file only provides a
id3v1 tag, this is not supported.
genre The genre or content type of the audio file.
tracknumber
The number of the position of the track on the disc. Obviously.
However, this can be in the form of ’12’ or ’12/23’. In the
second form, only the part left of the slash is used. The
tracknumber is a little special, as you can define to what
width it should be padded with zeros on the left (see tnpad
setting in "SETTINGS").
tracktitle
Well...
year Year (id3v1), TYER (id3v2) or DATE tag (.ogg/.flac).
EXIT STATUS
arename returns zero if everything went fine; non-zero on fatal
problems. This may change in future versions.
HOOKS
Before we start, a word of warning: Hooks can solve a lot of problems.
That amount of flexibility comes at its price. All data passed to hook
functions are references to the actual data in the script (except for
the namespace argument, which is a copy). If you write hooks
carelessly, arename will get back at you! HOOKS ARE A BIG HAMMER, THAT
CAN CRUSH PROBLEMS AS WELL AS LIMBS!
You have been warned!
Discussion
The reason for implementing hooks was to have a simple way of post
processing tags, filenames etc. without having to invent own magic in
the configuration files, when Perl has regular expressions on steriods
anyway. Hooks can do more then pure pre and post processing, because
they are called in numerous places and give broad access to the
script’s data structures. Still, post processing is probably the most
useful feature they implement.
Hooks are just Perl subroutines, which are defined in one of two files
(see "FILES"). They are run at certain events during the execution of
arename. The contents of the argument list for each hook depends on
what hook is called (see the "List of hook events" below). However,
the first argument (argument zero aka. $_[0]) to all hooks is the hook
namespace, the subroutine is called in.
The global hooks file is read before the local one, which means, that
this local file may overwrite and extend the definitions from the
global file, as much as Perl permits. This also means, that hooks from
the local file are run after the ones from the global file (unless you
are using your own method of registering hooks; but if you do so, you
know what you are doing anyway).
Subroutines must be registered to arename, to be known as hooks. Once
registered, a subroutine can be removed from the known hooks, if
requested (see "Utility subroutines" below).
The keys in various data hashes passed to the hooks can be one of the
following: album, artist, compilation, genre, tracknumber, tracktitle,
year.
Utility subroutines
Registration subroutines
There are two subroutines, that are used to tell arename about
subroutines, you defined that shall become hooks.
register_hook(event, coderef)
Registers a code reference (read: your subroutine) for the given
event. Example: register_hook(’startup’, \&custom_banner);
remove_hook(event, coderef)
Removes all entries of the code reference for the given event.
Example: remove_hook(’startup’, \&custom_banner);
If the coderef was added more than once, all entries are removed.
File access and manipulation
The currently processed file name can be accessed via two subroutines:
get_file()
Returns the current file name as a string. This way, you can get
the name of the currently processed file in every hook.
set_file(file name string)
This gives you the opportunity of manipulating the current file
name. Be careful using this, because if you break the file name,
arename cannot work properly.
With these, you could even change the file name of the processed file,
while arename works on it (which you really should only do, if you know
what you are doing).
User-defined-variable subroutines
Hooks can also use the data from user defined variables, via their Perl
interface:
user_get(setting)
Returns the current value of setting. This is always a scalar
value.
user_set(setting, value)
Change the value of setting to value.
Here is an example for user defined settings:
# Assume, the user set the myvar-variable to "bar" in his
# configuration file
my $foo = user_get('myvar'); # $foo is now "bar"
user_set('foo', "bar, baz");
my $foo = user_get('myvar'); # $foo is now "bar, baz"
API for accessing to arenames internal configuration
You can also access the configuration data of arename itself:
get_opt(setting)
Returns the current value of setting. This is always a scalar
value.
set_opt(setting, value)
Change the value of setting to value.
A list of settings arename will use: canonicalize, dryrun, force,
hookerrfatal, oprefix, prefix, quiet, quiet_skip, readstdin, shutup,
sepreplace, tnpad, usehooks, uselocalhooks, uselocalrc, verbose,
comp_template and template.
If you want to actually change these settings, you should have a
profound knowledge of arename’s internals. Be careful.
API for default_* settings
If you need to access the current values of the default_* settings:
get_defaults(tagname)
Returns the value of default_tagname.
get_default_keys()
Returns a lexically sorted array of tag names of currently set
default_* values.
set_default(tagname, value)
Sets the value of default_tagname to value.
Output subroutines
For output, you can use the following functions, the rest of arename
uses as well:
oprint(args, ...)
Print to the standard output stream. This can be called the same
way as Perl’s usual print subroutine.
owarn(args, ...)
Print to the standard error stream.
Miscellaneous subroutines
And finally, a few miscellaneous functions ARename.pm provides, that
might be of interest.
choose_template(data hash reference)
Return the appropriate template (normal versus compiliation
template) by the data in the referenced data hash.
expand_template(template string, data hash reference)
Return the expanded version of template string. The information,
that is used to do the expansion is taken from the referenced data
hash.
Keep in mind that this function calls hooks itself. Avoid endless
loops! See "Hooks when expanding the template" for details.
ensure_dir(directory)
Makes sure directory exists. Think: mkdir -p directory
file_eq(file0, file1)
Checks if the name file0 and the name file1 point to the same file.
Returns 0, if one of the file names does not exist or if the files
do not point to the same file, 1 otherwise.
Dies if it cannot stat one of the given files.
tag_supported(tagname)
Returns 1 if the tag tagname is supported by arename, 0 otherwise.
xrename(src, dest)
Renames src to dest. Works across file systems, too. Dies if
something fails.
List of hook events
This is a complete list of hooks events with descriptions.
The first argument (argument number "zero") for every hook is the name
space they are called in. To find out the name of the currently
processed file, use the get_file() subroutine described above.
Hooks in the main loop
These hooks are called at the highest level of the script.
canonicalize
This is called in the middle of the file name canonicalization
process (but only it is enabled via the canonicalize setting).
Get the current file name via get_file(). The canonicalized file
name is handed to you via the hook’s arguments. The value from this
argument will be assigned to the processed filename after the
execution of this hook.
Arguments: 1: canonicalized file name
next_file_early
Called at the start of the main loop before any file checks and
canonicalizations (if enabled) are done.
Arguments:
next_file_late
Called in the main loop after the file checks and canonicalizations
are done.
By file checks, checks for read-access and for symlinks are meant.
arename will refuse to process symlinks and files it cannot read.
Arguments:
file_done
Called in the main loop after the file has been processed (unless
filetype_unknown was triggered, see below).
Arguments:
filetype_unknown
Called in the main loop after the file was tried to be processed
but the file type (the extension, specifically) was unknown.
Arguments:
Hooks in the renaming procedure
When all data has been gathered, arename will go on to actually rename
the files to their new destination name (which will be generated in the
process, see "Hooks when expanding the template" below).
pre_apply_defaults
This is the first action to be taken in the renaming process. It is
called even before the default values are applied.
Arguments: 1: data hash, 2: file extension
pre_template
Called before template expansions have been done.
Arguments: 1: data hash, 2: file extension
post_template
Called after the template has been expanded and the new file name
has been completely generated (including the destination directory
prefix).
Arguments: 1: data hash, 2: file extension 3: the generated new
filename (including directory prefix and file extension)
post_ensure_dir
The destnation directory for the new file name may contain sub
directories, which currently do not exist. This hook is called
after it is ensured, every directory portion exists.
Arguments: 1: data hash, 2: file extension 3: the generated new
filename (including directory prefix and file extension)
post_rename
This is the final hook in the actual renaming process. The file has
been renamed at this point.
Arguments: 1: data hash, 2: file extension 3: the generated new
filename (including directory prefix and file extension)
Hooks when expanding the template
These hooks are called when the template string is filled with the data
from tags in the audio files. All file type specific actions will have
been taken care of already. That makes these hooks probably most useful
for post processing tags, the template and file names.
pre_expand_template
Called before any expansions are done.
Arguments: 1: the template string, 2: the data hash
expand_template_next_tag
This hook is triggered when the next identifier in the template
string is processed. At this point it is already verified, that
there is an according tag in the data hash to fill in the
identifier’s space.
Arguments: 1: the template string, 2: the tag’s name 3: the value
of the length modifier in the template (zero, if unspecified) 4:
the data hash
expand_template_postprocess_tag
This hooks is triggered after all internal processing of the
replacement token is done (directory seperators are replaced;
tracknumbers are padded up).
Arguments: 1: the template string, 2: the text token, that will
replace the identifier in the template, 3: the tag’s name 4: the
value of the length modifier, 5: the data hash
post_expand_template
Called after all expansions have been done, right before the the
resulting string is returned.
Arguments: 1: the template string (fully expanded), 2: the data
hash
Hooks when gathering information
These hooks are triggered while the tag information is extracted from
the audio files arename is processing. Due to the differing nature of
the the involved backends, these are slightly different from file type
to file type.
Specifically, the tag for .ogg and .flac files are read one after
another (the tags in these files are pretty much the same, hence they
are processed exactly the same), whereas tags in .mp3 files are read
all at the same time.
pre_process_flac
.flac only!
Called before a flac file is processed.
Arguments:
post_process_flac
.flac only!
Called after a flac file is processed.
Arguments:
pre_process_ogg
.ogg only!
Called before an ogg file is processed.
Arguments:
post_process_ogg
.ogg only!
Called after an ogg file is processed.
Arguments:
pre_handle_vorbistag
.ogg and .flac only!
Triggered before any processing of a certain tag. It is not ensured
that the tag is even among the supported tags at this point.
Arguments: 1: tag name, 2: tag value, 3: data hash
post_handle_vorbistag
.ogg and .flac only!
Triggered after a certain tag was processed.
This hook is only reached if the currently processed tag is in fact
among the tags supported by arename.
Arguments: 1: tag name, 2: tag value, 3: the internal name for the
tag (also used as the key in the data hash), 4: data hash
pre_process_mp3
.mp3 only!
Called before an mp3 file is processed.
Arguments:
post_process_mp3
.mp3 only!
Called after an mp3 file is processed.
Arguments:
pre_handle_mp3tag
.mp3 only!
Called before data from the mp3 object is copied to the data hash.
Arguments: 1: the mp3 object, 2: data hash
post_handle_mp3tag
.mp3 only!
Called after data from the mp3 object has been copied to the data
hash.
Arguments: 1: the mp3 object, 2: data hash
Miscellaneous hooks
apply_defaults
This is triggered before values from the default_* settings are
applied to missing values in the audio file. This hook is only run
if a default value for a tag will be used!
Arguments: 1: data hash, 2: current key
pre_method
This hook is called after a method for a file type is choosen but
before the method was executed.
Arguments: 1: method name
post_method
Called after a method for a file type was executed.
Arguments: 1: method name
startup
Called directly after all the module initialisation is done, at the
very start of the script. Configuration files will have been read,
as well as hook files (obviously) and command line options will
have been handled at this point already.
This hook may be useful for postprocessing the configuration as
well as for debugging.
Arguments: 1: program name, 2: its version, 3: configuration hash,
4: hash of extensions, that point the the according method for the
file type 5: array of supported tags, 6: the program’s argument
list
normal_quit
Called at the end of the script. This is reached if nothing fatal
happened.
Arguments: 1: the program’s argument list
Example
This is a very simple example for a hook file, that prints a custom
banner and replaces all whitespace in the expanded template with
underscores:
sub my_banner {
oprint "Hello World.\n";
}
register_hook('startup', \&my_banner);
sub replace_spaces_by_underscore {
my ($templateref, $datref) = @_;
$$templateref =~ s/\s+/_/g;
}
register_hook('post_expand_template',
\&replace_spaces_by_underscore);
Further examples can be found in the arename.hooks file of the
distribution.
SEE ALSO
Ogg::Vorbis::Header, Audio::FLAC::Header and MP3::Tag.
VERSION
This manual describes arename version 3.1.
AUTHOR
Frank Terbeck <ft@bewatermyfriend.org>,
Please report bugs.
LICENCE
Copyright 2007, 2008, 2009
Frank Terbeck <ft@bewatermyfriend.org>, All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above
copyright notice, this list of conditions and the following
disclaimer.
2. Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials
provided with the distribution.
THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS OF THE
PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.