arename - Online in the Cloud

PROGRAM:

NAME

arename - automatically rename audio files by tagging information

SYNOPSIS

arename [OPTION(s)] FILE(s)...

OPTIONS AND ARGUMENTS

--ambiguous-use-first
Sets the ambiguoususefirst option. See below for details.

--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 Enable debugging output. This actually sets `verbosity' to 10000. This output
option will cause very noisy output. You probably want something less verbose,
like `--verbosity 20'.

--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-file-types
Lists all file types currently supported by arename, one type per line.

--list-exts-for-type <type[,type[,...]]>
Lists all extensions recognised file name extsionsion for type <type>, one
extension per line. If a list of types is given as a comma-separated list,
extensions for all listed types are listed.

--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.)

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

--version (short option: -V)
Display version information.

--verbosity <integer-value>
Sets the `verbosity' setting to `integer-value'.

--suppress-skips (short option: -Q)
When a file is skipped, because its name would not change, this option will cause
arename to suppress any output. This sets the `suppress_skips' option.

Note that if the `verbosity' setting is at a high enough level, you may still get
messages about the file being processed in the first place.

--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. If changes to the --long-option interface are done, that
will happen with an appropriate deprecation phase, so users can adjust. 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 3.x to 4.0 can be found in the project's
CHANGES file and general advice about incompatible changes from major version to major
version are documented in the UPGRADING file.

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

--quiet
This option is a short hand for "--verbosity 10".

--uber-quiet
This option is a short hand for "--verbosity 5".

--verbose
This is a short hand for "--verbosity 20".

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
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) let's 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

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):

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

ARENAME_SUPPRESS_COLOURS
When set to 1 (and only 1 - arename will ignore any other setting), arename will
turn off its output colourations. As of version 4.0, arename uses Term::ANSIColor
to produce output, that features terminal colours.

Use arename online using onworks.net services