Field remappings

Some of the fields accessible through %name% are remapped to other values to make writing titleformat scripts more convenient.

Metadata

%album artist%

Defined as $if3($meta(album artist),$meta(artist),$meta(composer),$meta(performer)).

%album%

Defined as $if3($meta(album),$meta(venue)).

%artist%

Defined as $if3($meta(artist),$meta(album artist),$meta(composer),$meta(performer)).

%disc%

Returns the discnumber. The discnumber is taken from the discnumber tag; if that does not exist, it is taken from the disc tag. If neither exist, the field is undefined.

This is equivalent to the %discnumber% remapping.

%discnumber%

Returns the discnumber. The discnumber is taken from the discnumber tag; if that does not exist, it is taken from the disc tag. If neither exist, the field is undefined.

This is equivalent to the %disc% remapping.

%track artist%

Defined as $meta(artist), if $meta(album artist) is different than $meta(artist), otherwise this field is empty.

%title%

Defined as $if2($meta(title),%_filename%). Returns the title tag if available, otherwise it returns the filename excluding the extension.

%track%

Returns the tracknumber padded to two digits from the left with zeroes. The tracknumber is taken from the tracknumber tag; if that does not exist, it is taken from the track tag. If neither exist, this field is undefined.

This is equivalent to the %tracknumber% remapping.

%tracknumber%

Returns the tracknumber padded to two digits from the left with zeroes. The tracknumber is taken from the tracknumber tag; if that does not exist, it is taken from the track tag. If neither exist, this field is undefined.

This is equivalent to the %track% remapping.

Technical information

%bitrate%

Defined as $if2($info(bitrate_dynamic),$info(bitrate)). Returns the current bitrate, if available, otherwise it returns the average bitrate. If neither is available, nothing is returned.

%channels%

Defined as $channels(). Returns the number of channels in text form; returns "mono" and "stereo" instead of "1" and "2".

%filesize%

Defined as %_filesize%. Returns the filesize in bytes.

%samplerate%

Defined as $info(samplerate). Returns the samplerate in Hz.

%codec%

Defined as $codec().

Special fields

%playlist_number%

Defined as $num(%_playlist_number%,$len(%_playlist_total%)). Returns the position of the track as index into the playlist. The first track has index 1. The index is padded from the left with zeroes to the same number of digits as the last track.

Control flow

The functions in this section can be used to conditionally execute statements.

[...] (conditional section)

Evaluates the expression between [ and ]. If it has the truth value true, its string value and the truth value true are returned. Otherwise an empty string and false are returned.

Example: [%artist%] returns the value of the artist tag, if it exists. Otherwise it returns nothing, when artist would return "?".

$if(cond,then)

If cond evaluates to true, the then part is evaluated and its value returned. Otherwise, false is returned.

$if(cond,then,else)

If cond evaluates to true, the then part is evaluated and its value returned. Otherwise, the else part is evaluated and its value returned.

$if2(a,else)

Like $if(a,a,else) except that a is only evaluated once.

$if3(a1,a2,...,aN,else)

Evaluates arguments a1 ... aN, until one is found that evaluates to true. If that happens, its value is returned. Otherwise the else part is evaluated and its value returned.

$ifgreater(n1,n2,then,else)

Compares the integer numbers n1 and n2, if n1 is greater than n2, the then part is evaluated and its value returned. Otherwise the else part is evaluated and its value returned.

$iflonger(s1,s2,then,else)

Compares the length of the strings s1 and s2, if s1 is longer than s2, the then part is evaluated and its value returned. Otherwise the else part is evaluated and its value returned.

$select(n,a1,...,aN)

If the value of n is between 1 and N, an is evaluated and its value returned. Otherwise false is returned.

Arithmetic functions

The functions in this section can be used to perform arithmetic on integer numbers. A string will be automatically converted to a number and vice versa. The conversion to a number uses the longest prefix of the string, that can be interpreted as number. Leading whitespace is ignored.

Example: "c3po" -> 0, " -12" -> -12, but "- 12" -> 0

$add(a,b)

Adds a and b.

Can be used with an arbitrary number of arguments. $add(a,b,...) is the same as $add($add(a,b),...).

$div(a,b)

Divides a through b. If b evaluates to zero, it returns a.

Can be used with an arbitrary number of arguments. $div(a,b,...) is the same as $div($div(a,b),...).

$greater(a,b)

Returns true, if a is greater than b, otherwise false.

$max(a,b)

Returns the maximum of a and b.

Can be used with an arbitrary number of arguments. $max(a,b,...) is the same as $max($max(a,b),...).

$min(a,b)

Returns the minimum of a and b.

Can be used with an arbitrary number of arguments. $min(a,b,...) is the same as $min($min(a,b),...).

$mod(a,b)

Computes the remainder of dividing a through b. The result has the same sign as a. If b evaluates to zero, the result is a.

Can be used with an arbitrary number of arguments. $mod(a,b,...) is the same as $mod($mod(a,b),...).

$mul(a,b)

Multiplies a and b.

Can be used with an arbitrary number of arguments. $mul(a,b,...) is the same as $mul($mul(a,b),...).

$muldiv(a,b,c)

Multiplies a and b, then divides by c. The result is rounded to the nearest integer.

$rand()

Generates a random number in the range from 0 to 2³²-1.

$sub(a,b)

Subtracts b from a.

Can be used with an arbitrary number of arguments. $sub(a,b,...) is the same as $sub($sub(a,b),...).

Boolean functions

The functions in this section can be used to work with truth values (true and false), which have no explicit representation in titleformat scripts. They do not return a string or number value. You can use them for more complex conditions with $if and related functions.

$and(...)

Logical And of an arbitrary number of arguments. Returns true, if and only if all arguments evaluate to true.

Special case: $and(x,y) is true, if both x and y are true. Otherwise it is false.

$or(...)

Logical Or of an arbitrary number of arguments. Returns true, if at least one argument evaluates to true.

Special case: $or(x,y) is true, if x or y is true, or if both are true. Otherwise it is false.

$not(x)

Logical Not. Returns false, if x is true, otherwise it returns true.

$xor(...)

Logical Exclusive-or of an arbitrary number of arguments. Returns true, if an odd number of arguments evaluate to true.

Special case: $xor(x,y) is true, if one of x and y is true, but not both. Otherwise it is false.

Color functions

$blend(color1,color2,part,total)

Returns a color that is a blend between color1 and color2. If part is smaller than or equal to zero, color1 is returned. If part is greater than or equal to total, color2 is returned. Otherwise a blended color is returned that is part parts color1 and total-part parts color2. The blending is performed in the RGB color space.

$rgb()

Resets the text color to the default color.

$rgb(r,g,b)

Sets the color for text. r, g and b are the red, green and blue component of the color for unselected text. The color for selected text is set to the inverse color.

$rgb(r1,g1,b1,r2,g2,b2)

Sets the color for text. r1, g1 and b1 are the red, green and blue component of the color for unselected text. r2, g2 and b2 are the red, green and blue component for the color of selected text.

$transition(string,color1,color2)

Inserts color codes into string, so that the first character has color1, the last character has color2, and intermediate characters have blended colors. The blending is performed in the RGB color space. Note that color codes are additional characters that will also be counted by string manipulation functions. For example, if you need to truncate a string, you should do this before applying $transition.

$hsl(h,s,l)

Sets the color for text in the HSL colorspace. h, s and l are the hue, saturation, and lightness of the color for unselected text. The color for selected text is set to the inverse color. The ranges of h, s, and l are from 0 to 255.

Now playing info

The following functions and fields are usable for scripts used with the currently playing item, for example the status bar, the main window title and the copy command script.

Special fields

%_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.

Playlist info

The following functions and fields are usable for playlist scripts.

Special fields

%isplaying%

Returns "1" if file is currently playing and empty string otherwise.

The old version %_isplaying% still works.

%_ispaused%

Returns "1" if playback is paused, empty string otherwise.

%_playlist_number%

Returns playlist index of specified item. The first item is at index 1.

Also see %playlist_number%.

%_playlist_total%

Returns number of items in the playlist.

%playlist_name%

Returns the name of the playlist containing the specified item.

The old version %_playlist_name% still works.

String functions

The functions in this section can be used to manipulate character strings.

$abbr(x)

Returns abbreviation of x.

$abbr(x,len)

Returns abbreviation of x, if x is longer than len characters, otherwise returns x.

$ansi(x)

Converts x to system codepage and back. Any characters that are not present in the system codepage will be removed / replaced. Useful for mass-renaming files to ensure compatibility with non-unicode-capable software.

$ascii(x)

Converts x to ASCII. Any characters that are not present in ASCII will be removed / replaced.

$caps(x)

Converts first letter in every word of x to uppercase, and all other letters to lowercase.

$caps2(x)

Converts first letter in every word of x to uppercase, and leaves all other letters as they are.

$char(x)

Inserts Unicode character with code x.

$crc32(a)

Computes the CRC32 of the string a as a number. Intended for use in coloring scripts.

Example: $rgb($mod($crc32(%album%),256),128,128)

$crlf()

Inserts end-of-line marker (carriage return, line feed). Can be used to generate multiple lines in the output, for example for the tooltip of the system notification area ("systray") icon.

$cut(a,len)

Returns first len characters on the left of a.

$directory(x)

Extracts directory name from the file path x.

$directory(x,n)

Extracts directory name from the file path x; goes up by n levels.

$ext(x)

Extracts file extension from x which must be a file name or path.

$filename(x)

Extracts file name from full path.

$fix_eol(x)

If x contains an end-of-line marker (CR-LF), the end-of-line marker and all text to the right of it is replaced by " (...)". Otherwise x is returned unaltered.

$fix_eol(x,indicator)

If x contains an end-of-line marker (CR-LF), the end-of-line marker and all text to the right of it is replaced by indicator. Otherwise x is returned unaltered.

$hex(n)

Formats the integer number n in hexadecimal notation.

$hex(n,len)

Formats the integer number n in hexadecimal notation with len digits. Pads with zeros from the left if necessary.

$insert(a,b,n)

Inserts b into a after n characters.

$left(a,len)

Returns the first len characters from the left of a.

$len(a)

Returns length of string a in characters.

$len2(a)

Returns length of string x in characters, respecting double-width character rules (double-width characters will be counted as two).

$longer(a,b)

Returns true, if string a is longer than string b, false otherwise.

$lower(a)

Converts a to lowercase.

$longest(a,...)

Returns the longest of its arguments. Can be used with an arbitrary number of strings.

$num(n,len)

Formats the integer number n in decimal notation with len digits. Pads with zeros from the left if necessary.

$pad(x,len)

Pads x from the left with spaces to len characters.

$pad_right(x,y)

Pads x from the right with spaces to len characters.

$pad(x,len,char)

Pads x from the left with char to len characters.

$pad_right(x,len,char)

Pads x from the right with char to len characters.

$padcut(x,len)

Returns first len characters from the left of x, if x is longer than len characters. Otherwise pads x from the left with spaces to len characters.

$padcut_right(x,len)

Returns first len characters from the left of x, if x is longer than len characters. Otherwise pads x from the right with spaces to len characters.

$progress(pos,range,len,a,b)

Creates a progress bar: pos contains position, range contains range, len progress bar length in characters, a and b are characters to build progress bar with.

Example:$progress(%_time_elapsed_seconds%, %_time_total_seconds%, 20,'#','=') produces "====#===============", the # character is moving with playback position.

$progress2(pos,range,len,a,b)

Creates a progress bar: pos contains position, range contains range, len progress bar length in characters, a and b are characters to build progress bar with. Produces different appearance than $progress.

$repeat(a,n)

Returns n copies of a. Note that a is evaluated once before its value is used, so $repeat cannot be used for loops.

$replace(a,b,c)

Replaces all occurrences of string b in string a with string c.

Can also be used with an arbitrary number of arguments. Note that $replace(a,b1,c1,b2,c2) is generally not the same as $replace($replace(a,b1,c1),b2,c2).

Example: $replace(ab,a,b,b,c) -> "bc", $replace($replace(ab,a,b),b,c) -> "cc"

$right(a,len)

Returns the first len characters from the right of a.

$roman(n)

Formats the integer number n in roman notation.

$rot13()

Performs ROT13 transformation to given string.

Example: $rot13('foobar2000') -> "sbbone2000".

$shortest

Returns the shortest of its arguments. Can be used with an arbitrary number of strings.

$strchr(s,c)

Finds first occurence of character c in string s.

Example: $strchr(abca,a) -> 1

$strrchr(s,c)

Finds last occurence of character c in string s.

Example: $strrchr(abca,a) -> 4

$strstr(s1,s2)

Finds first occurence of string s2 in string s1.

$strcmp(s1,s2)

Performs a case-sensitive comparison of the strings s1 and s2.

$stricmp(s1,s2)

Performs a case-insensitive comparison of the strings s1 and s2.

$substr(s,m,n)

Returns substring of string s, starting from m-th character and ending at n-th character.

$trim(s)

Removes leading and trailing spaces from string s.

$tab()

Inserts one tabulator character.

$tab(n)

Inserts n tabulator characters.

$upper(s)

Converts string s to uppercase.

Track info

The functions and fields in this section can be used to access information about tracks.

Metadata

$meta(name)

Returns value of tag called name. If multiple values of that tag exist, they are concatenated with ", " as separator.

Example: $meta(artist) -> "He, She, It"

$meta(name,n)

Returns value of n-th tag called name.

Example: $meta(artist,2) -> "She"

$meta_sep(name,sep)

Returns value of tag called name. If multiple values of that tag exist, they are concatenated with sep as separator.

Example: $meta_sep(artist,' + ') -> "He + She + It"

$meta_sep(name,sep,lastsep)

Returns value of tag called name. If multiple values of that tag exist, they are concatenated with sep as separator between all but the last two values which are concatenated with lastsep.

Example: $metasep(artist,', ',', and ') -> "He, She, and It"

$meta_test(...)

Returns true, if all given tags exist.

Example: $meta_test(artist,title) -> true

$meta_num(name)

Returns the number of values for the tag called name.

Example: $meta_num(artist) -> 3

$tracknumber()

Returns the tracknumber padded to 2 digits with zeroes.

$tracknumber(n)

Returns the tracknumber padded to n digits with zeros.

Technical information

$info(name)

Returns value of technical information field called name.

Example: $info(channels) -> 2

$codec()

Returns codec of track. If no codec field is present, it the uses file extension.

Example: $codec() -> "WavPack"

$channels()

Returns number of channels in text format.

Example: $channels() -> "stereo"

%__replaygain_album_gain%

Returns ReplayGain album gain value. //Not available through// $info(replaygain_album_gain).

%__replaygain_album_peak%

Returns ReplayGain album peak value. //Not available through// $info(replaygain_album_peak).

%__replaygain_track_gain%

Returns ReplayGain track gain value. //Not available through// $info(replaygain_track_gain).

%__replaygain_track_peak%

Returns ReplayGain track peak value. //Not available through// $info(replaygain_track_peak).

Special fields

$extra(name)

Returns the value of the special field called name. These fields can also be accessed as %_name%; note the additional underscore. The following field names can be used:

filename

Returns the filename without directory and extension.

filename_ext

Returns the filename with extension, but without the directory.

directoryname

Returns the name of the parent directory only, not the complete path.

path

Returns the path.

path_raw

Returns the path as URL including the protocol scheme.

subsong

Returns the subsong index. The subsong index is used to distuingish multiple tracks in a single file, for example for cue sheets, tracker modules and various container formats.

foobar2000_version

Returns a string representing the version of foobar2000.

length

Returns the length of the track formatted as hours, minutes, and seconds.

length_ex

Returns the length of the track formatted as hours, minutes, seconds, and milliseconds.

length_seconds

Returns the length of the track in seconds.

length_seconds_fp

Returns the length of the track in seconds as floating point number.

length_samples

Returns the length of the track in samples.

Variable operations

Variables can be used to store strings and number. They cannot store truth values. They are best used to store intermediate results that you need multiple times. Variable names are not case-sensitive.

$get(name)

Returns the value that was last stored in the variable name, if the variable was not defined (yet), it returns nothing. The truth value returned by $get indicates if the variable name was defined.

$put(name,value)

Stores value in the variable name and returns value unaltered.

$puts(name,value)

Stores value in the variable name and returns only the truth value of value.

Component-provided fields and functions on tracks

This section lists components that provide additional fields and functions that are useable in the context of any track.

Playback statistics

Component-specific fields and functions

This section lists components that provide additional fields and functions that are only useable in the context of the particular component.

Album list

The official album list component supports creating multiple tree entries using special commands.