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 compatible.

The scripting functions are available at these parts of Mp3tag:

The following scripting functions are available:

Replace

Command: $replace(string,from,to)
Example: $replace(%artist% - %album% - %track% - %title%,_,-)
This example replaces all underscores to dashes.

Remove invalid characters from filename

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 tracknumber with three digits.

Other functions

$add(x,y)	adds y to x.
$and(x,y)	returns true, if x and y are true (not 0 and not empty).
$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 ASCII-character no. x (0-255).
$div(x,y)	divides x by y.
$eql(x,y)	returns true, if x equals y.
$fmtNum(x)	formats number x with seperator for thousands according to current locale settings.
$geql(x,y)	returns true, if x is greater as or equal to y.
$get(x)	returns the value of the user-defined variable x. Only availabe at Export.
$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.
$left(x,n)	Leftmost n characters of text x.
$len(x)	Returns the length of string x.
$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.
$mid(x,n,i)	First i characters of text x, starting at character n.
$mod(x,y)	returns the remainder of x divided by y.
$mul(x,y)	multiplies x by y.
$neql(x,y)	returns true, if x not equal to y.
$not(x)	returns true, if x is 0 or empty.
$odd(x)	returns true, if x is odd.
$or(x,y)	returns true, if x or y is true (not 0 and not empty).
$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.
$rand()	Returns a pseudorandom number >= 0.
$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).
$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.
$sub(x,y)	substracts y from x.
$trim(x)	trims all leading and trailing whitespaces from the string x. The optinal second parameter specifies the character to trim.

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.

Back to main page