AUDIO_RENAME(1) User Contributed Perl Documentation AUDIO_RENAME(1)NAMEaudio_rename - rename an audio file via information got via MP3::Tag.
SYNOPSISaudio_rename-csR -@p "@a/@l/@02n_@t" .
renames all the audio files in this directory and its subdirectories
into a 3-level directory structure given by Artist_Name/Album/Filename,
with the basename of Filename being the 2-digit track number separated
from the title by underscore; it also transliterates cyrillic, and
shortens long names.
(Due to use of "-@" and double quotes, this command line should work
both with UNIXish and DOSish shells; the other examples can be massaged
likewise.)
(Replacing @02n by "@{mA}@{n0}" (as in the default value of "-p") may
provide more intelligent semantic. See the description of "-p".
audio_rename-KD *.wav
Reports how it would rename the *.wav files in this directory according
to the default -p rule, but without protectiing "funny" characters.
Will not do actual renaming.
audio_rename-sc *.mp3
Rename the *.mp3 files in this directory according to the default -p
rule, translating cyrillic characters into Latin "equivalents",
shortening the names of long components, and protecting "funny"
characters.
audio_rename-p '%a/%{d0}/%B' -G '*/*.mp3'
Assuming one-level subdirectory structure dir/filename.ext, finds files
with extension .mp3, and "sorts" them into a two-level subdirectory
structure; toplevel directory is based on the "artist" field, the
remaing level is preserved.
audio_rename-p '%a/%{d0}/%B' -R .
Likewise, but does not suppose any particular depth of the current
directory structure; only the filename and the most internal directory
name are preserved.
audio_rename-p '%a/%N' -R .
Likewise, but all directory names (inside the current directory) are
preserved.
DESCRIPTION
The script takes a list of files (or, with -R option, directories) and
renames the given files (or audio files in the directories) according
to the rules specified through the command line options. File
extensions are preserved (by default).
Some "companion" files (i.e., files with the same basename, and with an
extension from a certain list) may be renamed together with audio
files. A lot of care is taken to make the resulting file names as
portable as possible: e.g., "funny" characters in file names are dumbed
down (unless requested otherwise), long filename components may be
shortened to certain limits.
A care is taken so that renaming will not overwrite existing files;
however, on OSes which allow rename() to overwrite files, race
conditions can ruin the best intentions. E.g., do not run several
"overlapping" rename procedures simultaneously!
Recognized options
General use options:
-p "TARGET_FILENAME_PATTERN"
Target file name/basename pattern; is subject to interpolation via
"MP3::Tag" method "interpolate()". Default is "%{mA}%{n0}_%t"; in
simplest cases this uses 2-digit track number separated from the
title by underscore. See "interpolate" in MP3::Tag for more
details.
Here is the explanation of the default value: due to semantic of
escapes "%{mA}" and "%{n0}", if "TPOS" frame (disk number) is
present, it is encoded as a letter, and put before the track
number. If the track number has a form "N1/N2" (meaning track N1
of N2), then N1 is used, and padded by 0s to the width of N2. If
"N2" is not present, padding to width=2 is used.
For example, if "TPOS" is 3/12, and track is "14/173", then what is
prepended to the title is "c014_"; if there is no "TPOS" frame, and
track is "4/8", "4_" is prepended without any leading 0.
(If you want to modify the semantic of "%{n0}", note that it is
equivalent to "%{n2:%{n0}}%{!n2:%02n}". So while %02{n0} will
ALWAYS 0-pad to at least width=2, the pattern
"%{n2:%{n0}}%{!n2:%03n}" will 0-pad to width=3 in the case N2 is
absent.
-e ".ext1|.ext2|..."
"|"-separated list of associated extensions; when renaming
source.mp3 to target.mp3, the similar rename will be done to files
with the same basename, and extensions .ext1, .ext2, etc. Defaults
to ".inf|.tag|.id3".
-x If not present, the pattern of -p is the basename; the extension of
the initial file is appended (as interpolated by %E). If present,
the pattern of -p is the complete file name. Behaviour with non-
empty list of associated extensions is not defined.
The following options have the same meaning as for script "mp3info2"
-D "Dry run": do not rename, just report the calculated renames.
-G Arguments are glob patterns; expand them.
-R Arguments are directory names, recurse inside using option -E for
choosing audio files via their extension.
-r Regular expression to use when looking for audio files per option
-R. Defaults to "(?i:\.mp3$)": will find files ending in .mp3
(ignoring the case). Note that this expression is put into a case-
ignoring regular expression, so if you want it to be case-
sensitive, protect it as in "(?-i:REGEXPR)".
-E "option_letters"
Controls expansion of escape characters. It should contain the
letters of the command-line options where "\\, \n, \t" are
interpolated. Default is none.
-@ Replace "@" by "%" in option values. (May be useful since -p and
-P may have a lot of embedded characters "%", which may be hard to
deal with on some shells, e.g., DOSISH shells. DOSish shells
recognize double quotes, so if one wants shell-transparent examples
of command lines, use -@ and double quotes.)
-P "patterns"
Patterns to parse before application of the rule -p. See mp3info2
for details.
-C "config_options"
Configuration options for MP3::Tag. See mp3info2 for details.
File name portability options:
-s Make the components of file names short enough to fit on a CD file
system. Currently this means the restriction to 110 chars (as with
"mkisofs -J --joliet-long", at least of version 2.01a32). The
limit may be modified per "AUDIO_MAX_FILENAME_LEN" environment
variable.
Note that "components" are parts separated by a literal character
"/" in the given pattern (not slashes coming from interpolated
strings).
-c Latinize file names (for portability) assuming they are in
WinCyrillic encoding. Needs transliterate_win1251.pm (in
examples/mod/Encode directory of the distribution; put it in the
subdirectory Encode of the script directory).
-K Do not convert "exotic" characters to underscores (those characters
which have a low portability score, so the files will have problem
being moved between systems).
Note that this utility performes very similarly to mp3info2 utility
when the latter one is used with -p option; only instead of printing
the result of interpolation of -p, it uses the result as the target
file name for renaming (after some "sanitizing" of the result).
(However, the defaults for "-E" options differ!)
Please take into account that the option -P is provided for
completeness only. If one needs really complicated parsing rules to
deduce the resulting file name, it is much safer to use mp3info2
utility to set the wanted file name into some ID3v2 frame (such as
"TXXX[wanted-target-name]"), and then, after checking for errors, use
this result similarly to
audio_rename-p "%{TXXX[wanted-target-name]]}" -R .
After rename, one can delete this frame from the resulting files.
If you want to be absolutely error-prone, preserve the initial file
name inside the files by doing something similar to
mp3info2 -@F "TXXX[orig-fname]=@A" -R .
before the rename. If worst comes to worst (but no race conditions
happend, so files are not overwritten), one should be able to restore
the status quo by running
audio_rename -@p "@A" files_or_directories_list
(giving -R option if needed).
POSSIBLE PROBLEMS
With -R option, there might be situations when the scan of
subdirectories first finds a source file in some directory, renames it,
then continues the scan of other subdirectories, and will find the
target file, so will try to rename it again.
In practice, I do not recall ever encountering this situation; if the
target file name depends only on the contents of the file, and not its
name, then the second rename will be tautological, so not visible.
AUTHOR
Ilya Zakharevich <cpan@ilyaz.org>.
SEE ALSO
MP3::Tag, MP3::Tag::ParseData, mp3info2
perl v5.20.2 2008-10-23 AUDIO_RENAME(1)