Syntax reference for title formatting for version 0.8

The syntax 0.8 syntax is c-like one. So instructions have to be sepperated by semicolons, function arguments are comma-sepperated enclosed in parentheses and instruction blocks (for if-statetements) are enclosed in curly braces.

To activate the new 0.8 syntax, the first line of the script has to be "#script 1" (without quotes).

Text Handling

Strings have always to be enclosed in double-quotes. Strings are concated by "#" (eg. "pre"#"post" equals "prepost"). Following special characters can be created with escaping (there are various others, but they are useless in formatting-strings):

\n	newline
\t	tabulator
\"	double-quotes
\\	backslash

Variable Handling

Variables are typeless and don't need to be declared. Type-conversions are done automatically. The #= += -= *= /= short-forms are also allowed.

var = "2string";

  var += 4;

  print(var);

Prints "6";

Functions

Output

print(arg)

Outputs arg

Metadata handling

meta_test(field)	Returns 1 if field is set, otherwise 0
meta(field)	Returns the value of the metadata field
extra(techfield)	Returns tech info field techfield's value.

Tech info fields:

path	holds full file name with path
path_raw	holds full file name including path and protocol
filename	holds file name without extension
filename_ext	holds file name with extension
directoryname	holds the directory name
subsong	holds subsong index
foobar2000_version	holds foobar2000's version string
length	holds length of track in formatted form
length_seconds	holds length in seconds

Special fields (only aviable in playlist)

isplaying	holds '1' if file is currently playing and empty string otherwise.
ispaused	holds '1' if playback is paused, empty string otherwise.
playlist_number	holds playlist index of specified item.
playlist_total	holds number of files in playlist.
playlist_name	holds name of playlist containing specified item.

Special fields (only aviable in status bar, window title and copy command)

time_elapsed	holds elapsed time
time_remaining	holds remaining time until track ends
time_total	holds total length of track
time_elapsed_seconds	holds elapsed time in seconds
time_remaining_seconds	holds remaining time in seconds
time_total_seconds	holds total track length in seconds
ispaused	holds '1' if playback is paused and empty string otherwise

time_total / time_total_seconds get data from playback core while length% / length_seconds get data from database, in some rare cases either of them may be more reliable.
You can see all metadata and tech info fields in file info box.

Colors (playlist and status bar only)

set_color(r,g,b)	set text color; will invert the color on selected fields
set_color(r,g,b,sr,sg,sb)	set text color to r,g,b on non-selected fields and to sr,sg,sb on selected fields
set_color()	reset to default color

Right-aligned text (playlist and status bar only)

Output a tab character ("\t") to indicate right-aligned text (e.g. track length).

Functions

$abbr(x)	Creates abbreviation of x.	"$abbr(%album%)" - will convert album name of "Final Fantasy VI" to "FFVI"
$abbr(x,y)	Creates abbreviation of x if x is longer than y characters; otherwise inserts full value of x.	$abbr(%album%,10)
$add(x,y...)	Adds multiple integral numbers (x+y+...). Accepts any amount of parameters.	$add(%TRACKNUMBER%,$mul(%DISC%,100))
$and(x,y...)	Performs logical AND operation on parameters. For use with $if()-type functions and other logical operators.
$ansi(x)	Converts x to system codepage and back. Any characters that aren't present in the system codepage will be removed / replaced. Useful for mass-renaming files to ensure compatibility with non-unicode-capable software.
$blend(a,b,c,d)	Generates a color in c/d between colors a and b.	$blend($rgb(0,0,0),$rgb(255,255,255),%_time_elapsed%,%_time_total%)
$caps(x)	Converts first letter in every word of x to uppercase, and all other letters to lowercase.	"$caps(blah BLAH)" -> "Blah Blah"
$caps2(x)	Similar to $caps, but leaves uppercase letters as they are.	"$caps2(blah BLAH)" -> "Blah BLAH"
$char(x)	Inserts Unicode character no. x.	"$char(3)" produces the character controlling color codes in playlist
$crlf()	Inserts end-of-line (carrier return / linefeed) code. Useful for multiline scripts (e.g. system tray tooltip).	$crlf()
$cut(a,b)	Returns b first left characters from a.	$cut(%title%,5)
$directory(x), $directory(x,n)	Extracts directory name from file path x, optionally goes up by n directory levels.	$directory(%_path%,2)
$div(x,y)	Divides integral number x by integral number y.	$div(%TRACKNUMBER%,100)
$ext(x)	Extracts extension from file path / file name	$ext(%_path%)
$filename(x)	Extracts file name from full path.	$filename(%_path%)
$fix_eol(x)	Scans x for end-of-line marker (CR/LF), if found - truncates and appends " (...)".
$fix_eol(x,y)	Scans x for end-of-line marker (CR/LF), if found - truncates and appends y.
$greater(x,y)	Compares two integral numbers, tests if x>y. For use with $if()-type functions and other logical operators.	$if($greater(%TRACKNUMBER%,100),$div(%TRACKNUMBER%,100),%DISC%)
$hex(x)	Converts integral number x from decimal to hexdecimal notation.	$hex(%_playlist_number%)
$hex(x,y)	Converts integral number x from decimal to hexdecimal notation, pads with zeros to y digits.	$hex(%_playlist_number%,3)
$if(a,b,c)	If a contains at least one valid tag, executes/displays b, otherwise executes/returns c.	"$if(%artist%,%artist%,unknown artist)" will return artist name if present; otherwise will return "unknown artist"; note that "$if(a,a,)" is equivalent to "[a]" (see below)
$if2(a,b)	Same as $if(a,a,b).	$if2(%title%,%_filename%)
$if3(a,b,c,..)	Returns first of items being true/non-empty.
$ifgreater(a,b,c,d)	If number a is greater than number b, return/execute c, otherwise return/execute d.
$iflonger(a,b,c,d)	If string a is longer than b characters, return/execute c, otherwise return/execute d.
$insert(a,b,n)	Inserts string b into string a after n characters.
$left(a,b)	Returns b first left characters from a.	$left(%title%,5)
$len(x)	Returns length of string x in characters.
$len2(x)	Returns length of string x in characters, respecting double-width character rules (double-width characters will be counted as two).
$longer(x,y)	Compares two strings, tests if x is longer than y. For use with $if()-type functions and other logical operators.
$lower(x)	Converts x to lowercase.	$lower(%title%)
$longest(a,b,c,....)	Compares parameters: a,b,c... and returns the longest one.	$longest(%title%,%comment%)
$mod(x,y)	Calculates remainder of x divided by y.	$mod($rand(),10)
$mul(x,y...)	Multiplies integral numbers (xy...). Accepts any amount of parameters.	$add(%TRACKNUMBER%,$mul(%DISC%,100))
$muldiv(x,y,z)	Multiplies integral numbers x by y, then divides by integral number z.
$min(x,y...)	Performs integral number comparison and returns smallest of x, y... . Accepts any amount of parameters.
$max(x,y...)	Performs integral number comparison and returns largest of x, y... . Accepts any amount of parameters.
$num(x,y)	Returns x as decimal number and pads with zeros up to y characters (useful for track numbers).	$num(%tracknumber%,2)
$not(x)	Performs logical NOT operation on parameter. For use with $if()-type functions and other logical operators.
$or(x,y...)	Performs logical OR operation on parameters. For use with $if()-type functions and other logical operators.
$pad(x,y), $pad_right(x,y)	Pads x with spaces up to y characters.
$pad(x,y,z), $pad_right(x,y,z)	Pads x with z character up to y characters.
$padcut(x,y), $padcut_right(x,y)	Pads x to y characters or truncates to y if longer.
$progress(a,b,c,d,e), $progress2(a,b,c,d,e)	Creates progress bar: a contains position, b contains range, c progress bar length in characters, d and e are characters to build progress bar with. $progress2() produces different appearance.	"$progress(%_time_elapsed_seconds%, %_time_total_seconds%, 20,'#','=')" produces "====#===============", the # character is moving with playback position
$rand()	generates a random number in range from 0 to 2³²-1	$mod($rand(),10)
$repeat(x,y)	Repeats x y times.
$replace(a,b,c)	Replaces all occurrences of string b in string a with string c. Additionally, you can specify more parameters, $replace(a,b1,c1,b2,c2,b3,c3....), and all bX will re replaced with corresponding cX.
$right(a,b)	Returns b first right characters from a.	$right(%title%,5)
$roman(x)	Converts number x from decimal to roman notation.	$roman(%tracknumber%)
$rgb(a,b,c), $rgb(a,b,c,d,e,f)	Converts decimal color values to color codes (see colors above).
$shortest(a,b,c,....)	Compares parameters: a,b,c... and returns the shortest one.	$shortest(%title%,%comment%)
$strchr(x,y)	Finds first occurrence of character y in string x.
$strrchr(x,y)	Finds last occurrence of character y in string x.
$strstr(x,y)	Finds first occurrence of string y in string x.
$sub(x,y)	Subtracts integral number y from integral number x.
$strcmp(x,y)	Compares two strings, case-sensitive. For use with $if()-type functions and other logical operators.
$stricmp(x,y)	Compares two strings, non-case-sensitive. For use with $if()-type functions and other logical operators.
$substr(a,b,c)	Returns substring of string a, starting from b-th character and ending at c-th character.	$substr('blah',1,2) returns 'bl'
$select(n,a,b,c,....)	Returns n-th of a,b,c... parameters.
$trim(a)	Removes leading/trailing spaces from a.	$trim(%comment%)
$tab(), $tab(n)	Generates one ($tab()) or n ($tab(n)) tab characters, useful for separating colums in playlist.	$tab()
$transition(a,b,c)	Generates color codes between characters in string a, interpolating colors from b to c.	$transition(%TITLE%,$rgb(0,0,0),$rgb(255,255,255))
$upper(x)	Converts x to uppercase.	$upper(%title%)
$xor(x,y)	Performs logical XOR operation on parameters. For use with $if()-type functions and other logical operators.

Variable operations

$put(name,text)	Sets variable named <name> to <text> and returns <text>.	"$put(x,blah)" sets variable x to 'blah' and returns 'blah'
$puts(name,text)	Same as $put(name,text), but returns empty string.
$get(name)	Returns value of variable <name>.	"$puts(x,blah)$get(x)$get(x)" will return 'blahblah'

Variables allow you to store intermediate results of text processing in order to reduce size of your formatting string.
Variables are not kept between instances of title formatting process and modifying actual file info with them is not possible.

Other

[ .... ]	displays contents of brackets only if at least one of fields referenced inside has been found	"%artist% - [%album% / ]%title%" will hide [] block if album field is not present; note that mixing brackets with $functions may give unpredictable results and should be avoided (use $if() instead)
' (single quotation mark)	outputs raw text without parsing	'blah$blah%blah[][]' will output the contained string and ignore all reserved characters (%,$,[,]) in it; you can use this feature to insert square brackets for an example
//	comments, can be placed only at the beginning of new line, they prevent any characters following them until the end of line from being parsed
end-of-line characters	ignored; use $char() to force weird character sequences if you need them; you can safely split your string into multiple lines without affecting its output