Scripting functions

Mp3tag features a set of built-in scripting functions which can be used at various places through the program. These functions are offering 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 at these parts of Mp3tag:

The following scripting functions are available:

Replace

Command: $replace(string,from,to) or $replace(string,from1,to1,from2,to2,...)
Example: $replace(%artist% - %album% - %track% - %title%,_,-)
This example replaces all underscores to 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 (/?*"<>|:) to 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 triggers 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 triggers 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 triggers 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 at renaming files to ensure compatibility with software which doesn't support Unicode.
$char(x)	returns Unicode character with code x.
$fmtNum(x)	formats number x with seperator for thousands according to current locale settings.
$left(x,n)	Leftmost n characters of text x.
$len(x)	Returns the length of string x.
$mid(x,i,n)	First n characters of text x, starting at character i. If n is ommited, the character on position i is returned.
$ord(x)	returns the code of character x.
$repeat(a,n)	Returns the string a n times.
$regexp(what,expr,repl)	Replaces the pattern specified by the regular expression expr in the string what 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 (see end of this document).
$reverse(what)	Reverses the order of the characters in the given string.
$right(x,n)	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 whitespaces 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 as or equal to y.
$eql(x,y)	returns true, if x equals y.
$grtr(x,y)	returns true, if x is greater as 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 lesser as or equal to y.
$less(x,y)	returns true, if x is lesser as 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

$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 >= 0.
$sub(x,y)	substracts y from x.

Variable operations

$get(x)	returns the value of the user-defined variable x. Only availabe at Export.
$put(x,y)	sets the value of the user-defined variable x to y and returns y. Only availabe at Export.
$puts(x,y)	sets the value of the user-defined variable x to y and returns nothing. Only availabe at Export.

Metadata (including multiple tag fields)

$meta(x)	returns all values of field x (e.g. $meta(artist)). If multiple values of that field exist, they are separated with ", ".
$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 $meta_sep(artist,; ). If multiple values of that field exist, they are separated with sep.

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 the single quote around these reserved characters if you want to use them unparsed. The same applies to parentheses in parameters to scripting functions.

Back to main page