AUDIO_RENAME(1p)

🌸 audio_rename 🌸 (yes bestie, this is the AUDIO_RENAME(1p) page) 👑

okay so before we even start: this whole page is about one little script called audio_rename, and it's lowkey iconic. let's go 💅

---

✨ NAME ✨

audio_rename — renames an audio file using information it got via MP3::Tag. periodt.

---

🦋 SYNOPSIS 🦋

  audio_rename -csR -@p "@a/@l/@02n_@t" .

this one renames every single audio file 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 an underscore; it also transliterates cyrillic, and shortens long names. ate. 🔥

(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 protecting "funny" characters. Will not do actual renaming. (so it's a vibe check, not a commitment 🙈)

  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!

bestie. do NOT run overlapping renames at the same time. that's the whole warning. i said what i said 💀

---

🎀 Recognized options 🎀

💜 General use options:

• -p "TARGET_FILENAME_PATTERN" — the target file name/basename pattern; it's subject to interpolation via the 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|..." — a |-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 Unicode (or 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).
• -L — The value of option -L is the encoding used for the output; if the value is a number, system-specific encoding is guessed (and used for the output if the bit 0x1 is set); if the bit 0x2 is set, then command line options are assumed to be in the guessed encoding; if the bit 0x4 is set, then command line arguments are assumed to be in the guessed encoding. If the bit 0x8 is set, the encoding/decoding configuration of file input/output of MP3::Tag is redone with the the detected encoding.
• -U — In presence of -U option the default for -L is 15, and the decoding/encoding processing happens as if LANG is set for UTF-8 encoding. (For example, for -Uee 1 the STDOUT the output message of this script happens in UTF-8 mode, which makes it easier to detect decoding/encoding errors in tags.)

---

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

🫶 the safety-net arc. save the original name inside the file first, and you can always come back home.

---

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

(ngl that's giving "it's fine, probably" energy and honestly? same.)

---

💖 AUTHOR 💖

Ilya Zakharevich <cpan@ilyaz.org>.

---

🌟 SEE ALSO 🌟

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

---

and that's a wrap bestie 🎀 this page came to you as part of <b>perl v5.36.0</b>, dated <b>2022-12-30</b>, and it lives at AUDIO_RENAME(1p) in the User Contributed Perl Documentation section. slay, go rename something 💅✨