Scripting Functions

Mp3tag offers various built-in scripting functions, which can be used at various places in the program.

These functions offer advanced display and converting options and are to be used in combination with format strings and placeholders.

Wherever a string parameter can be used, a generating format string can be used and is evaluated before being passed as parameter to the scripting function. Nesting of scripting functions is also possible.

Note that characters with special functionality apply. This implies that you can enclose parameters in ' to pass them as raw text without parsing. Functions with variable parameter count (e.g., $replace) are limited to < 64 parameters.

The following scripting functions are available:

String Functions
Boolean Functions
Arithmetic Functions
Variable Functions
Metadata Functions

String Functions

Function	Description
`$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.
`$caps(x,y)`	returns the given string x as mixed case. The second parameter y is optional and specifies the characters that trigger upper case.
`$caps2(x,y)`	returns the given string x as mixed case without changing uppercase characters. The second parameter y is optional and specifies the characters that trigger upper case.
`$caps3(x,y)`	returns the given string x as first-letter upper case. The second parameter y is optional and specifies additional characters that trigger upper case.
`$char(x)`	returns the Unicode character for decimal code point x.
`$cutLeft(x,n)`	removes n characters from the left side of string x and returns the remaining string.
`$cutRight(x,n)`	removes n characters from the right side of string x and returns the remaining string.
`$distance(x,y)`	computes the edit distance between strings x and y.
`$fmtDuration(x,y,h,ms)`	formats number x as a duration string. The optional parameter y decides how the number is intepreted, where `m` is minutes, `s` is seconds (default), and `ms` is milliseconds. Optional parameters h and ms set to `1` enable the display of hours and milliseconds respectively in the formatted duration string.
`$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.
`$lower(x)`	returns the given string x in lower case.
`$mid(x,i,n)`	returns n characters of string x, starting at character position i. If n is omitted, the character at position i is returned.
`$num(x,y)`	returns string x interpreted as decimal number, padded with leading zeros from the left up to y digits. It ignores anything from the first non-numeric character, or results in 0 if the string is not numeric.
`$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,e,r,c)`	replaces the pattern specified by the regular expression e in the string x by r. The optional fourth parameter c enables ignore case (`1`) or disables the ignore case setting (`0`). Please note that you have to escape comma and other special characters in e.
`$replace(x,y,z)`	returns the string x with all occurrences of string y replaced by string z. Supports multiple parameter pairs y and z.
`$reverse(x)`	reverses the order of the characters in string x.
`$right(x,n)`	returns the rightmost n characters of text x.
`$strcmp(x,y)`	compares strings x and y case-sensitively.
`$stricmp(x,y)`	compares strings x and y case-insensitively.
`$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,c)`	trims all leading and trailing whitespace from the string x. The optional second parameter c specifies the character to trim.
`$trimLeft(x,c)`	trims all leading whitespace from the string x. The optional second parameter c specifies the character to trim.
`$trimRight(x,c)`	trims all trailing whitespace from the string x. The optional second parameter c specifies the character to trim.
`$upper(x)`	returns the given string x in upper case.
`$validate(x,y)`	returns the given file name/path x with all invalid characters `/?*"<>\|:` replaced by the string y.

Boolean Functions

Function	Description
`$and(x,y)`	returns true if x and y are true.
`$eql(x,y)`	returns true if x equals y. If x and y are strings, they’re compare case-insensitively.
`$geql(x,y)`	returns true if x is greater than or equal to 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 (or any additional argument given) is true.

Arithmetic Functions

Integer arithmetic only, operations support up to 64 arguments.

Function	Description
`$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.
`$sub(x,y)`	subtracts y from x.
`$uuid()`	creates a 128-bit universally unique identifier (UUID)

Variable Functions

Function	Description
`$getenv(x)`	returns the value of the environment variable x. Use `MP3TAGAPP` for the app directory and `MP3TAGAPPDATA` for the configuration directory paths.

Metadata Functions

Function	Description
`$list(x,y,z)`	returns a list of all read tag fields and their values that are 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`.