Welcome to audiorename’s documentation!
Contents:
Todos:
Indices and tables
audiorename
Rename audio files from metadata tags.
Installation
From Github
git clone git@github.com:Josef-Friedrich/audiorename.git
cd audiorename
python setup.py install
From PyPI
pip install audiorename
easy_install audiorename
Examples
Please use the -d (--dry-run) option first
Basic example:
cd my-chaotic-music-collection
audiorenamer -d .
More advanced example:
audiorenamer -d -f '$artist/$album/$track $title' --target /mnt/hd/my-organized-music-collection .
Very advanced example:
audiorenamer -d -f '$ar_initial_artist/%shorten{$ar_combined_artist_sort}/%shorten{$ar_combined_album}%ifdefnotempty{ar_combined_year,_${ar_combined_year}}/${ar_combined_disctrack}_%shorten{$title}' .
Usage
usage: audiorenamer [-h] [--config CONFIG] [-v] [-t TARGET] [-a]
[-p BACKUP_FOLDER] [-B] [-d] [-C | -M | -n] [-A | -D] [-F]
[-m ALBUM_MIN] [-e EXTENSION]
[--genre-classical GENRE_CLASSICAL] [-s FIELD_SKIP] [-k]
[-S] [--no-soundtrack] [-f PATH_TEMPLATE]
[-c PATH_TEMPLATE] [--soundtrack PATH_TEMPLATE]
[--format-classical PATH_TEMPLATE] [-K | --no-color] [-b]
[-j] [-l] [-o] [-T] [-V] [-E] [-r]
source
Rename audio files from metadata tags.
How to specify the target directory?
1. By the default the audio files are moved or renamed to the parent
working directory.
2. Use the option ``-t <folder>`` or ``--target <folder>`` to specifiy
a target directory.
3. Use the option ``-a`` or ``--source-as-target`` to copy or rename
your audio files within the source directory.
Metadata fields
===============
$acoustid_fingerprint: The Acoustic Fingerprint for the track. The
fingerprint is based on the audio information
found in a file, and is calculated using the
Chromaprint software.
$acoustid_id: The AcoustID associated with the track. The
AcoustID is the identifier assigned to an
audio file based on its acoustic fingerprint.
Multiple fingerprints may be assigned the
same AcoustID if the fingerprints are similar
enough.
Examples: ['86e217b7-d3ad-4493-a9f2-cf71256ace07']
$album: The title of the release.
Examples: ['Help!']
$albumartist: The artist for the entire album, which may be
different from the artists for the individual
tracks. The artists primarily credited on the
release, separated by the specified join
phrases.
Examples: ['The Beatles']
$albumartist_credit: The release-specific artist credit name,
which may be a variation of the artist’s
“canonical” name.
$albumartist_sort: The release artists sort names, separated by
the specified join phrases. (e.g.: “Beatles,
The”).
Examples: ['Beatles, The']
$albumartists: The album artists specifed as a list.
Examples: [['The Beatles']]
$albumartists_credit: The release-specific artists credit names,
which may be a variation of the artist’s
“canonical” names.
$albumartists_sort: The “sort name” of the artist for the entire
album.
Examples: ['Beatles, The', 'White, Jack']
$albumdisambig: The disambiguation album field helps to
distinguish between identically named albums.
The album “Weezer” for example has the
disambiguation comments “Red Album” and
“Green Album”.
$albumstatus: The status describes how "official" a release
is.
Examples: ['official', 'promotional', 'bootleg', 'pseudo-release']
$albumtype: The primary MusicBrainz release group type;
the MusicBrainz wiki has a list of type
names.
Examples: ['album/soundtrack']
$albumtypes: The MusicBrainz release group types; the
MusicBrainz wiki has a list of type names.
Examples: [['album', 'soundtrack']]
$ar_classical_album: The field “work” without the movement suffix.
For example: “Horn Concerto: I. Allegro” ->
“Horn Concerto”
Examples: ['Horn Concerto', 'Die Meistersinger von Nürnberg']
$ar_classical_performer: “ar_performer_short” or “albumartist” without
the composer prefix: “Beethoven; Karajan,
Mutter” -> “Karajan, Mutter”
Examples: ['Karajan, Mutter', 'Karajan, StaDre']
$ar_classical_title: The movement title without the parent work
prefix. For example “Horn Concerto: I.
Allegro” -> “I. Allegro”
Examples: ['I. Allegro', 'Akt III, Szene V. "Morgendlich leuchtend im rosigen Schein" (Walther, Volk, Meister, Sachs, Pogner, Eva)']
$ar_classical_track: If the title contains Roman numbers, then
these are converted to arabic numbers with
leading zeros. If no Roman numbers could be
found, then the field “ar_combined_disctrack”
is used.
Examples: ['01', '4-08']
$ar_combined_album: “album” without ” (Disc X)”.
Examples: ['Headlines and Deadlines: The Hits of a-ha', 'Die Meistersinger von Nürnberg']
$ar_combined_artist: The first non-empty value of the following
list of fields: “albumartist” -> “artist” ->
“albumartist_credit” -> “artist_credit” ->
“albumartist_sort” -> “artist_sort”. If no
value could be determined, then “Unknown” is
assigned. The second artist after “feat.”,
“ft.” or “vs.” is removed.
Examples: ['a-ha', 'Richard Wagner; René Kollo, Helen Donath, ...']
$ar_combined_artist_sort: The first non-empty value of the following
list of fields: “albumartist_sort” ->
“artist_sort” -> “albumartist” -> “artist” ->
“albumartist_credit” -> “artist_credit”. If
no value could be determined, then “Unknown”
is assigned. The second artist after “feat.”,
“ft.” or “vs.” is removed.
Examples: ['a-ha', 'Wagner, Richard; Kollo, René, Donath, Helen...']
$ar_combined_composer: The first not empty field of this field list:
“composer_sort”, “composer”,
“ar_combined_artist”
Examples: ['Beethoven, Ludwig-van', 'Wagner, Richard']
$ar_combined_disctrack: Combination of disc and track in the format:
disk-track
Examples: ['1-01', '3-099']
$ar_combined_soundtrack: Boolean flag which indicates if the audio
file is a soundtrack
Examples: [True, False]
$ar_combined_work_top: The work on the top level of a work
hierarchy.
Examples: ['Horn Concerto: I. Allegro', 'Die Meistersinger von Nürnberg']
$ar_combined_year: First “original_year” then “year”.
Examples: [1978]
$ar_initial_album: First character in lowercase of
“ar_combined_album”. Allowed characters:
[a-z, 0, _], 0-9 -> 0, ? -> _. For example
“Help!” -> “h”.
Examples: ['h']
$ar_initial_artist: First character in lowercase of
“ar_combined_artist_sort”. Allowed
characters: [a-z, 0, _], 0-9 -> 0, ? -> _.
For example “Brendel, Alfred” -> “b”.
Examples: ['b']
$ar_initial_composer: First character in lowercase of
“ar_combined_composer”. Allowed characters:
[a-z, 0, _], 0-9 -> 0, ? -> _. For example
“Ludwig van Beethoven” -> “l”.
Examples: ['l']
$ar_performer: Performer names.
Examples: ['Herbert von Karajan, Staatskapelle Dresden']
$ar_performer_raw: Raw performer names.
Examples: [[['conductor', 'Herbert von Karajan'], ['orchestra', 'Staatskapelle Dresden']]]
$ar_performer_short: Abbreviated performer names.
Examples: ['Karajan, StaDre']
$arranger: A musician who creates arrangements.
$art: Legacy album art field.
Examples: [b'\xff\xd8\xff\xe0\x00']
$artist: The track artist names, separated by the
specified join phrases.
Examples: ['The Beatles']
$artist_credit: The track-specific artist credit name, which
may be a variation of the artist’s
“canonical” name.
$artist_sort: The “sort name” of the track artist.
Examples: ['Beatles, The', 'White, Jack']
$artists: A multi-value field containing the track
artist names.
Examples: [['a-ha'], ['Anouk', 'Remon Stotijn']]
$artists_credit: The track-specific artists credit names,
which may be a variation of the artist’s
“canonical” names.
$artists_sort: The “sort name” of the track artists.
Examples: [['Beatles, The', 'White, Jack']]
$asin: The Amazon Standard Identification Number -
the number identifying the item on Amazon.
Examples: ['B000002UAL']
$barcode: The barcode assigned to the release. There
are many different types of barcode, but the
ones usually found on music releases are two:
1. Universal Product Code (UPC), which is the
original barcode used in North America. 2.
European Article Number (EAN).
Examples: ['5028421931838', '036000291452']
$bitdepth: The number of bits per sample in the audio
encoding (an int). Only available for certain
file formats (zero where unavailable).
Examples: [16]
$bitrate: The number of bits per seconds used in the
audio coding (an int). If this is provided
explicitly by the compressed file format,
this is a precise reflection of the encoding.
Otherwise, it is estimated from the on-disk
file size. In this case, some imprecision is
possible because the file header is
incorporated in the file size.
Examples: [436523, 256000]
$bitrate_mode: The mode of the bitrate used in the audio
coding (a string, eg. "CBR", "VBR" or "ABR").
Only available for the MP3 file format (empty
where unavailable).
Examples: ['CBR']
$bpm: The number of beats per minute of the track.
$catalognum: A number assigned to the release by the label
which can often be found on the spine or near
the barcode. There may be more than one,
especially when multiple labels are involved.
Examples: ['CDP 7 46439 2']
$catalognums: Multiple numbers assigned to the release by
the label which can often be found on the
spine or near the barcode. There may be more
than one, especially when multiple labels are
involved.
Examples: [['CDP 7 46439 2', 'Do 247282']]
$channels: The number of channels in the audio (an int).
Examples: [1, 2]
$comments: The disambiguation comment entered to help
distinguish one release from another (e.g.:
Deluxe version with 2 bonus tracks).
$comp: Compilation flag.
Examples: [True, False]
$composer: The name of the composer.
Examples: ['Ludwig van Beethoven']
$composer_sort: The composer name for sorting.
Examples: ['Beethoven, Ludwig van']
$copyright: The copyright message for the copyright
holder of the original sound, beginning with
a year and a space character.
$country: The country the release was issued in.
Examples: ['NL', 'EN', 'GB']
$date: The release date of the specific release.
Examples: ['1996-01-01']
$day: The release day of the specific release.
Examples: [31]
$disc: The number of the disc.
Examples: [1]
$disctitle: Mediums are always included in a release, and
have a position in said release (e.g. disc 1
or disc 2). They have a format, like CD, 12"
vinyl or cassette (in some cases this will be
unknown), and can have an optional title
(e.g. disc 2: The Early Years).
Examples: ['disc 2: The Early Years']
$disctotal: The total number of discs.
Examples: [1]
$encoder: The name of the person or organisation that
encoded the audio file. This field may
contain a copyright message, if the audio
file also is copyrighted by the encoder.
Examples: ['iTunes v7.6.2']
$encoder_info: The name and/or version of the encoder used
(a string, eg. "LAME 3.97.0"). Only available
for some formats (empty where unavailable)
Examples: ['LAME 3.92.0+']
$encoder_settings: A guess of the settings used for the encoder
(a string, eg. "-V2"). Only available for the
MP3 file format (empty where unavailable).
Examples: ['-b 255+']
$format: A string describing the file format/codec.
e.g., “MP3” or “FLAC”
Examples: ['MP3', 'FLAC']
$genre: Genres are currently supported in MusicBrainz
as part of the tag system.
Examples: ['Rock']
$genres: Genres are currently supported in MusicBrainz
as part of the tag system.
Examples: [['Rock']]
$grouping: A content group, which is a collection of
media items such as a CD boxed set.
$images: Cover art, also known as "album art" or
"album artwork", is artwork that provides a
visual representation of a release.
Examples: [['<mediafile.Image object at 0x7f51fce26b20>']]
$initial_key: The Initial key frame contains the musical
key in which the sound starts. It is
represented as a string with a maximum length
of three characters. The ground keys are
represented with "A","B","C","D","E", "F" and
"G" and halfkeys represented with "b" and
"#". Minor is represented as "m".
Examples: ['Dbm']
$isrc: The International Standard Recording Code,
abbreviated to ISRC, is a system of codes
that identify audio and music video
recordings.
Examples: ['CAC118989003', 'ITO101117740']
$label: The label which issued the release. There may
be more than one.
Examples: ['Brilliant Classics', 'wea']
$language: The language a release’s track list is
written in. The possible values are taken
from the ISO 639-3 standard.
Examples: ['zxx', 'eng']
$languages: The language a release’s track list is
written in. The possible values are taken
from the ISO 639-3 standard.
Examples: [['zxx', 'eng']]
$length: The duration of the audio in seconds (a
float).
Examples: [674.4666666666667]
$lyricist: The writer of the text or lyrics in the
recording.
$lyrics: The lyrics of the song or a text
transcription of other vocal activities.
$mb_albumartistid: MusicBrainz album artist ID.
Examples: ['1f9df192-a621-4f54-8850-2c5373b7eac9', 'b972f589-fb0e-474e-b64a-803b0364fa75']
$mb_albumartistids: MusicBrainz album artist IDs as a list.
Examples: [['b972f589-fb0e-474e-b64a-803b0364fa75', 'dea28aa9-1086-4ffa-8739-0ccc759de1ce', 'd2ced2f1-6b58-47cf-ae87-5943e2ab6d99']]
$mb_albumid: MusicBrainz work ID.
Examples: ['fd6adc77-1489-4a13-9aa0-32951061d92b']
$mb_artistid: MusicBrainz artist ID.
Examples: ['1f9df192-a621-4f54-8850-2c5373b7eac9']
$mb_artistids: MusicBrainz artist IDs as a list.
Examples: [['1f9df192-a621-4f54-8850-2c5373b7eac9']]
$mb_releasegroupid: MusicBrainz releasegroup ID.
Examples: ['f714fd70-aaca-4863-9d0d-2768a53acaeb']
$mb_releasetrackid: MusicBrainz release track ID.
Examples: ['38c8c114-5e3b-484f-8af0-79c47ef9c169']
$mb_trackid: MusicBrainz track ID.
Examples: ['c390b132-4a44-4e16-bec3-bffbbcaa19aa']
$mb_workhierarchy_ids: All IDs in the work hierarchy. This field
corresponds to the field `work_hierarchy`.
The top level work ID appears first. A slash
(/) is used as separator.
Examples: ['e208c5f5-5d37-3dfc-ac0b-999f207c9e46 / 5adc213f-700a-4435-9e95-831ed720f348 / eafec51f-47c5-3c66-8c36-a524246c85f8']
$mb_workid: MusicBrainz work ID.
Examples: ['508ec4b1-9549-38cd-a61e-1f0d120a6118']
$media: A prototypical medium is one of the physical,
separate things you would get when you buy
something in a record store.
Examples: ['CD']
$month: The release month of the specific release.
Examples: [12]
$original_date: The release date of the original version of
the album.
Examples: ['1991-11-04']
$original_day: The release day of the original version of
the album.
Examples: [4]
$original_month: The release month of the original version of
the album.
Examples: [11]
$original_year: The release year of the original version of
the album.
Examples: [1991]
$r128_album_gain: An optional gain for album normalization. EBU
R 128 is a recommendation for loudness
normalisation and maximum level of audio
signals.
$r128_track_gain: An optional gain for track normalization. EBU
R 128 is a recommendation for loudness
normalisation and maximum level of audio
signals.
$releasegroup_types: This field collects all items in the
MusicBrainz’ API related to type: `type`,
`primary-type and `secondary-type-list`. Main
usage of this field is to determine in a
secure manner if the release is a soundtrack.
$rg_album_gain: ReplayGain Album Gain, see
https://en.wikipedia.org/wiki/ReplayGain.
$rg_album_peak: ReplayGain Album Peak, see
https://en.wikipedia.org/wiki/ReplayGain.
$rg_track_gain: ReplayGain Track Gain, see
https://en.wikipedia.org/wiki/ReplayGain.
Examples: [0.0]
$rg_track_peak: ReplayGain Track Peak, see
https://en.wikipedia.org/wiki/ReplayGain.
Examples: [0.000244]
$samplerate: The sample rate as an integer number.
Examples: [44100]
$script: The script used to write the release’s track
list. The possible values are taken from the
ISO 15924 standard.
Examples: ['Latn']
$title: The title of the track.
Examples: ['32 Variations for Piano in C minor on an Original Theme, WoO 80']
$track: The number of the track on the disc.
Examples: [1]
$tracktotal: The total number of tracks on this disc.
Examples: [12]
$url: Uniform Resource Locator.
$work: The Musicbrainzs’ work entity.
Examples: ['32 Variations for Piano in C minor on an Original Theme, WoO 80']
$work_hierarchy: The hierarchy of works: The top level work
appears first. As separator is this string
used: -->.
Examples: ['Die Zauberflöte, K. 620 --> Die Zauberflöte, K. 620: Akt I --> Die Zauberflöte, K. 620: Act I, Scene II. No. 2 Aria "Was hör ...']
$year: The release year of the specific release.
Examples: [2001]
Functions
=========
alpha
-----
``%alpha{text}``
This function first ASCIIfies the given text, then all non alphabet
characters are replaced with whitespaces.
``%alpha{a1b23c}`` → ``a b c``
alphanum
--------
``%alphanum{text}``
This function first ASCIIfies the given text, then all non alpanumeric
characters are replaced with whitespaces.
``%alphanum{après-évêque1}`` → ``apres eveque1``
asciify
-------
``%asciify{text}``
Translate non-ASCII characters to their ASCII equivalents. For
example, “café” becomes “cafe”. Uses the mapping provided by the
unidecode module.
``%asciify{äÄöÖüÜ}`` → ``aeAeoeOeueUe``
delchars
--------
``%delchars{text,chars}``
Delete every single character of “chars“ in “text”.
``%delchars{Schubert, ue}`` → ``Schbrt``
deldupchars
-----------
``%deldupchars{text,chars}``
Search for duplicate characters and replace with only one occurrance
of this characters.
``%deldupchars{a---b___c...d}`` → ``a-b_c.d``; ``%deldupchars{a---
b___c, -}`` → ``a-b___c``
first
-----
``%first{text}`` or ``%first{text,count,skip}`` or
``%first{text,count,skip,sep,join}``
Returns the first item, separated by ``;``. You can use
``%first{text,count,skip}``, where count is the number of items
(default 1) and skip is number to skip (default 0). You can also use
``%first{text,count,skip,sep,join}`` where ``sep`` is the separator,
like ``;`` or ``/`` and join is the text to concatenate the items.
``%first{Alice / Bob / Eve,2,0, / , & }`` → ``Alice & Bob``
if
--
``%if{condition,trueval}`` or ``%if{condition,trueval,falseval}``
If condition is nonempty (or nonzero, if it’s a number), then returns
the second argument. Otherwise, returns the third argument if
specified (or nothing if ``falseval`` is left off).
``x%if{false,foo}`` → ``x``
ifdef
-----
``%ifdef{field}``, ``%ifdef{field,trueval}`` or
``%ifdef{field,trueval,falseval}``
If field exists, then return ``trueval`` or field (default).
Otherwise, returns ``falseval``. The field should be entered without
``$``.
``%ifdef{compilation,Compilation}``
ifdefempty
----------
``%ifdefempty{field,text}`` or ``%ifdefempty{field,text,falsetext}``
If field exists and is empty, then return ``truetext``. Otherwise,
returns ``falsetext``. The field should be entered without ``$``.
``%ifdefempty{compilation,Album,Compilation}``
ifdefnotempty
-------------
``%ifdefnotempty{field,text}`` or ``%ifdefnotempty{field,text,falsetext}``
If field is not empty, then return ``truetext``. Otherwise, returns
``falsetext``. The field should be entered without ``$``.
``%ifdefnotempty{compilation,Compilation,Album}``
initial
-------
``%initial{text}``
Get the first character of a text in lowercase. The text is converted
to ASCII. All non word characters are erased.
``%initial{Schubert}`` → ``s``
left
----
``%left{text,n}``
Return the first “n” characters of “text”.
``%left{Schubert, 3}`` → ``Sch``
lower
-----
``%lower{text}``
Convert “text” to lowercase.
``%lower{SCHUBERT}`` → ``schubert``
nowhitespace
------------
``%nowhitespace{text,replace}``
Replace all whitespace characters with ``replace``. By default: a dash
(``-``)
``%nowhitespace{a b}`` → ``a-b``; ``%nowhitespace{a b, _}`` → ``a_b``
num
---
``%num{number,count}``
Pad decimal number with leading zeros.
``%num{7,3}`` → ``007``
replchars
---------
``%replchars{text,chars,replace}``
Replace the characters “chars” in “text” with “replace”.
``%replchars{Schubert,-,ue}`` → ``Sch-b-rt``
right
-----
``%right{text,n}``
Return the last “n” characters of “text”.
``%right{Schubert,3}`` → ``ert``
sanitize
--------
``%sanitize{text}``
Delete characters that are not allowed in most file systems.
``%sanitize{x:*?<>|/~&x}`` → ``xx``
shorten
-------
``%shorten{text}`` or ``%shorten{text,max_size}``
Shorten “text” on word boundarys.
``%shorten{Lorem ipsum dolor sit, 10}`` → ``Lorem``
time
----
``%time{date_time,format,curformat}``
Return the date and time in any format accepted by ``strftime``. For
example, to get the year, use ``%time{$added,%Y}``.
``%time{30 Nov 2024,%Y,%d %b %Y}`` → ``2024``
title
-----
``%title{text}``
Convert “text” to Title Case.
``%title{franz schubert}`` → ``Franz Schubert``
upper
-----
``%upper{text}``
Convert “text” to UPPERCASE.
``%upper{foo}`` → ``FOO``
Configuration file
==================
[selection]
source = /home/user/source
target = /home/user/target
source_as_target = False
[rename]
backup_folder = /tmp/backup
best_format = True
dry_run = False
; see --move, --copy or --no-rename
; “move”, “copy” or “no_rename”
move_action = move
; see --backup, --delete
; “backup”, “delete” or “do_nothing”
cleaning_action = do_nothing
[filters]
album_complete = False
album_min = 7
extension = mp3,m4a,flac,wma
genre_classical = Classical music,Opera,Symphony
field_skip = title
[template_settings]
classical = False
shell_friendly = False
no_soundtrack = False
[path_templates]
default_template = $ar_initial_artist/%shorten{$ar_combined_artist_sort}/%shorten{$ar_combined_album}%ifdefnotempty{ar_combined_year,_${ar_combined_year}}/${ar_combined_disctrack}_%shorten{$title}
compilation_template = _compilations/$ar_initial_album/%shorten{$ar_combined_album}%ifdefnotempty{ar_combined_year,_${ar_combined_year}}/${ar_combined_disctrack}_%shorten{$title}
soundtrack_template = _soundtrack/$ar_initial_album/%shorten{$ar_combined_album}%ifdefnotempty{ar_combined_year,_${ar_combined_year}}/${ar_combined_disctrack}_${artist}_%shorten{$title}
classical_template = $ar_initial_composer/$ar_combined_composer/%shorten{$ar_combined_work_top,48}_[%shorten{$ar_classical_performer,32}]/${ar_combined_disctrack}_%shorten{$ar_classical_title,64}%ifdefnotempty{acoustid_id,_%shorten{$acoustid_id,8}}
[cli_output]
; see --color or --no-color
color = True
debug = False
job_info = False
mb_track_listing = False
one_line = False
stats = True
verbose = False
[metadata_actions]
enrich_metadata = False
remap_classical = False
options:
-h, --help show this help message and exit
--config CONFIG Load a configuration file in INI format.
-v, --version show program's version number and exit
[selection]:
The following arguments are intended to select the audio files.
source A folder containing audio files or a single audio
file. If you specify a folder, the program will search
for audio files in all subfolders. If you want to
rename the audio files in the current working
directory, then specify a dot (“.”).
-t, --target TARGET Target directory
-a, --source-as-target
Use specified source folder as target directory
[rename]:
These options configure the actual renaming process.
-p, --backup-folder BACKUP_FOLDER
Folder to store the backup files in.
-B, --best-format Use the best format. This option only takes effect if
the target file already exists. `audiorename` now
checks the qualtity of the two audio files (source and
target). The tool first examines the format. For
example a FLAC file wins over a MP3 file. Then
`audiorename` checks the bitrate.
-d, --dry-run Don’t rename or copy the audio files.
move action:
-C, --copy Copy files instead of rename / move.
-M, --move Move / rename a file. This is the default action. The
option can be omitted.
-n, --no-rename Don’t rename, move, copy or perform a dry run. Do
nothing.
cleaning action:
The cleaning actions are only executed if the target file already exists.
-A, --backup Backup the audio files instead of deleting them. The
backup directory can be specified with the --backup-
folder option.
-D, --delete Delete the audio files instead of creating a backup.
[filters]:
The following options filter the music files that are renamed according to certain rules.
-F, --album-complete Rename only complete albums.
-m, --album-min ALBUM_MIN
Rename only albums containing at least X files.
-e, --extension EXTENSION
Extensions to rename.
--genre-classical GENRE_CLASSICAL
List of genres to be classical.
-s, --field-skip FIELD_SKIP
Skip renaming if field is empty.
[template_settings]:
-k, --classical Use the default format for classical music. If you use
this option, both parameters (--default and
--compilation) have no effect. Classical music is
sorted by the lastname of the composer.
-S, --shell-friendly Rename audio files “shell friendly”, this means
without whitespaces, parentheses etc.
--no-soundtrack Do not use the path template for soundtracks. Use
instead the default path template.
[path_templates]:
audiorename provides default path templates. You can specify your own path templates using the following options.
-f, --default, --format PATH_TEMPLATE
The default path template for audio files that are not
compilations or compilations. Use metadata fields and
functions to build the path template.
-c, --compilation PATH_TEMPLATE
Path template for compilations. Use metadata fields
and functions to build the path template.
--soundtrack PATH_TEMPLATE
Path template for a soundtrack audio file. Use
metadata fields and functions to build the path
template.
--format-classical PATH_TEMPLATE
Path template for classical audio file. Use metadata
fields and functions to build the path template.
[cli_output]:
This group contains all options that affect the output on the command line interface (cli).
-K, --color Colorize the standard output of the program with ANSI
colors.
--no-color Don’t colorize the standard output of the program with
ANSI colors.
-b, --debug Print debug informations about the single metadata
fields.
-j, --job-info Display informations about the current job. This
informations are printted out before any actions on
the audio files are executed.
-l, --mb-track-listing
Print track listing for Musicbrainz website: Format:
track. title (duration), e. g.: 1. He, Zigeuner (1:31)
2. Hochgetürmte Rimaflut (1:21)
-o, --one-line Display the rename / copy action status on one line
instead of two.
-T, --stats Show statistics at the end of the execution.
-V, --verbose Make the command line output more verbose.
[metadata_actions]:
-E, --enrich-metadata
Fetch the tag fields “work” and “mb_workid” from
Musicbrainz and save this fields into the audio file.
The audio file must have the tag field “mb_trackid”.
The give audio file is not renamed.
-r, --remap-classical
Remap some fields to fit better for classical music:
“composer” becomes “artist”, “work” becomes “album”,
from the “title” the work prefix is removed
(“Symphonie No. 9: I. Allegro” -> “I. Allegro”) and
“track” becomes the movement number. All overwritten
fields are safed in the “comments” field.
/home/jf/.cache/uv/builds-v0/.tmpc9CQj2/lib/python3.13/site-packages/ansicolor/ansicolor.py:507: SyntaxWarning: invalid escape sequence '\['
return re.sub("\033\[(?:(?:[0-9]*;)*)(?:[0-9]*m)", "", s)
Configuration files
Use the --config option to load a configuration file. The command
line arguments overwrite the corresponding options of the configuration
file.
audiorenamer --config /home/user/my-config.ini
It is also possible to load several configuration files. Values of the latter file overwrite the values of the first files.
audiorenamer --config base.ini --config overload.ini
Almost all command line arguments have a corresponding option in the
configuration file. audiorename implements a basic configuration
language which provides a structure similar to what’s found in Microsoft
Windows INI
files:
[selection]
source = /home/user/source
target = /home/user/target
source_as_target = False
[rename]
backup_folder = /tmp/backup
best_format = True
dry_run = False
; see --move, --copy or --no-rename
; “move”, “copy” or “no_rename”
move_action = move
; see --backup, --delete
; “backup”, “delete” or “do_nothing”
cleaning_action = do_nothing
[filters]
album_complete = False
album_min = 7
extension = mp3,m4a,flac,wma
genre_classical = Classical music,Opera,Symphony
field_skip = title
[template_settings]
classical = False
shell_friendly = False
no_soundtrack = False
[path_templates]
default_template = $ar_initial_artist/%shorten{$ar_combined_artist_sort}/%shorten{$ar_combined_album}%ifdefnotempty{ar_combined_year,_${ar_combined_year}}/${ar_combined_disctrack}_%shorten{$title}
compilation_template = _compilations/$ar_initial_album/%shorten{$ar_combined_album}%ifdefnotempty{ar_combined_year,_${ar_combined_year}}/${ar_combined_disctrack}_%shorten{$title}
soundtrack_template = _soundtrack/$ar_initial_album/%shorten{$ar_combined_album}%ifdefnotempty{ar_combined_year,_${ar_combined_year}}/${ar_combined_disctrack}_${artist}_%shorten{$title}
classical_template = $ar_initial_composer/$ar_combined_composer/%shorten{$ar_combined_work_top,48}_[%shorten{$ar_classical_performer,32}]/${ar_combined_disctrack}_%shorten{$ar_classical_title,64}%ifdefnotempty{acoustid_id,_%shorten{$acoustid_id,8}}
[cli_output]
; see --color or --no-color
color = True
debug = False
job_info = False
mb_track_listing = False
one_line = False
stats = True
verbose = False
[metadata_actions]
enrich_metadata = False
remap_classical = False
Metadata fields
Field name |
Category |
Description |
Examples |
|---|---|---|---|
acoustid_fingerprint |
music_brainz |
The Acoustic Fingerprint for the track. The fingerprint is based on the audio information found in a file, and is calculated using the Chromaprint software. |
|
acoustid_id |
music_brainz |
The AcoustID associated with the track. The AcoustID is the identifier assigned to an audio file based on its acoustic fingerprint. Multiple fingerprints may be assigned the same AcoustID if the fingerprints are similar enough. |
|
album |
common |
The title of the release. |
|
albumartist |
common |
The artist for the entire album, which may be different from the artists for the individual tracks. The artists primarily credited on the release, separated by the specified join phrases. |
|
albumartist_credit |
common |
The release-specific artist credit name, which may be a variation of the artist’s “canonical” name. |
|
albumartist_sort |
common |
The release artists sort names, separated by the specified join phrases. (e.g.: “Beatles, The”). |
|
albumartists |
common |
The album artists specifed as a list. |
|
albumartists_credit |
common |
The release-specific artists credit names, which may be a variation of the artist’s “canonical” names. |
|
albumartists_sort |
common |
The “sort name” of the artist for the entire album. |
|
albumdisambig |
common |
The disambiguation album field helps to distinguish between identically named albums. The album “Weezer” for example has the disambiguation comments “Red Album” and “Green Album”. |
|
albumstatus |
common |
The status describes how “official” a release is. |
|
albumtype |
common |
The primary MusicBrainz release group type; the MusicBrainz wiki has a list of type names. |
|
albumtypes |
common |
The MusicBrainz release group types; the MusicBrainz wiki has a list of type names. |
|
ar_classical_album |
common |
The field “work” without the movement suffix. For example: “Horn Concerto: I. Allegro” -> “Horn Concerto” |
|
ar_classical_performer |
common |
“ar_performer_short” or “albumartist” without the composer prefix: “Beethoven; Karajan, Mutter” -> “Karajan, Mutter” |
|
ar_classical_title |
common |
The movement title without the parent work prefix. For example “Horn Concerto: I. Allegro” -> “I. Allegro” |
|
ar_classical_track |
common |
If the title contains Roman numbers, then these are converted to arabic numbers with leading zeros. If no Roman numbers could be found, then the field “ar_combined_disctrack” is used. |
|
ar_combined_album |
common |
“album” without ” (Disc X)”. |
|
ar_combined_artist |
common |
The first non-empty value of the following list of fields: “albumartist” -> “artist” -> “albumartist_credit” -> “artist_credit” -> “albumartist_sort” -> “artist_sort”. If no value could be determined, then “Unknown” is assigned. The second artist after “feat.”, “ft.” or “vs.” is removed. |
|
ar_combined_artist_sort |
common |
The first non-empty value of the following list of fields: “albumartist_sort” -> “artist_sort” -> “albumartist” -> “artist” -> “albumartist_credit” -> “artist_credit”. If no value could be determined, then “Unknown” is assigned. The second artist after “feat.”, “ft.” or “vs.” is removed. |
|
ar_combined_composer |
common |
The first not empty field of this field list: “composer_sort”, “composer”, “ar_combined_artist” |
|
ar_combined_disctrack |
common |
Combination of disc and track in the format: disk-track |
|
ar_combined_soundtrack |
common |
Boolean flag which indicates if the audio file is a soundtrack |
|
ar_combined_work_top |
common |
The work on the top level of a work hierarchy. |
|
ar_combined_year |
common |
First “original_year” then “year”. |
|
ar_initial_album |
common |
First character in lowercase of “ar_combined_album”. Allowed characters: [a-z, 0, _], 0-9 -> 0, ? -> _. For example “Help!” -> “h”. |
|
ar_initial_artist |
common |
First character in lowercase of “ar_combined_artist_sort”. Allowed characters: [a-z, 0, _], 0-9 -> 0, ? -> _. For example “Brendel, Alfred” -> “b”. |
|
ar_initial_composer |
common |
First character in lowercase of “ar_combined_composer”. Allowed characters: [a-z, 0, _], 0-9 -> 0, ? -> _. For example “Ludwig van Beethoven” -> “l”. |
|
ar_performer |
common |
Performer names. |
|
ar_performer_raw |
common |
Raw performer names. |
|
ar_performer_short |
common |
Abbreviated performer names. |
|
arranger |
common |
A musician who creates arrangements. |
|
art |
common |
Legacy album art field. |
|
artist |
common |
The track artist names, separated by the specified join phrases. |
|
artist_credit |
common |
The track-specific artist credit name, which may be a variation of the artist’s “canonical” name. |
|
artist_sort |
common |
The “sort name” of the track artist. |
|
artists |
common |
A multi-value field containing the track artist names. |
|
artists_credit |
common |
The track-specific artists credit names, which may be a variation of the artist’s “canonical” names. |
|
artists_sort |
common |
The “sort name” of the track artists. |
|
asin |
common |
The Amazon Standard Identification Number - the number identifying the item on Amazon. |
|
barcode |
common |
The barcode assigned to the release. There are many different types of barcode, but the ones usually found on music releases are two: 1. Universal Product Code (UPC), which is the original barcode used in North America. 2. European Article Number (EAN). |
|
bitdepth |
audio |
The number of bits per sample in the audio encoding (an int). Only available for certain file formats (zero where unavailable). |
|
bitrate |
audio |
The number of bits per seconds used in the audio coding (an int). If this is provided explicitly by the compressed file format, this is a precise reflection of the encoding. Otherwise, it is estimated from the on-disk file size. In this case, some imprecision is possible because the file header is incorporated in the file size. |
|
bitrate_mode |
common |
The mode of the bitrate used in the audio coding (a string, eg. “CBR”, “VBR” or “ABR”). Only available for the MP3 file format (empty where unavailable). |
|
bpm |
common |
The number of beats per minute of the track. |
|
catalognum |
common |
A number assigned to the release by the label which can often be found on the spine or near the barcode. There may be more than one, especially when multiple labels are involved. |
|
catalognums |
common |
Multiple numbers assigned to the release by the label which can often be found on the spine or near the barcode. There may be more than one, especially when multiple labels are involved. |
|
channels |
audio |
The number of channels in the audio (an int). |
|
comments |
common |
The disambiguation comment entered to help distinguish one release from another (e.g.: Deluxe version with 2 bonus tracks). |
|
comp |
common |
Compilation flag. |
|
composer |
common |
The name of the composer. |
|
composer_sort |
common |
The composer name for sorting. |
|
copyright |
common |
The copyright message for the copyright holder of the original sound, beginning with a year and a space character. |
|
country |
common |
The country the release was issued in. |
|
date |
date |
The release date of the specific release. |
|
day |
date |
The release day of the specific release. |
|
disc |
common |
The number of the disc. |
|
disctitle |
common |
Mediums are always included in a release, and have a position in said release (e.g. disc 1 or disc 2). They have a format, like CD, 12” vinyl or cassette (in some cases this will be unknown), and can have an optional title (e.g. disc 2: The Early Years). |
|
disctotal |
common |
The total number of discs. |
|
encoder |
common |
The name of the person or organisation that encoded the audio file. This field may contain a copyright message, if the audio file also is copyrighted by the encoder. |
|
encoder_info |
common |
The name and/or version of the encoder used (a string, eg. “LAME 3.97.0”). Only available for some formats (empty where unavailable) |
|
encoder_settings |
common |
A guess of the settings used for the encoder (a string, eg. “-V2”). Only available for the MP3 file format (empty where unavailable). |
|
format |
audio |
A string describing the file format/codec. e.g., “MP3” or “FLAC” |
|
genre |
common |
Genres are currently supported in MusicBrainz as part of the tag system. |
|
genres |
common |
Genres are currently supported in MusicBrainz as part of the tag system. |
|
grouping |
common |
A content group, which is a collection of media items such as a CD boxed set. |
|
images |
common |
Cover art, also known as “album art” or “album artwork”, is artwork that provides a visual representation of a release. |
|
initial_key |
common |
The Initial key frame contains the musical key in which the sound starts. It is represented as a string with a maximum length of three characters. The ground keys are represented with “A”,”B”,”C”,”D”,”E”, “F” and “G” and halfkeys represented with “b” and “#”. Minor is represented as “m”. |
|
isrc |
common |
The International Standard Recording Code, abbreviated to ISRC, is a system of codes that identify audio and music video recordings. |
|
label |
common |
The label which issued the release. There may be more than one. |
|
language |
common |
The language a release’s track list is written in. The possible values are taken from the ISO 639-3 standard. |
|
languages |
common |
The language a release’s track list is written in. The possible values are taken from the ISO 639-3 standard. |
|
length |
audio |
The duration of the audio in seconds (a float). |
|
lyricist |
common |
The writer of the text or lyrics in the recording. |
|
lyrics |
common |
The lyrics of the song or a text transcription of other vocal activities. |
|
mb_albumartistid |
music_brainz |
MusicBrainz album artist ID. |
|
mb_albumartistids |
music_brainz |
MusicBrainz album artist IDs as a list. |
|
mb_albumid |
music_brainz |
MusicBrainz work ID. |
|
mb_artistid |
music_brainz |
MusicBrainz artist ID. |
|
mb_artistids |
music_brainz |
MusicBrainz artist IDs as a list. |
|
mb_releasegroupid |
music_brainz |
MusicBrainz releasegroup ID. |
|
mb_releasetrackid |
music_brainz |
MusicBrainz release track ID. |
|
mb_trackid |
music_brainz |
MusicBrainz track ID. |
|
mb_workhierarchy_ids |
music_brainz |
All IDs in the work hierarchy. This field corresponds to the field work_hierarchy. The top level work ID appears first. A slash (/) is used as separator. |
|
mb_workid |
music_brainz |
MusicBrainz work ID. |
|
media |
common |
A prototypical medium is one of the physical, separate things you would get when you buy something in a record store. |
|
month |
date |
The release month of the specific release. |
|
original_date |
date |
The release date of the original version of the album. |
|
original_day |
date |
The release day of the original version of the album. |
|
original_month |
date |
The release month of the original version of the album. |
|
original_year |
date |
The release year of the original version of the album. |
|
r128_album_gain |
r128 |
An optional gain for album normalization. EBU R 128 is a recommendation for loudness normalisation and maximum level of audio signals. |
|
r128_track_gain |
r128 |
An optional gain for track normalization. EBU R 128 is a recommendation for loudness normalisation and maximum level of audio signals. |
|
releasegroup_types |
music_brainz |
This field collects all items in the MusicBrainz’ API related to type: type, primary-type and `secondary-type-list. Main usage of this field is to determine in a secure manner if the release is a soundtrack. |
|
rg_album_gain |
rg |
ReplayGain Album Gain, see https://en.wikipedia.org/wiki/ReplayGain. |
|
rg_album_peak |
rg |
ReplayGain Album Peak, see https://en.wikipedia.org/wiki/ReplayGain. |
|
rg_track_gain |
rg |
ReplayGain Track Gain, see https://en.wikipedia.org/wiki/ReplayGain. |
|
rg_track_peak |
rg |
ReplayGain Track Peak, see https://en.wikipedia.org/wiki/ReplayGain. |
|
samplerate |
audio |
The sample rate as an integer number. |
|
script |
common |
The script used to write the release’s track list. The possible values are taken from the ISO 15924 standard. |
|
title |
common |
The title of the track. |
|
track |
common |
The number of the track on the disc. |
|
tracktotal |
common |
The total number of tracks on this disc. |
|
url |
common |
Uniform Resource Locator. |
|
work |
common |
The Musicbrainzs’ work entity. |
|
work_hierarchy |
music_brainz |
The hierarchy of works: The top level work appears first. As separator is this string used: –>. |
|
year |
date |
The release year of the specific release. |
|