foobar2000

# Syntax reference for title formatting for version 0.7

## Fields

%fieldname% | inserts metadata field named <fieldname> | %artist%
%__fieldname% | inserts tech info field named <fieldname> | %__bitrate%
%_path% | inserts full file name with path |
%_path_raw% | inserts full file name including path and protocol |
%_filename% | inserts file name without extension |
%_filename_ext% | inserts file name with extension |
%_directoryname% | inserts the directory name |
%_subsong% | inserts subsong index |
%_foobar2000_version% | inserts foobar2000's version string |
%_length% | inserts length of track in formatted form |
%_length_seconds% | inserts length in seconds |

## Special fields (playlist)

%_isplaying% | Returns '1' if file is currently playing and empty string otherwise. |
%_ispaused% | Returns '1' if playback is paused, empty string otherwise. |
%_playlist_number% | Returns playlist index of specified item. |
%_playlist_total% | Returns number of files in playlist. |
%_playlist_name% | Returns name of playlist containing specified item. |

## Special fields (status bar, window title and copy command)

%_time_elapsed% | returns elapsed time |
%_time_remaining% | returns remaining time until track ends |
%_time_total% | returns total length of track |
%_time_elapsed_seconds% | returns elapsed time in seconds |
%_time_remaining_seconds% | returns remaining time in seconds |
%_time_total_seconds% | returns total track length in seconds |
%_ispaused% | returns '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.
- All %...% fields automatically truncate multiline strings, if you don't want that, see $meta() function.
- You can see all metadata (%blah%) and tech info (%__blah%) fields in file info box.

## Colors (playlist and status bar only)

XXXXXX | set text color to XXXXXX, where XXXXXX is new text color in hex; will invert the color on selected fields |
XXXXXX|YYYYYY | set text color to XXXXXX on non-selected fields and to YYYYYY on selected fields |
| reset to default color |

## Right-aligned text (playlist and status bar only)

- use tab character (or "$char(9)") 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. |
$info(x) | Returns tech info field named x. Doesn't truncate end-of-line markers (%__field% does). | "$info(bitrate)" is same as "%__bitrate%"
$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 (x*y*...). 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. |
$meta(x) | Inserts value of metadata field named x. Doesn't truncate end-of-line markers (%field% does). | "$meta(artist)" is same as "%artist%"
$meta(x,y) | Returns y-th value for metadata field named x, used for multiple values per one field name. Doesn't truncate end-of-line markers (%field% does). | "multiple artists - $meta(artist,1), $meta(artist,2)"
$meta_sep(x,y), $meta_sep(x,y,z) | Returns metadata field named x, with custom separators for multiple values. | "$meta(artist,', ',' and ')" for three artists named A, B, C will produce this - "A, B and C"
$meta_num(x) | Returns number of present values for metadata field x. |
$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 232-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 |