Scripting functions

Mp3tag features a set of built-in scripting functions which can be used at various places in the program. These functions offer advanced display and converting options and giving you the power to get the most out of Mp3tag.

I got the idea for implementing the scripting functions from my favourite audio player, foobar2000. I first used a different syntax, but now the syntax of both programs should be (almost) compatible.

The scripting functions are available in these parts of Mp3tag:

Characters with special functionality

[...] The contents of brackets are displayed only if at least one of the placeholders used inside the brackets has been found.
' Outputs raw text without parsing. This will output the contained string and ignore all reserved characters. If you want to output this character, please use ''.
[]$% You have to put a single quote around these reserved characters if you want to use them unparsed.
,() These characters must only be escaped when they are inside a scripting function.

The following scripting functions are available:

General functions

Note: Functions with a variable parameters (e.g., Replace) are limited to < 64 parameters.

Replace

Command: $replace(string,from,to) or $replace(string,from1,to1,from2,to2,...)
Example: $replace(%artist% - %album% - %track% - %title%,_,-)
This example replaces all underscores with dashes. You can provide additional pairs of from/to as parameters.

Remove invalid characters from file name/file paths

Command: $validate(filename,to)
Example: $validate(%artist% - %album% - %track% - %title%,-)
This example replaces all invalid characters (/?*"<>|:) with dashes.

Case conversion Normal

Command: $caps(string,...)
Example: $caps(%artist% - %album% - %track% - %title%)
This example converts the given string to normal case. The second parameter is optional and specifies additional characters that trigger upper case.
artist - ALBUM - 01 - tItle converts to Artist - Album - 01 - Title

Case conversion Normal (without changing uppercase characters)

Command: $caps2(string)
Example: $caps2(%artist% - %album% - %track% - %title%)
This example converts the given string to normal case without changing uppercase characters. The second parameter is optional and specifies additional characters that trigger upper case.
artist - ALBUM - 01 - tItle converts to Artist - ALBUM - 01 - TItle

Case conversion Sentence

Command: $caps3(string)
Example: $caps3(%artist% - %album% - %track% - %title%)
This example converts the given string to first-letter upper case. The second parameter is optional and specifies additional characters that trigger upper case.
artist - ALBUM - 01 - tItle converts to Artist - album - 01 - title

Case conversion UPPER

Command: $upper(string)
Example: $upper(%artist% - %album% - %track% - %title%)
This example converts the given string to upper case.
artist - ALBUM - 01 - tItle converts to ARTIST - ALBUM - 01 - TITLE

Case conversion lower

Command: $lower(string)
Example: $lower(%artist% - %album% - %track% - %title%)
This example converts the given string to lower case.
artist - ALBUM - 01 - tItle converts to artist - album - 01 - title

Pad decimal number with leading zeros

Command: $num(x,y)
Example: $num(%track%,3)
This example returns the track number with three digits.

Other functions

String functions
$ansi(x) returns the string x converted to the system codepage. This is useful for renaming files to ensure compatibility with software which doesn't support Unicode.
$char(x) returns the Unicode character for decimal code point x.
$cutLeft(x,n) removes the first n characters of string x and returns the result.
$cutRight(x,n) removes the last n characters of string x and returns the result.
$fmtNum(x) formats number x with separator for thousands according to current locale settings.
$folderdepth(x) returns the number of folders in path x.
$left(x,n) returns the leftmost n characters of string x.
$len(x) returns the length of string x.
$mid(x,i,n) returns the first n characters of text x, starting at character i. If n is ommited, the character at position i is returned.
$ord(x) returns the decimal Unicode code point of the first character of string x. Currently supports characters up to U+FFFF.
$repeat(x,n) returns the string x n times.
$regexp(x,expr,repl) replaces the pattern specified by the regular expression expr in the string x by repl. The fourth optional parameter enables ignore case (1) or disables the ignore case setting (0). Please note that you have to escape comma and other special characters in expr.
$reverse(x) reverses the order of the characters in string x.
$right(x,n) returns the rightmost n characters of text x.
$strchr(x,y) finds the first occurrence of character y in string x.
$strrchr(x,y) finds the last occurrence of character y in string x.
$strstr(x,y) finds the first occurrence of string y in string x.
$trim(x) trims all leading and trailing whitespace from the string x. The optional second parameter specifies the character to trim.
$trimLeft(x) trims all leading whitespace from the string x. The optional second parameter specifies the character to trim.
$trimRight(x) trims all trailing whitespace from the string x. The optional second parameter specifies the character to trim.
Boolean functions
$and(x,y) returns true if x and y are true.
$geql(x,y) returns true if x is greater than or equal to y.
$eql(x,y) returns true if x equals y.
$grtr(x,y) returns true if x is greater than y.
$if(x,y,z) if x is true, y is returned, otherwise z.
$if2(x,y) if x is true, x is returned, otherwise y.
$ifgreater(a,b,x,y) if number a is greater than number b, x is returned, otherwise y.
$iflonger(a,b,x,y) if string a is longer than number b, x is returned, otherwise y.
$isdigit(x) returns true if character x is a decimal number.
$leql(x,y) returns true if x is less than or equal to y.
$less(x,y) returns true if x is less than y.
$neql(x,y) returns true if x not equal to y.
$not(x) returns true if x is false.
$odd(x) returns true if x is odd.
$or(x,y) returns true if x or y is true.
Arithmetic functions (support up to 64 arguments)
$add(x,y) adds y to x.
$div(x,y) divides x by y.
$mod(x,y) returns the remainder of x divided by y.
$mul(x,y) multiplies x by y.
$rand() returns a pseudorandom number in the range 0 to 32767.
$sub(x,y) substracts y from x.
Variable operations
$get(x) returns the value of the user-defined variable x. Only available at Export.
$put(x,y) sets the value of the user-defined variable x to y and returns y. Only available at Export.
$puts(x,y) sets the value of the user-defined variable x to y and returns nothing. Only available at Export.
$getenv(x) returns the value of the environment variable x.
Metadata (including multiple tag fields)
$list(x,y,z) returns a list of all read tag fields and their values that stored in the file. The fields are prefixed by x, y is used as separator between field and value, and z is used as suffix after the tag field's value. Multiple values of a field are separated by ", ".
$meta(x) returns all values of field x (e.g. $meta(artist)). Multiple values of a field are separated by ", ".
$meta(x,n) returns the nth value of field x (where n starts at 0, e.g. $meta(artist,1)).
$meta_sep(x,sep) returns all values of field x (e.g. $meta_sep(artist,; )). Multiple values of a field are separated by sep.

Back to main page