arename1

Deprecated Command Line Options

The following options are deprecated and will be removed in a later version of arename.

Supported file formats

Since version 4.0, arename supports a lot more file formats than it used to (version 3.0 only supported .mp3, .ogg and .flac files). Thanks to Audio::Scan, we now support a much wider range of file types, of which most may exist using different file name extensions (e.g. *.ogg and *.oga are both of the type ogg).

You may use the `--list-file-types' and `--list-ext-for-type' options to find out which file type is mapped to which file name extensions.

If you would like support for another file type in arename, you will have to persuade the Audio::Scan developers to extend their module with said feature. Adding support for it in arename after that should be trivial.

To give you an idea, arename (in connection with Audio::Scan 0.85) lets you rename mp3, mp4, aac, ogg, flac, asf, musepack, monkey audio, wav (this type also supports aiff) and wavpack files.

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 the xargs tool instead.

A last solution for zsh users would be zargs (which requires 'autoload zargs' in your zsh configuration):

  % zargs -- **/*.mp3 -- arename -d

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
  verbosity 20
  # 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.

Deprecated Settings

verbose

This setting has no effect and will be removed in a later version. Use an appropriate `verbosity' setting instead.

quiet

This setting has no effect and will be removed in a later version. Use an appropriate `verbosity' setting instead.

quiet_skip

This setting has no effect and will be removed in a later version. Use an appropriate `verbosity' setting instead.

debug

This setting has no effect and will be removed in a later version. Use an appropriate `verbosity' setting instead.

User defined variables

You can use the set command in arenamerc files. This way the user can define his own variables. The namespace is separate from arename's normal settings. (That means, you cannot, for example, overwrite the internal template variable with this command.)

The sytnax 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). Starting with version 4 of arename, user defined variables may also be defined within sections, which (just like normal option) makes them applicable only if said section is used for a given file.

Nesting expressions

In complex expressions, the strings called `default-template', `set-template' and `unset-template' are subject to regular template expansion. Hence, expressions like the following are possible:

  "&{album?&album/!}"

If `album' were set, it would expand to its value followed by a slash; otherwise it would expand to nothing. Using this, it is fairly easy to deal with album-less tracks:

  "&artist/&{album?&album/&tracknumber. !-no-album-/}&tracktitle"

That will effectively use the following template if `album' is set:

  "&artist/&album/&tracknumber. &tracktitle"

But if it is not set, it will instead use this:

  "&artist/-no-album-/&tracktitle"

Caution has to be taken if certain characters are to be used within conditional template expressions. For example, to use a closing curly bracket in either of them, it needs to be quoted using a backslash character.

Similarly, if an exclamation mark is to be used in a `set-template', it needs to be quoted by a backslash to avoid the character being interpreted as the end of the `set-template' string.

Available expression identifiers

The data, that is expanded is derived from tagging information in the audio files. There are two kinds of information available. One is the purely informational tag (like a track's artist) and the other further describes the format of the audio file (like the file's bitrate).

If you are defining a lot of templates on the command line, you may find that these identifiers take quite a while to type. If the template_aliases option is set, you may use shorter alias names instead of the the real identifier. Available aliases are listed with their corresponding idetifier below.

This is a list of all informational identifiers available for all file-types:

album

The album the currently processed track is part of. (alias: al)

artist

The artist for the current track. (alias: ar)

compilation

Compilation tags are not very stable across different file types. Usually, this is set to a string like "Various Artists" for tracks that are part of some sort of compilation album (like motion picture sound-tracks). (alias: cmp)

genre

The genre or content type of the audio file. (alias: gn)

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"). (alias: tn)

tracktitle

The title of the currently processed track. (alias: tt)

year

Chronological information about the track (usually the year a song was written or the year the album a track is part of was released). (alias: yr)

Here is a list of file-format information tag available for all file-types:

bitrate

The bitrate the file was recorded/encoded with. (alias: br)

channels

The number of channels available in the file (for example, this is `2' for stereo files). (alias: ch)

length_ms

The length of the track in milli-seconds. (alias: ln)

samplerate

The samplerate the file was recorded/encoded with. (alias: sr)

For all file-types, the following tags are generated from the ones listed above (for convenience):

Some tags are only available for certain file-types. They are always called `type_*'. File-type specific identifiers do not have alias names. Here is a list of those tags:

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:

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 arename's internal configuration

You can also access the configuration data of arename itself:

A list of settings arename will use: canonicalize, dryrun, force, hookerrfatal, prefix, quiet, quiet_skip, readstdin, sepreplace, tnpad, usehooks, uselocalhooks, uselocalrc, verbose, verbosity, 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:

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.

template_deep_inspect(template_string)

This tokenises a template string and then looks at the whole token tree, and tries to figure out any potential problems in it.

If tokenisation already failed, a negative value is returned. In case of any warnings with the token tree, zero is returned. If nothing came up, a positive value is returned.

This subroutine is called for the `template' and `comp_template' strings in all sections when arename starts. If the user chooses to change a template string in a hook it is recommended to use this function to avoid any errors due to broken templates.

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 if the canonicalize setting is set).

You can 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.

In this context, file checks means tests for read-access and for whether the processed file is a symlink. 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:

filetype_known

Called when it has been established, that the file in question should theoretically be supported by arename.

Arguments: 1: the current file name extension 2: the file type that has been detected

pre_rename

This is triggered directly before the actual file renaming process starts. All information about the file has been gathered at this point.

Arguments: 1: the file type, 2: the extension that will be used to assemble the target filename, 3: the data hash

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. To do this, arename first tokenises the template string into a data structure, which is later used to assemble the target file name.

pre_expand_template

Called before any expansions are done.

Arguments: 1: the template string, 2: 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

expand_template_pre_expand_tag

Called each time the value of an existing tag is expanded. This may be more than once, as tags may be used as often in a template as the user requires. At each point, this hook will be called right before the data was retrieved and post-processed (like zero-padding the `tracknumber' tag).

Arguments: 1: the tag's name, 2: the data hash

expand_template_unknown_tag

This hook gets called whenever arename tries to expand a tag within a template, for which it does not have any data available.

Arguments: 1: the supposedly expanded string (`undef' upon hook-entry), 2: the tag's name, 2: the data hash

expand_template_post_expand_tag

Called each time the value of an existing tag is expanded. Like with the `expand_template_pre_expand_tag' hook, this may be more than once.

At each point, this hook will be called right after the data was retrieved and post-processed.

Arguments: 1: the value, which will be used for expansion, 2: the tag's name, 2: the data hash

Hooks while gathering information

These hooks are triggered while the tag information is extracted from the audio files arename is processing. This is done in two steps. First the Audio::Scan module is used to scan for the raw meta data information from the current file. Then arename's data hash is being filled with that data.

pre_scan

This hook is called right before any scanning has been done.

Arguments: 1: the type of the file being processed (`ogg' for ogg vorbis files)

post_scan

This is triggered as soon as Audio::Scan is done processing the current file, but before arename's data hash has been filled.

Arguments: 1: the type of the file being processed (`ogg' for ogg vorbis files), 2: the data structure returned by `Audio::Scan'

ambiguoustag

When the data hash is being filled it is possible, that for one arename tag (like `artist') multiple values where returned by Audio::Scan. This hook is triggered as soon as such a tag with ambiguous values is processed.

The hook may be used for maximum control over how ambiguous values are handled. To do this, the ambiguous value (passed as an array reference in the second argument) should be turned into the desired scalar value.

If the array reference is left as it is, the usual `ambiguoususefirst' behaviour is followed. The the option's description for details.

Arguments: 1: the name of the tag with the ambiguous value, 2: its current (ambiguous) value, 3: the data hash in its current form (obviously not all values will have been filled in at this point), 4: the data structure returned by Audio::Scan (see its documentation for details)

post_fill

Finally, the `post_fill' hook is called after the data hash has been filled. This is a good spot, if post-processing the values of individual tag is desired.

Arguments: 1: return code of the filling process (`0' in case of an error, `1' otherwise), 2: the type of the file being processed (`ogg' for ogg vorbis files), 3: the data structure returned by `Audio::Scan', 4: the 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

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: array of supported tags, 5: 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

First, to give you an idea about how argument passing works in arename hooks, take a look at these two `startup' hooks:

  sub print_banner0 {
      # Yes, everything handed over to hooks (except for the namespace)
      # are references. This gives us simple two way communication, but
      # it's also a pretty big responsibility to handle. Think before
      # screwing up. :)
      my ($ns, $nameref, $verref, $confref, $suptagsref, $argvref) = @_;
      print "BANNER! $$nameref $$verref " . $argvref->[0] . "\n";
      # The following actually changes the $NAME variable, used
      # in ARename.pm, which doesn't hurt, because it is only the
      # name of the program running. For other hook events and variables,
      # there might be vital data in one of the references. Be very careful
      # before changing values willy-nilly.
      $$nameref =~ s/name/blame/;
  }
  register_hook('startup', \&print_banner0);
  sub print_banner1 {
      my ($ns, $nameref, $verref, $confref, $suptagsref, $argvref) = @_;
      # Since $NAME used to be 'arename', the substitution
      # in print_banner0() will have changed $NAME to 'areblame',
      # which $$nameref below will reveal.
      print "ANOTHER BANNER! $$nameref $$verref\n";
  }
  register_hook('startup', \&print_banner1);

After that short introduction, here is something more useful. The following hook will replace all whitespace with underscores in generated file names.

  sub replace_spaces_by_underscore {
      my ($templateref, $datref) = @_;
      $$templateref =~ s/\s+/_/g;
  }
  register_hook('post_expand_template', \&replace_spaces_by_underscore);

This will do the trick, but there is actually an arename extension that is distributed with the application, which is designed to solve exactly this problem. See "EXTENSIONS" below for details on the `ReplaceSpaces' extension module.

User-defined Extensions

Say you have decided, that the `ARename::Extension::register()' idea to encapsulate extensions is a good idea and now you want to do that yourself, too. Maybe because, you just like to keep your `hooks' file tidy or maybe because you want to contribute your awesome extension code back to arename. Either way, you will need a place to put your Perl code.

Arename does NOT set such a place by default. But it is very easy to set it yourself from the `hooks' file:

  BEGIN {
      unshift @INC, $ENV{HOME} . q{/.arename};
  }

That way you can place Perl modules into `~/.arename' like this:

  ~/.arename/ARename/MyAwesomeExtension.pm

And then just use it like the bundled extensions:

  use ARename::MyAwesomeExtension.pm;
  ARename::MyAwesomeExtension::register();

Take a look at the `KillNonASCII.pm.in' file in the `arename' sources, for details about how to write proper extensions and how to make them configurable and how to make use of the bundled utilities to make your extension appropriate for inclusion with `arename'.