Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
AUDIO_RENAME(1)	      User Contributed Perl Documentation      AUDIO_RENAME(1)

       audio_rename - rename an	audio file via information got via MP3::Tag.

	 audio_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

       (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"

	 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

       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:

	   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

	   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

       -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

	   Note	that "components" are parts separated by a literal character
	   "/" in the given pattern (not slashes coming	from interpolated

       -c  Latinize file names (for portability) assuming they are in
	   WinCyrillic encoding.  Needs (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).

       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.

       Ilya Zakharevich	<>.

       MP3::Tag, MP3::Tag::ParseData, mp3info2

perl v5.32.0			  2008-10-23		       AUDIO_RENAME(1)


Want to link to this manual page? Use this URL:

home | help