Format Strings and Placeholders
Mp3tag uses format strings in various of its features to describe the structure of file names and imported data. A format string is built of either standard text (e.g., Music), placeholders (such as %artist%, %title%, …), or backslash characters \ that usually denote directory structures (optionally starting with a drive specifier e.g., D:\).
Format strings are used in two ways in Mp3tag, matching format strings and generating format strings.
Matching format strings are used for simple pattern matching of existing strings, e.g., file names to import tags from or lines in a text file that describe tag contents to be imported.
Generating format strings are used to create new strings, e.g., file names when renaming, field contents when formatting tag fields, data when exporting, but also file names for playlists or cover images that are parameterized with tag contents. Generating format strings can be combined with scripting functions.
Characters with Special Functionality
Some characters have special functionality in generating format strings and need to be treated with extra care. If you experience some unexpected behavior when using format strings, check if some of the rules listed below apply.
[...] |
The contents of brackets are displayed only if at least one of the placeholders used inside the brackets has been found. An example use case is creating disc subfolders: [CD$num(%discnumber%,1)\] results in CD1\ if DISCNUMBER is 1 or an empty string if it’s not filled. |
' |
Outputs raw text without parsing. This will output the contained string and ignore all reserved characters. If you want to output this character please mask it with an extra one ''. |
[]$% |
You need to put the single quote around these reserved characters if you want to use them unparsed. |
Tag and Metadata Information
Mp3tag supports flexible tagging, which means that the names of the tag fields are not fixed. You can reference any supported field which is, e.g., listed in the extended tags dialog as FIELDNAME via a placeholder %fieldname%.
Some examples:
| Placeholder | Description |
|---|---|
%artist% |
Artist |
%album% |
Album |
%comment% |
Comment |
%genre% |
Genre |
%title% |
Title |
%track% |
Track Number |
%year% |
Year |
Technical Information
Technical information fields begin with an underscore %_ are read-only and may also be used in the File List, format strings, filters, and export configurations, but not in the Tag Panel.
| Placeholder | Description |
|---|---|
%_bitrate% |
Bitrate in kbit/s |
%_bitspersample% |
Bits per sample (available only for some audio formats) |
%_codec% |
Codec |
%_cover_description% |
Description of first cover art in the tag of the file |
%_cover_mimetype% |
Mimetype of first cover art in the tag of the file |
%_cover_size% |
Size of first cover art in the tag of the file in bytes |
%_cover_type% |
Cover type of first cover art in the tag of the file |
%_cover_height% |
Cover height of first cover art in the tag of the file in pixels |
%_cover_width% |
Cover width of first cover art in the tag of the file in pixels |
%_covers% |
Count of cover art in the tag of the file |
%_id3v2_character_encoding% |
Encoding of the ID3v2 text frames of the file |
%_id3v2_unknown_frames% |
Set to 1 if the ID3v2 tag contains any of the unsupported ID3v2 frames |
%_length% |
Length (formatted) |
%_length_seconds% |
Length (in seconds) |
%_mode% |
Mode |
%_samplerate% |
Sample rate |
%_subsong% |
Chapter index for files with chapters |
%_subsong_count% |
Chapter count for files with chapters |
%_tag% |
Available tag types in file |
%_tag_read% |
Displayed tag type |
%_tag_size% |
Size of all tags in bytes |
%_tag_size_appended% |
Size of all appended tags in bytes |
%_tag_size_prepended% |
Size of all prepended tags in bytes |
%_tool% |
Additional codec information (not available for all supported audio formats) |
%_vbr% |
Bitrate type or compression profile |
%_video_bitrate% |
Video bitrate for MP4/M4V/MKV video files |
%_video_codec% |
Video codec for MP4/M4V/MKV video files |
%_video_height% |
Video height for MP4/M4V/MKV video files |
%_video_width% |
Video width for MP4/M4V/MKV video files |
File Name and Path Information
| Placeholder | Description |
|---|---|
%_directory% |
Name of the file’s parent folder |
%_extension% |
File extension |
%_filename% |
File name without extension |
%_filename_ext% |
File name with extension |
%_folderpath% |
Path without file name |
%_path% |
File name with path |
%_parent_directory% |
Name of the file’s grandparent folder |
%_volume% |
Volume label |
%_workingdir% |
Name of current working directory |
%_workingpath% |
Path of current working directory |
File Properties
| Placeholder | Description |
|---|---|
%_file_create_date% |
Short creation date |
%_file_create_datetime% |
Long creation date |
%_file_create_datetime_raw% |
Long creation date (unformatted) |
%_file_mod_date% |
Short modification date |
%_file_mod_datetime% |
Long modification date |
%_file_mod_datetime_raw% |
Long modification date (unformatted) |
%_file_size% |
File size in human readable format |
%_file_size_bytes% |
File size in bytes |
%_file_size_kb% |
File size in kilobytes |
%_file_size_mb% |
File size in megabytes |
Dynamic Information
| Placeholder | Description |
|---|---|
%_app% |
Mp3tag, e.g. Mp3tag v3.22 |
%_counter% |
Current selection index of the file (ascending from 1) |
%_date% |
Short date |
%_datetime% |
Long date |
Export
| Placeholder | Description |
|---|---|
%_filename_rel% |
File path with extension, relative to Export output file if output and track files are on same drive, else absolute |
%_folderpath_rel% |
Folder path relative to Export output file if output and track files are on same drive, else absolute |
%_crc% |
CRC32 value of file content |
%_md5% |
MD5-Hash of the file (slow!) |
%_md5audio% |
MD5-Hash of the audio part of the file (fast and natively supported for FLAC and WavPack, slow and dynamically calculated for ID3- and/or APE-only tagged files) |
%_max_counter% |
Maximum value of counter of the last closed loop. |
Global placeholders for Export
Providing totals for the preceding $loop/$loopend
| Placeholder | Description |
|---|---|
%_total_files% |
Total number of files |
%_total_size% |
Total file size (formatted output) |
%_total_size_raw% |
Total file size in bytes |
%_total_time% |
Total playing time (formatted output) |
%_total_time2% |
Total playing time (formatted output without days) |
%_total_time_raw% |
Total playing time in seconds |
Playlist
| Placeholder | Description |
|---|---|
%_playlist_filename% |
File name of current playlist without extension |
%_playlist_filename_ext% |
File name of current playlist with extension |
%_playlist_folderpath% |
Folderpath of current playlist |