Difference between revisions of "Foobar2000:Title Formatting Reference"

From Hydrogenaudio Knowledgebase
Jump to: navigation, search
(Blah blah blah.)
(Technical information functions)
 
(109 intermediate revisions by 41 users not shown)
Line 1: Line 1:
 
{{fb2k}}
 
{{fb2k}}
This article contains information about built-in titleformatting functions and field references with special meaning. References to documentation about fields and function which can only be used in specific components or which are provided by specific components can be found at the end of this article.
+
This article contains information about built-in title formatting functions and field references, plus additional documentation about fields and functions which can only be used in specific components or which are provided by specific components.
  
A field reference is a field name enclosed in percent signs, for example ''%artist%''. A function call starts with a dollar sign, followed by the function name and the parameter list. A parameter list can either be empty - denoted as ''()'' - or contain one or more parameters separated by commata, for example ''$abbr(%artist%)''. Note that there must be no whitespace between the dollar sign and the function name, or the function name and the opening parenthesis of the parameter list.
+
Please see [[Foobar2000:Title Formatting Introduction|Title Formatting Introduction]] for a general overview of title format syntax and its basic rules. The article [[foobar2000:Titleformat Examples|Titleformat Examples]] offers user-submitted examples of code for specific purposes; feel free to add your own if you think it can be of use to others.
  
Please see [[Foobar2000:Titleformat_Introduction|Titleformat Introduction]] for a presentation of titleformat syntax in general.
+
For details of the query syntax, which uses some of these fields to find files for playlists, etc., see the [[Foobar2000:Query_syntax|Query Syntax]] article.
  
= Field remappings =
+
== Syntax ==
  
Some of the fields accessible through ''%name%'' are remapped to other values to make writing titleformat scripts more convenient.
+
A title formatting script consists of any combination of literal text, field references, function calls, comments, and line break characters. The script always outputs a text string (which can be empty).
  
== Metadata ==
+
A '''comment''' is a line starting with two slashes, e.g. {{code|// this is a comment}}.
  
=== %album artist% ===
+
A '''field reference''' is a field name enclosed in percent signs, for example {{code|%artist%}}.
Name of the artist of the album specified track belongs to. Checks following metadata fields, in this order: "album artist", "artist", "composer", "performer". The difference between this and ''%artist%'' is that ''%album artist%'' is intended for use where consistent value across entire album is needed even when per-track artists values vary.
+
  
=== %album% ===
+
A '''function call''' starts with a dollar sign, followed by the function name and the parameter list. A parameter list can either be empty – denoted as {{code|()}} – or contain one or more parameters separated by commas, for example {{code|$abbr(%artist%)}}. A parameter can be literal text, a field reference, or another function call. Note that there must be no whitespace between the dollar sign and the function name, or the function name and the opening parenthesis of the parameter list.
Name of the album specified track belongs to. Checks following metadata fields, in this order: "album", "venue".
+
  
=== %artist% ===
+
Any other text is '''literal text'''. In literal text, the character {{code|%}}, {{code|$}}, {{code|[}}, {{code|]}}, or {{code|'}} (apostrophe/single quote) must be escaped by enclosing it in {{code|'}} (apostrophe/single quote) characters. For example, {{code|'['}} (a left bracket in single quotes) results in a literal {{code|[}} (left bracket). As a special case, {{code|<nowiki>''</nowiki>}} (two single quotes in a row) results in one single quote. In the playlist, {{code|&lt;}} and {{code|&gt;}} are also special; see [[#Dimmed and highlighted text|Dimmed and highlighted text]].
Name of the artist of the track. Checks following metadata fields, in this order: "artist", "album artist", "composer", "performer".
+
  
=== %disc% ===
+
When the script is evaluated, the output string is assembled by evaluating the function parameters, function calls, and field references. Comments and line break characters (CR and LF/newline) are ignored; to output a line break, use {{code|$crlf()}}. Each field reference becomes the field's value, as a string. Each function becomes a string or number, and/or a truth value (not output) which can be used by another function.
Index of disc specified track belongs to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.
+
  
This remapping exists only for compatibility with old scripts. It is recommended to use %discnumber% instead.
+
'''Note: The interface for entering custom columns and grouping schemes for the Default UI playlist does not support line breaks; scripts must be written all on one line, without comments.'''
  
=== %discnumber% ===
+
== Arithmetic functions ==
Index of disc specified track belongs to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.
+
 
+
=== %track artist% ===
+
Name of the artist of the track; present only if ''%album artist%'' is different than ''%artist%'' for specific track. Intended for use together with ''%album artist%'', to indicate track-specific artist info, e.g. "%album artist% - %title%[ '//' %track artist%]". In this case, the last part will be displayed only when track-specific artist info is present.
+
 
+
=== %title% ===
+
Title of the track. If "title" metadata field is missing, file name is used instead.
+
 
+
=== %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 remapping exists only for compatibility with old scripts. It is recommended to use %tracknumber% instead.
+
 
+
=== %tracknumber% ===
+
Two-digit index of specified track within the album. Available only when "tracknumber" field is present in track’s metadata.
+
 
+
== Technical information ==
+
 
+
=== %bitrate% ===
+
Bitrate of the track; includes dynamic VBR bitrate display for currently played track.
+
 
+
=== %channels% ===
+
Number of channels in the track (mono/stereo/etc). 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% ===
+
Sample rate of the track, in Hz.
+
 
+
=== %codec% ===
+
Name of codec used to encode the track. If exact codec name is not available, file extension is used.
+
 
+
== Special fields ==
+
 
+
= 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.
+
 
+
=== $ifequal(n1,n2,then,else) ===
+
 
+
Compares the integer numbers ''n1'' and ''n2'', if ''n1'' is equal to ''n2'', the ''then'' part is evaluated and its value 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. Decimal points are not supported. Examples:
 +
* ''c3po'' → 0
 +
* ''4.8'' → 4
 +
* ''-12'' → -12
 +
* ''- 12'' → 0
  
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.
+
=== $add(a,b, ...) ===
 
+
Example: "c3po" → 0, " -12" → -12, but "- 12" → 0
+
 
+
=== $add(a,b) ===
+
  
 
Adds ''a'' and ''b''.
 
Adds ''a'' and ''b''.
Line 118: Line 38:
 
=== $div(a,b) ===
 
=== $div(a,b) ===
  
Divides ''a'' through ''b''. If ''b'' evaluates to zero, it returns ''a''.
+
Divides ''a'' by ''b'' and rounds down to an integer. 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),...)''.
 
Can be used with an arbitrary number of arguments. ''$div(a,b,...)'' is the same as ''$div($div(a,b),...)''.
Line 156: Line 76:
 
=== $rand() ===
 
=== $rand() ===
  
Generates a random number in the range from 0 to 2<sup>32</sup>-1.
+
Generates a random number in the range from 0 to 2<sup>32</sup>-1. Available only in sort-related contexts, such as the ''Edit → Sort → Sort by ...'' menu command.
  
 
=== $sub(a,b) ===
 
=== $sub(a,b) ===
Line 164: Line 84:
 
Can be used with an arbitrary number of arguments. ''$sub(a,b,...)'' is the same as ''$sub($sub(a,b),...)''.
 
Can be used with an arbitrary number of arguments. ''$sub(a,b,...)'' is the same as ''$sub($sub(a,b),...)''.
  
= Boolean functions =
+
== 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.
 
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(...) ===
+
Foobar does not have a concept of TRUE and FALSE in a programming language sense where 0 or empty string are considered FALSE and other values TRUE. Therefore there is no difference between numeric 0 and string representation '0' which both are considered as values, and being attached a boolean value FALSE. Apostrophes are only required to escape certain syntax characters. Values are treated as numbers during arithmetic operations like'' $add()''.
  
Logical And of an arbitrary number of arguments. Returns ''true'', if and only if all arguments evaluate to ''true''.
+
=== $and(expr, ...) ===
  
Special case: ''$and(x,y)'' is ''true'', if both ''x'' and ''y'' are ''true''. Otherwise it is ''false''.
+
Logical And of an arbitrary number of arguments. Returns ''true'', if and only if all ''expr'' arguments evaluate to ''true''.
  
=== $or(...) ===
+
=== $or(expr, ...) ===
  
Logical Or of an arbitrary number of arguments. Returns ''true'', if at least one argument evaluates to ''true''.
+
Logical Or of an arbitrary number of arguments. Returns ''true'', if at least one expression 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(expr) ===
  
=== $not(x) ===
+
Logical Not. Returns the logical opposite of EXPR: ''false'', if ''expr'' is ''true'' and ''true'' if ''expr'' is false.
  
Logical Not. Returns ''false'', if ''x'' is ''true'', otherwise it returns ''true''.
+
=== $xor(expr,...) ===
 
+
=== $xor(...) ===
+
  
 
Logical Exclusive-or of an arbitrary number of arguments. Returns ''true'', if an odd number of arguments evaluate to ''true''.
 
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''.
+
Special case: ''$xor(expr1,expr2)'' returns ''true'', if EXPR1 or EXPR2 is ''true''. If both expressions are true, returns ''false''.
  
= Color functions =
+
== Control flow functions ==
  
=== $blend(color1,color2,part,total) ===
+
The functions in this section can be used to conditionally execute statements.
  
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.
+
=== [...] (conditional section) ===
  
=== $hsl() ===
+
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.
  
Resets the text color to the default color.
+
Example: ''[%artist%]'' returns the value of the artist tag, if it exists. Otherwise it returns nothing, when ''artist'' would return "?".
  
=== $hsl(h,s,l) ===
+
=== $if(cond,then) ===
  
Sets the color for text in the HSL color space. ''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.
+
If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, ''false'' is returned.
The ranges of ''h'', ''s'', and ''l'' are from 0 to 240; the function is designed to interpret those values in the same way as the standard Windows color dialog.
+
  
=== $hsl(h1,s1,l1,h2,s2,l2) ===
+
Plain strings are FALSE. Field lookups and functions can introduce a boolean value of TRUE. <br />
 +
<u>Examples</u>:<br />
 +
<u>1</u>
 +
<code>
 +
#False:
 +
$if(0,True,False)
 +
# False:
 +
$if('0',True,False)
 +
# True or False:
 +
[$add(%rating%,1)]
 +
</code><br />
 +
The last one would display the value of %rating% plus one, if and only if %rating% is set for the track.
  
Sets the color for text in the HSL color space. ''h1'', ''s1'' and ''l1'' are the hue, saturation, and lightness of the color for unselected text. ''h2'', ''s2'' and ''l2'' are the hue, saturation, and lightness of the color for selected text.
+
<u>2</u>
 +
Ignore inserting the %album artist%, if it contains the word "various".  
 +
<code>
 +
# Wrong:
 +
$if([%album artist%=Various],,%artist%-)
 +
# Good approach:
 +
$if($stricmp(%album artist%,Various),,%artist%-)
 +
</code>
  
=== $rgb() ===
+
=== $if(cond,then,else) ===
  
Resets the text color to the default color.
+
If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, the ''else'' part is evaluated and its value returned.
  
=== $rgb(r,g,b) ===
+
=== $if2(expr,else) ===
  
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.
+
Like ''$if(expr,expr,else)'' except that ''expr'' is only evaluated once. In other words, if expression ''expr'' is true, ''expr'' is returned, otherwise the ''else'' part is evaluated and ''expr'' is returned as true.
  
=== $rgb(r1,g1,b1,r2,g2,b2) ===
+
=== $if3(a1,a2,...,aN,else) ===
  
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 of the color for selected text.
+
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.
  
=== $transition(string,color1,color2) ===
+
=== $ifequal(int1,int2,then,else) ===
  
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''.
+
Compares the integer numbers ''int1'' and ''int2'', if ''int1'' is equal to ''int2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.
  
= Now playing info =
+
=== $ifgreater(int1,int2,then,else) ===
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 ==
+
Compares the integer numbers ''int1'' and ''int2'', if ''int1'' is greater than ''int2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.
  
=== %playback_time% ===
+
=== $iflonger(str,n,then,else) ===
Returns the elapsed time formatted as [HH:]MM:SS.
+
  
=== %playback_time_seconds% ===
+
Compares the length of the string ''str'' to the number ''n'', if ''str'' is longer than ''n'' characters, the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.
Returns elapsed time in seconds.
+
Old version: <code>%_time_elapsed%</code>
+
  
=== %playback_time_remaining% ===
+
=== $select(n,a1,...,aN) ===
Returns remaining time until track ends, formatted as [HH:]MM:SS.
+
Old version: <code>%_time_remaining%</code>
+
  
=== %playback_time_remaining_seconds% ===
+
If the value of ''n'' is between 1 and N, ''an'' is evaluated and its value returned. Otherwise ''false'' is returned.
Returns remaining time in seconds.
+
Old version: <code>%_time_remaining_seconds%</code>
+
  
=== %length% ===
+
== String functions ==
Returns the length of the track formatted as hours, minutes, and seconds.
+
Old version: <code>%_time_total%</code>
+
  
=== %length_ex% ===
+
The functions in this section can be used to manipulate character strings.
Returns the length of the track formatted as hours, minutes, seconds, and milliseconds.
+
  
=== %length_seconds% ===
+
=== $abbr(str) ===
Returns the length of the track in seconds.
+
Old version: <code>%_time_total_seconds%</code>
+
  
=== %length_seconds_fp% ===
+
Returns abbreviation of string ''str''. Words which begin with an alphanumeric character are shortened to the first character. Spaces and parentheses are stripped. Example:
Returns the length of the track in seconds as floating point number.
+
* $abbr('This is a Long Title (12-inch version) [needs tags]') → TiaLT1v[needst
  
=== %length_samples% ===
+
=== $abbr(str,len) ===
Returns the length of the track in samples.
+
  
= Playlist info =
+
Returns abbreviation of ''str'', if ''str'' is longer than ''len'' characters, otherwise returns ''str''.
The following functions and fields are usable for playlist display formatting (eg. per-column title formatting patterns).
+
  
== Special fields ==
+
=== $ansi(str) ===
  
=== %isplaying% ===
+
Converts string ''str'' 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.
  
Returns "1" if file is currently playing and empty string otherwise.
+
=== $ascii(str) ===
  
=== %ispaused% ===
+
Converts string ''str'' to ASCII. Any characters that are not present in ASCII will be removed / replaced.
  
Returns "1" if playback is paused, empty string otherwise.
+
=== $caps(str) ===
  
=== %list_index% ===
+
Converts first letter in every word of string ''str'' to uppercase, and all other letters to lowercase.
  
Returns a zero-padded playlist index of specified item. The first item is at index 1.
+
=== $caps2(str) ===
  
=== %list_total% ===
+
Converts first letter in every word of string ''str'' to uppercase, and leaves all other letters as they are.
  
Returns number of items in the playlist.
+
=== $char(nbr) ===
  
= String functions =
+
Returns Unicode character of ''nbr''. You can search for characters and find the matching decimal number on this [http://www.fileformat.info/info/unicode/char/search.htm site].
  
The functions in this section can be used to manipulate character strings.
+
=== $crc32(str) ===
  
=== $abbr(x) ===
+
Computes the CRC32 of the string ''str'' as a number. Intended for use in coloring scripts.
  
Returns abbreviation of ''x''.
+
Example: $rgb($mod($crc32(%album%),256),128,128)
  
=== $abbr(x,len) ===
+
=== $crlf() ===
  
Returns abbreviation of ''x'', if ''x'' is longer than ''len'' characters, otherwise returns ''x''.
+
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.
  
=== $ansi(x) ===
+
=== $cut(str,len) ===
  
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.
+
Returns first ''len'' characters from the left of the string ''str''. This function is the same as $left(a,len). Negative numbers produce the entire string. Examples:
 +
* ''$cut('abc123',3)'' → abc
 +
* ''$cut('abc123',0)'' → (nothing)
 +
* ''$cut('abc123',-1)'' → abc123
  
=== $ascii(x) ===
+
=== $directory(path) ===
  
Converts ''x'' to ASCII. Any characters that are not present in ASCII will be removed / replaced.
+
Extracts directory name from the file ''path''.
  
=== $caps(x) ===
+
=== $directory(path,n) ===
  
Converts first letter in every word of x to uppercase, and all other letters to lowercase.
+
Extracts directory name from the file ''path''; goes up by ''n'' levels.
  
=== $caps2(x) ===
+
=== $directory_path(path) ===
  
Converts first letter in every word of x to uppercase, and leaves all other letters as they are.
+
Extracts directory path from the file ''path''.
  
=== $char(x) ===
+
=== $ext(path) ===
  
Inserts Unicode character with code ''x''.
+
Extracts file extension from string ''path''; a file name or full path.
  
=== $crc32(a) ===
+
=== $filename(path) ===
  
Computes the CRC32 of the string ''a'' as a number. Intended for use in coloring scripts.
+
Extracts file name from full ''path''.
  
Example: $rgb($mod($crc32(%album%),256),128,128)
+
=== $fix_eol(str) ===
  
=== $crlf() ===
+
If ''str'' 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 ''str'' is returned unaltered.
  
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.
+
=== $fix_eol(str,indicator) ===
  
=== $cut(a,len) ===
+
If ''str'' 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 ''str'' is returned unaltered.
  
Returns first ''len'' characters on the left of ''a''.
+
=== $hex(int,len) ===
  
=== $directory(x) ===
+
Formats the integer number ''int'' in hexadecimal notation with ''len'' digits. Pads with zeros from the left if necessary.
  
Extracts directory name from the file path ''x''.
+
=== $insert(str,insert,n) ===
  
=== $directory(x,n) ===
+
Inserts ''insert'' into ''str'' after ''n'' characters.
  
Extracts directory name from the file path ''x''; goes up by ''n'' levels.
+
=== $left(str,len) ===
  
=== $ext(x) ===
+
Returns first ''len'' characters from the left of the string ''str''. This function is the same as $cut(str,len). Negative numbers produce the entire string. Examples:
 +
* ''$left('abc123',3)'' → abc
 +
* ''$left('abc123',0)'' → (nothing)
 +
* ''$left('abc123',-1)'' → abc123
  
Extracts file extension from ''x'' which must be a file name or path.
+
=== $len(str) ===
  
=== $filename(x) ===
+
Returns length of string ''str'' in characters.
  
Extracts file name from full path.
+
=== $len2(str) ===
  
=== $fix_eol(x) ===
+
Returns length of string ''str'' in characters, respecting double-width character rules (double-width characters will be counted as two).
  
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.
+
=== $longer(str1,str2) ===
  
=== $fix_eol(x,indicator) ===
+
Returns ''true'', if string ''str1'' is longer than string ''str2'', false otherwise.
  
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.
+
=== $lower(str) ===
  
=== $hex(n) ===
+
Converts string ''str'' to lowercase.
  
Formats the integer number ''n'' in hexadecimal notation.
+
=== $longest(arg,...) ===
  
=== $hex(n,len) ===
+
Returns the longest of its arguments. Can be used with an arbitrary number of strings.
  
Formats the integer number ''n'' in hexadecimal notation with ''len'' digits. Pads with zeros from the left if necessary.
+
=== $num(nbr,len) ===
  
=== $insert(a,b,n) ===
+
Formats the integer number ''nbr'' in decimal notation with ''len'' characters. Pads with zeros from the left if necessary. ''len'' includes the dash when the number is negative. If ''nbr'' is not numeric, it is treated as zero. Examples:
  
Inserts ''b'' into ''a'' after ''n'' characters.
+
* ''$num(123,5)'' → 00123
 +
* ''$num(-123,5)'' → -0123
 +
* ''$num(4.8,5)'' → 00004
 +
* ''$num(A1,5)'' → 00000
  
=== $left(a,len) ===
+
=== $pad(str,len) ===
  
Returns the first ''len'' characters from the left of ''a''.
+
Creates a left-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds spaces to the right of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.
  
=== $len(a) ===
+
=== $pad_right(str,len) ===
  
Returns length of string ''a'' in characters.
+
Creates a right-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds spaces to the left of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.
  
=== $len2(a) ===
+
=== $pad(str,len,char) ===
  
Returns length of string x in characters, respecting double-width character rules (double-width characters will be counted as two).
+
Creates a left-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds ''char'' to the right of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.
  
=== $longer(a,b) ===
+
=== $pad_right(str,len,char) ===
  
Returns ''true'', if string ''a'' is longer than string ''b'', false otherwise.
+
Creates a right-aligned version of the string ''str''. If ''str'' is shorter than ''len'' characters, the function adds ''char'' to the left of ''str'' to make the result ''len'' characters long. Otherwise the function returns ''str'' unchanged.
  
=== $lower(a) ===
+
=== $padcut(str,len) ===
  
Converts ''a'' to lowercase.
+
Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds spaces to the right of ''str'' to make the result ''len'' characters long.
  
=== $longest(a,...) ===
+
=== $padcut(str,len,char) ===
  
Returns the longest of its arguments. Can be used with an arbitrary number of strings.
+
Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds ''char'' to the right of ''str'' to make the result ''len'' characters long.
  
=== $num(n,len) ===
+
=== $padcut_right(str,len) ===
  
Formats the integer number ''n'' in decimal notation with ''len'' digits. Pads with zeros from the left if necessary.
+
Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds spaces to the left of ''str'' to make the result ''len'' characters long.
  
=== $pad(x,len) ===
+
=== $padcut_right(str,len,char) ===
  
Pads ''x'' from the left with spaces to ''len'' characters.
+
Returns first ''len'' characters from the left of ''str'', if ''str'' is longer than ''len'' characters. Otherwise adds ''char'' to the left of ''str'' to make the result ''len'' characters long.
  
=== $pad_right(x,y) ===
+
=== $progress(pos,range,len,char1,char2) ===
  
Pads ''x'' from the right with spaces to ''len'' characters.
+
Creates a progress bar: ''pos'' contains position, ''range'' contains range, ''len'' progress bar length in characters, ''char1'' and ''char2'' are characters to build progress bar with.
  
=== $pad(x,len,char) ===
+
Example:''$progress(%_time_elapsed_seconds%, %_time_total_seconds%, 20,'#','=')'' produces "====#===============", the # character is moving with playback position.
  
Pads ''x'' from the left with ''char'' to ''len'' characters.
+
=== $progress2(pos,range,len,char1,char2) ===
  
=== $pad_right(x,len,char) ===
+
Creates a progress bar: ''pos'' contains position, ''range'' contains range, ''len'' progress bar length in characters, ''char1'' and ''char2'' are characters to build progress bar with. Produces different appearance than ''$progress''.
  
Pads ''x'' from the right with ''char'' to ''len'' characters.
+
=== $repeat(expr,count) ===
  
=== $padcut(x,len) ===
+
Returns ''count'' copies of ''expr''. Note that ''expr'' is evaluated once before its value is used, so ''$repeat'' cannot be used for loops.
  
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.
+
=== $replace(str,search,replace) ===
  
=== $padcut_right(x,len) ===
+
Replaces all occurrences of string ''search'' in string ''str'' with string ''replace''.
  
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.
+
Can also be used with an arbitrary number of arguments. Note that ''$replace(str,search1,replace1,search2,replace2)'' is generally not the same as ''$replace($replace(str,search1,replace1),search2,replace2)''.
  
=== $progress(pos,range,len,a,b) ===
+
Example: ''$replace(ab,a,b,b,c)'' → "bc", ''$replace($replace(ab,a,b),b,c)'' → "cc"
  
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.
+
=== $right(str,len) ===
  
Example:''$progress(%_time_elapsed_seconds%, %_time_total_seconds%, 20,'#','=')'' produces "====#===============", the # character is moving with playback position.
+
Returns the first ''len'' characters from the right of string ''str''.
  
=== $progress2(pos,range,len,a,b) ===
+
=== $roman(int) ===
  
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''.
+
Formats the integer number ''int'' in roman notation.
  
=== $repeat(a,n) ===
+
=== $rot13(str) ===
  
Returns ''n'' copies of ''a''. Note that ''a'' is evaluated once before its value is used, so ''$repeat'' cannot be used for loops.
+
Performs [http://en.wikipedia.org/wiki/ROT13 ROT13] transformation to given string.
  
=== $replace(a,b,c) ===
+
Example: ''$rot13('foobar2000')'' → "sbbone2000".
  
Replaces all occurrences of string ''b'' in string ''a'' with string ''c''.
+
=== $shortest(str,...strN) ===
  
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)''.
+
Returns the first shortest element of its arguments. Can be used with an arbitrary number of strings.
  
Example: ''$replace(ab,a,b,b,c)'' → "bc", ''$replace($replace(ab,a,b),b,c)'' → "cc"
+
=== $strchr(str,char) ===
  
=== $right(a,len) ===
+
Returns position of first occurrence of character ''char'' in string ''str''.
  
Returns the first ''len'' characters from the right of ''a''.
+
Example: ''$strchr(abca,a)'' → 1
  
=== $roman(n) ===
+
=== $strrchr(str,char) ===
  
Formats the integer number ''n'' in roman notation.
+
Returns positions of last occurrence of character ''char'' in string ''str''.
  
=== $rot13() ===
+
Example: ''$strrchr(abca,a)'' → 4
  
Performs [http://en.wikipedia.org/wiki/ROT13 ROT13] transformation to given string.
+
=== $strstr(str1,str2) ===
  
Example: ''$rot13('foobar2000')'' → "sbbone2000".
+
Returns position of first occurrence of string ''str2'' in string ''str1''. Function is case-sensitive.
  
=== $shortest ===
+
=== $strcmp(str1,str2) ===
  
Returns the shortest of its arguments. Can be used with an arbitrary number of strings.
+
Performs a case-sensitive comparison of the strings ''str1'' and ''str2''.
  
=== $strchr(s,c) ===
+
=== $stricmp(str1,str2) ===
  
Finds first occurence of character ''c'' in string ''s''.
+
Performs a case-insensitive comparison of the strings ''str1'' and ''str2''.
  
Example: ''$strchr(abca,a)'' → 1
+
=== $stripprefix(str) ===
  
=== $strrchr(s,c) ===
+
Removes ''A'' and ''The'' prefixes from string ''str''.
 
+
Finds last occurence of character ''c'' in string ''s''.
+
 
+
Example: ''$strrchr(abca,a)'' → 4
+
  
=== $strstr(s1,s2) ===
+
=== $stripprefix(str,prefix1,prefix2,...) ===
  
Finds first occurence of string ''s2'' in string ''s1''.
+
Removes the specified prefixes from string ''str''.  
  
=== $strcmp(s1,s2) ===
+
=== $substr(str,from,to) ===
  
Performs a case-sensitive comparison of the strings ''s1'' and ''s2''.
+
Returns substring of string ''str'', starting from ''FROM''-th character and ending at ''TO''-th character.
  
=== $stricmp(s1,s2) ===
+
=== $swapprefix(str) ===
  
Performs a case-insensitive comparison of the strings ''s1'' and ''s2''.
+
Moves ''A'' and ''The'' prefixes to the end of string ''str''.  
  
=== $substr(s,m,n) ===
+
=== $swapprefix(str,prefix1,prefix2,...) ===
  
Returns substring of string ''s'', starting from ''m''-th character and ending at ''n''-th character.
+
Moves the specified prefixes to the end of string ''str''.  
  
=== $trim(s) ===
+
=== $trim(str) ===
  
Removes leading and trailing spaces from string ''s''.
+
Removes leading and trailing spaces from string ''str''.
  
 
=== $tab() ===
 
=== $tab() ===
Line 493: Line 418:
 
Inserts one tabulator character.
 
Inserts one tabulator character.
  
=== $tab(n) ===
+
=== $tab(count) ===
  
Inserts ''n'' tabulator characters.
+
Inserts ''count'' tabulator characters.
  
=== $upper(s) ===
+
=== $upper(str) ===
  
Converts string ''s'' to uppercase.
+
Converts string ''str'' to uppercase.
  
= Track info =
+
== Track info fields and functions ==
  
The functions and fields in this section can be used to access information about tracks. See [[Foobar2000:0.9 Track Info Panel Mod (foo uie trackinfo mod)|this]] for more info about Track info mod.
+
The functions and fields in this section can be used to access information about tracks.
  
== Metadata ==
+
=== Metadata fields and functions ===
  
=== $meta(name) ===
+
Generally, metadata from the files (whether in tags or a cue sheet) is mapped directly to a field which can be referenced case-insensitively. For example, the first tag named ''URL'' can be referenced as ''%url%'', and the first standard comment tag can be referenced as ''%comment%''.
 +
 
 +
The following functions are also available for accessing metadata:
 +
 
 +
==== $meta(name) ====
 
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ", " as separator.
 
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"
+
Example: ''$meta(artist)'' → "He, She, They"
  
=== $meta(name,n) ===
+
==== $meta(name,n) ====
 
Returns value of ''n''-th (0,1,2 and so on) tag called ''name''.
 
Returns value of ''n''-th (0,1,2 and so on) tag called ''name''.
  
 
Example: ''$meta(artist,1)'' → "She"
 
Example: ''$meta(artist,1)'' → "She"
  
=== $meta_sep(name,sep) ===
+
==== $meta_sep(name,sep) ====
 
Returns value of tag called ''name''. If multiple values of that tag exist, they are concatenated with ''sep'' as separator.
 
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"
+
Example: ''$meta_sep(artist,' + ')'' → "He + She + They"
  
=== $meta_sep(name,sep,lastsep) ===
+
==== $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''.
 
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: ''$meta_sep(artist,', ',', and ')'' → "He, She, and It"
+
Example: ''$meta_sep(artist,', ',', and ')'' → "He, She, and They"
  
=== $meta_test(...) ===  
+
==== $meta_test(...) ====
 
Returns ''1'', if all given tags exist, ''undefined'' otherwise.
 
Returns ''1'', if all given tags exist, ''undefined'' otherwise.
  
 
Example: ''$meta_test(artist,title)'' → true
 
Example: ''$meta_test(artist,title)'' → true
  
=== $meta_num(name) ===
+
==== $meta_num(name) ====
 
Returns the number of values for the tag called ''name''.
 
Returns the number of values for the tag called ''name''.
  
 
Example: ''$meta_num(artist)'' → 3
 
Example: ''$meta_num(artist)'' → 3
  
=== $tracknumber() ===
+
=== Remapped metadata fields ===
Returns the tracknumber padded to 2 digits with zeroes.
+
  
=== $tracknumber(n) ===
+
The following fields have special remapped values to make writing title format scripts more convenient:
Returns the tracknumber padded to ''n'' digits with zeros.
+
  
== Technical information ==
+
==== %album artist% ====
 +
Name of the artist of the album specified track belongs to. Checks following metadata fields, in this order: "album artist", "artist", "composer", "performer". The difference between this and ''%artist%'' is that ''%album artist%'' is intended for use where consistent value across entire album is needed even when per-track artists values vary.
  
=== $info(name) ===
+
==== %album% ====
 +
Name of the album specified track belongs to. Checks following metadata fields, in this order: "album", "venue".
 +
 
 +
==== %artist% ====
 +
Name of the artist of the track. Checks following metadata fields, in this order: "artist", "album artist", "composer", "performer". For a SHOUTcast stream which contains metadata, it is the StreamTitle up to the first "-" character.
 +
 
 +
==== %discnumber% ====
 +
Index of disc specified track belongs to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.
 +
 
 +
==== %totaldiscs% ====
 +
Index of total discs specified tracks belong to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.
 +
 
 +
==== %track artist% ====
 +
Name of the artist of the track; present only if ''%album artist%'' is different than ''%artist%'' for specific track. Intended for use together with ''%album artist%'', to indicate track-specific artist info, e.g. "%album artist% - %title%[ '//' %track artist%]". In this case, the last part will be displayed only when track-specific artist info is present.
 +
 
 +
==== %title% ====
 +
Title of the track. If "title" metadata field is missing, file name is used instead. For a SHOUTcast stream which contains metadata, it is the StreamTitle after the first "-" character.
 +
 
 +
==== %tracknumber% ====
 +
Two-digit index of specified track within the album. Available only when "tracknumber" field is present in track’s metadata. An extra '0' is placed in front of single digit track numbers (5 becomes 05).
 +
 
 +
==== %track number% ====
 +
Similar to %tracknumber%, however single digit track numbers are not reformatted to have an extra 0.
 +
 
 +
=== Technical information fields ===
 +
 
 +
==== %bitrate% ====
 +
Bitrate of the track in kilobits per second. VBR files will show a dynamic display for currently played track (outside of the playlist).
 +
 
 +
==== %channels% ====
 +
Number of channels in the track, as text; either "mono", "stereo" for 1 or 2 channels, respectively, otherwise a number followed by "ch", e.g. "6ch".
 +
 
 +
==== %codec% ====
 +
Name of codec used to encode the track, e.g. PCM, FLAC, MP3, or AAC. If exact codec name is not available, file extension is used. The Default UI's standard Codec column displays the same info, but sometimes adds details, e.g. "MP3 / VBR V2" or "AAC / LC".
 +
 
 +
==== %filesize% ====
 +
The exact file size in bytes.
 +
Old version: <code>%_filesize%</code>
 +
 
 +
==== %filesize_natural% ====
 +
The approximate file size, automatically formatted in appropriate units such as megabytes or kilobytes, e.g. "8.49 MB"
 +
 
 +
==== %length% ====
 +
The length of the track formatted as hours, minutes, and seconds, rounded to the nearest second.
 +
Old version: <code>%_time_total%</code>
 +
 
 +
==== %length_ex% ====
 +
The length of the track formatted as hours, minutes, seconds, and milliseconds, rounded to the nearest millisecond.
 +
 
 +
==== %length_seconds% ====
 +
The length of the track in seconds, rounded to the nearest second.
 +
Old version: <code>%_time_total_seconds%</code>
 +
 
 +
==== %length_seconds_fp% ====
 +
The length of the track in seconds as a floating point number.
 +
 
 +
==== %length_samples% ====
 +
The length of the track in samples.
 +
 
 +
==== %samplerate% ====
 +
Sample rate of the track, in Hz.
 +
 
 +
=== Technical information functions ===
 +
 
 +
==== $info(name) ====
 
Returns value of technical information field called ''name''.
 
Returns value of technical information field called ''name''.
  
Line 553: Line 545:
  
 
Here is an '''informative''' list of recognized fields. Some of these depend on the media file type being queried.
 
Here is an '''informative''' list of recognized fields. Some of these depend on the media file type being queried.
 
(→See also: [[Foobar2000_Talk:Titleformat_Reference#Other_information|Talk page]])
 
  
 
{| border="0" cellspacing="0" cellpadding="2"
 
{| border="0" cellspacing="0" cellpadding="2"
Line 582: Line 572:
 
|channels
 
|channels
 
| style="background-color:#EEF"|'''Channels''' count (''e.g.'' 2 <nowiki>[for stereo]</nowiki>)
 
| style="background-color:#EEF"|'''Channels''' count (''e.g.'' 2 <nowiki>[for stereo]</nowiki>)
 +
|-
 +
|channel_mode
 +
| style="background-color:#EEF"|'''Channel Mode''', description of channels (''e.g.'' 3 front, 2 rear surround channels + LFE)
 
|-
 
|-
 
|bitspersample
 
|bitspersample
Line 598: Line 591:
 
|-
 
|-
 
|ENC_DELAY
 
|ENC_DELAY
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_delay''' value (''e.g.'' 576)
+
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_delay''' value for gapless playback (''e.g.'' 576)
 
|-
 
|-
 
|ENC_PADDING
 
|ENC_PADDING
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_padding''' value (''e.g.'' 1536)
+
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_padding''' value for gapless playback (''e.g.'' 1536)
 
|-
 
|-
 
|MP3_ACCURATE_LENGTH
 
|MP3_ACCURATE_LENGTH
| style="background-color:#EEF"|'''mp3_accurate_length''' supported (LAME proprietary header)? (''e.g.'' yes)
+
| style="background-color:#EEF"|MP3 duration (%length% etc.) takes into account LAME or iTunes gapless playback info (''e.g.'' yes)*
 
|-
 
|-
 
|MP3_STEREO_MODE
 
|MP3_STEREO_MODE
Line 616: Line 609:
 
|}
 
|}
  
=== $channels() ===
 
Returns number of channels in text format.
 
  
Example: ''$channels()'' → "stereo"
+
<div style="font-size: 90%"><nowiki>*</nowiki> ''MP3_ACCURATE_LENGTH won't exist if gapless playback info isn't present or the file is not an MP3. The info can be in a LAME tag in the VBR header, or in an iTunSMPB ID3v2 comment tag. Gapless playback info is taken into account in .m4a files, but there's no special field to say so.''</div>
  
=== %replaygain_album_gain% ===
+
==== $channels() ====
 +
The number of channels in text format.
  
Returns ReplayGain album gain value.
+
Example: ''$channels()'' → "stereo"
  
=== %replaygain_album_peak% ===
+
==== %replaygain_album_gain% ====
 +
The ReplayGain album gain value.
  
Returns ReplayGain album peak value.
+
==== %replaygain_album_peak% ====
 +
The ReplayGain album peak value.
  
=== %replaygain_track_gain% ===
+
==== %replaygain_album_peak_db% ====
 +
The ReplayGain album peak value in decibels.
  
Returns ReplayGain track gain value.
+
==== %replaygain_track_gain% ====
 +
The ReplayGain track gain value.
  
=== %replaygain_track_peak% ===
+
==== %replaygain_track_peak% ====
 +
The ReplayGain track peak value.
  
Returns ReplayGain track peak value.
+
==== %replaygain_track_peak_db% ====
 +
The ReplayGain track peak value in decibels.
  
== Special fields ==
+
=== Special fields ===
  
 
==== %filename% ====
 
==== %filename% ====
 
+
The filename without directory and extension.
Returns the filename without directory and extension.
+
  
 
==== %filename_ext% ====
 
==== %filename_ext% ====
 
+
The filename with extension, but without the directory.
Returns the filename with extension, but without the directory.
+
  
 
==== %directoryname% ====
 
==== %directoryname% ====
 +
The name of the parent directory only, not the complete path.
  
Returns the name of the parent directory only, not the complete path.
+
==== %last_modified% ====
 +
The date and time the file was last modified. Eg: ''2005-12-22 00:04:10''
  
==== %lastmodified% ====
+
==== %path% ====
 +
The complete path, including the filename and extension.
  
Returns the date and time the file was last modified. Eg: ''2005-12-22 00:04:10''
+
==== %_path_raw% ====
 +
The path as URL including the protocol scheme.
  
==== %path% ====
+
==== %subsong% ====
 +
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.
  
Returns the path.
+
==== %_foobar2000_version% ====
 +
A string representing the version of foobar2000.
  
==== %path_raw% ====
+
== Time and date functions ==
  
Returns the path as URL including the protocol scheme.
+
These functions are used to manipulate time/date strings, notably (but not limited to), [[Foobar2000:Titleformat_Playback_Statistics|those gathered]] by the [[Foobar2000:Components/Playback Statistics v3.x (foo playcount)|Playback Statistics component]].
  
==== %subsong% ====
+
=== $year(time) ===
 +
Retrieves the year part (formatted as four digits) from a time/date string.
  
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.
+
=== $month(time) ===
 +
Retrieves the month part (formatted as two digits) from a time/date string.
  
==== %_foobar2000_version% ====
+
=== $day_of_month(time) ===
Returns a string representing the version of foobar2000.
+
Retrieves the day of month part (formatted as two digits) from a time/date string.
 +
 
 +
=== $date(time) ===
 +
Retrieves the date part (formatted as YYYY-MM-DD) from a time/date string.
 +
 
 +
=== $time(time) ===
 +
Retrieves the time part (formatted as HH:MM:SS or HH:MM) from a date/time string.
  
= Variable operations =
+
== 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.
+
Variables can be used to store strings and numbers. They cannot store truth values. They are best used to store intermediate results that you need multiple times. Variable names are not case-sensitive.
  
 
For example:
 
For example:
Line 690: Line 700:
 
2000</pre>
 
2000</pre>
 
|}
 
|}
 +
 
=== $get(name) ===
 
=== $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 and is a non-empty string.
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) ===
 
=== $put(name,value) ===
 
+
Stores ''value'' in the variable ''name'' and returns ''value'' unaltered.
Stores ''value'' in the variable ''name'' and returns ''value'' unaltered
+
  
 
=== $puts(name,value) ===
 
=== $puts(name,value) ===
 +
Stores ''value'' in the variable ''name'' and returns nothing.
  
Stores ''value'' in the variable ''name'' and returns nothing
+
== Component-specific fields and functions ==
  
= Component-provided fields and functions on tracks =
+
This section lists fields and functions which are specific to certain components. Unless otherwise stated, the fields and functions are only usable in the context of those components.
  
This section lists components that provide additional fields and functions that are useable in the context of any track.
+
=== Now playing info ===
  
== Playback statistics ==
+
The following fields related to the currently playing item are only usable in certain locations outside of the playlist, e.g. in the status bar, the main window title and the copy command script.
  
* [http://www.foobar2000.org/beta/components.html Playback statistics homepage]
+
==== %playback_time% ====
* [[Foobar2000:Titleformat Playback Statistics|Playback statistics titleformat reference]]
+
The elapsed time formatted as [HH:]MM:SS.
  
= Component-specific fields and functions =
+
==== %playback_time_seconds% ====
 +
The elapsed time in seconds.
 +
Old version: <code>%_time_elapsed%</code>
  
This section lists components that provide additional fields and functions that are only usable in the context of the particular component.
+
==== %playback_time_remaining% ====
 +
The time remaining until the track ends, formatted as [HH:]MM:SS.
 +
Old version: <code>%_time_remaining%</code>
  
== Album list ==
+
==== %playback_time_remaining_seconds% ====
 +
The time remaining until the track ends, in seconds.
 +
Old version: <code>%_time_remaining_seconds%</code>
  
The official album list component supports creating multiple tree entries using special commands.
+
=== Playlist-only fields ===
  
* [http://www.foobar2000.org/ Album list homepage]
+
The following fields are only usable in playlist display formatting (i.e., the column title formatting patterns).
* [[Foobar2000:Titleformat Album List|Album list titleformat reference]]
+
  
== Columns UI ==
+
==== %isplaying% ====
 +
"1" if file is currently playing, empty string otherwise.
  
* [http://music.morbo.org/wiki/columns_ui:manual Columns UI homepage]
+
==== %ispaused% ====
* [http://music.morbo.org/wiki/columns_ui:config:global_variables Global variables reference]
+
"1" if playback is paused, empty string otherwise.
* [http://music.morbo.org/wiki/columns_ui:config:colour_string Playlist colors reference]
+
* [http://music.morbo.org/wiki/columns_ui:config:playlist_switcher_titleformatting Playlist switcher reference]
+
  
== Cwbowron's titleformatting (foo_cwb_hooks) ==
+
==== %list_index% ====
 +
A zero-padded playlist index of specified item. The first item is at index 1.
  
Cwbowron's titleformatting, <tt>foo_cwb_hooks</tt>, adds various functions and variables to global titleformatting.
+
==== %list_total% ====
 +
The number of items in the playlist.
 +
 
 +
==== %queue_index% ====
 +
Index of the specified item in the playback queue. If the item has been queued multiple times, %queue_index% evaluates to the first index.
 +
 
 +
==== %queue_indexes% ====
 +
List of indexes of the specified item in the playback queue. Same as %queue_index% unless the item has been queued more than once.
 +
 
 +
==== %queue_total% ====
 +
Total amount of tracks in playback queue. Available only for queued tracks, for technical reasons.
 +
 
 +
=== Playlist text color ===
 +
 
 +
==== Dimmed and highlighted text ====
 +
 
 +
In the Default UI playlist, text color can be adjusted by enclosing it in angle-brackets. The only options are to make the text dimmer (mixing the default color with the background color) or brighter (mixing the default color with the highlight color):
 +
 
 +
* ''&lt;text>'' – dim ''text''
 +
* ''&lt;&lt;text>>'' – dimmer ''text''
 +
* ''&lt;&lt;&lt;text>>>'' – dimmest ''text''
 +
* ''>text&lt;'' – bright ''text''
 +
* ''>>text&lt;&lt;'' – brighter ''text''
 +
* ''>>>text&lt;&lt;&lt;'' – brightest ''text''
 +
 
 +
==== Historical and Columns UI color functions ====
 +
 
 +
Prior to version 1.0, the default UI playlist supported the following color functions, which are still available in the Columns UI playlist:
 +
 
 +
===== $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.
 +
 
 +
===== $hsl() =====
 +
Resets the text color to the default color.
 +
 
 +
===== $hsl(h,s,l) =====
 +
Sets the color for text in the HSL color space. ''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 240; the function is designed to interpret those values in the same way as the standard Windows color dialog.
 +
 
 +
===== $hsl(h1,s1,l1,h2,s2,l2) =====
 +
Sets the color for text in the HSL color space. ''h1'', ''s1'' and ''l1'' are the hue, saturation, and lightness of the color for unselected text. ''h2'', ''s2'' and ''l2'' are the hue, saturation, and lightness of the color for selected text.
 +
 
 +
===== $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 of the color for 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''.
 +
 
 +
=== Album List ===
 +
 
 +
* [[Foobar2000:Titleformat_Album_List|Album List Title Formatting]]
 +
* [[Foobar2000:Preferences:Album List|Preferences: Album List]]
 +
 
 +
=== Playback Statistics ===
 +
 
 +
The foo_playcount component adds a number of fields for playback statistics and ratings. The fields can be used anywhere track info can be displayed. See the documentation for details:
 +
* [http://www.foobar2000.org/components/view/foo_playcount Playback statistics homepage]
 +
* [[Foobar2000:Titleformat Playback Statistics|Playback statistics titleformat reference]]
  
* [[Foobar2000:Components 0.9/Cwbowron's Title formating (foo cwb hooks)|foo_cwb_hooks titleformat reference]]
+
=== Playlist Organizer ===
  
== Panels UI ==
+
This component adds a number of fields to control the display of a list of playlists. See the documentation for details:
 +
* [[Foobar2000:Components/Playlist Organizer (foo_plorg)#Nodes|Playlist Organizer: Nodes Title Formatting]]
  
* [[Foobar2000:Components 0.9/Panels UI (foo ui panels)|Panels UI]]
+
=== Columns UI ===
* [[Foobar2000:Components 0.9/Panels UI (foo ui panels)/Commands|Panels UI titleformat reference]]
+
  
= Additional Reading =
+
This component replaces the Default UI framework, including the playlist. See the documentation for details:
 +
* [http://yuo.be/columns.php Columns UI homepage]
 +
* [http://yuo.be/wiki/columns_ui:config:global_variables Global variables reference]
 +
* [http://yuo.be/wiki/columns_ui:config:colour_string Playlist colors reference]
 +
* [http://yuo.be/wiki/columns_ui:config:playlist_switcher_titleformatting Playlist switcher reference]
  
* [[Foobar2000:Titleformat_Introduction|Introduction to titleformat scripts]]
+
== Additional Reading ==
* '''titleformat_help.html''' in your Foobar2000 directory (ie C:\Program Files\foobar2000\titleformat_help.html) file:///C:/Program%20Files/foobar2000/titleformat_help.html
+
  
 +
* [[Foobar2000:Title Formatting Introduction|Introduction to titleformat scripts]]
 +
* The file '''titleformat_help.html''' in your Foobar2000 directory, e.g. file:///C:/Program%20Files%20(x86)/foobar2000/titleformat_help.html
  
 
[[Category:foobar2000 Guides|Titleformat Reference]]
 
[[Category:foobar2000 Guides|Titleformat Reference]]

Latest revision as of 08:56, 1 March 2021

Foobar2000_Logo.png

This article contains information about built-in title formatting functions and field references, plus additional documentation about fields and functions which can only be used in specific components or which are provided by specific components.

Please see Title Formatting Introduction for a general overview of title format syntax and its basic rules. The article Titleformat Examples offers user-submitted examples of code for specific purposes; feel free to add your own if you think it can be of use to others.

For details of the query syntax, which uses some of these fields to find files for playlists, etc., see the Query Syntax article.

Contents

Syntax[edit]

A title formatting script consists of any combination of literal text, field references, function calls, comments, and line break characters. The script always outputs a text string (which can be empty).

A comment is a line starting with two slashes, e.g. // this is a comment.

A field reference is a field name enclosed in percent signs, for example %artist%.

A function call starts with a dollar sign, followed by the function name and the parameter list. A parameter list can either be empty – denoted as () – or contain one or more parameters separated by commas, for example $abbr(%artist%). A parameter can be literal text, a field reference, or another function call. Note that there must be no whitespace between the dollar sign and the function name, or the function name and the opening parenthesis of the parameter list.

Any other text is literal text. In literal text, the character %, $, [, ], or ' (apostrophe/single quote) must be escaped by enclosing it in ' (apostrophe/single quote) characters. For example, '[' (a left bracket in single quotes) results in a literal [ (left bracket). As a special case, '' (two single quotes in a row) results in one single quote. In the playlist, < and > are also special; see Dimmed and highlighted text.

When the script is evaluated, the output string is assembled by evaluating the function parameters, function calls, and field references. Comments and line break characters (CR and LF/newline) are ignored; to output a line break, use $crlf(). Each field reference becomes the field's value, as a string. Each function becomes a string or number, and/or a truth value (not output) which can be used by another function.

Note: The interface for entering custom columns and grouping schemes for the Default UI playlist does not support line breaks; scripts must be written all on one line, without comments.

Arithmetic functions[edit]

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. Decimal points are not supported. Examples:

  • c3po → 0
  • 4.8 → 4
  • -12 → -12
  • - 12 → 0

$add(a,b, ...)[edit]

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)[edit]

Divides a by b and rounds down to an integer. 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)[edit]

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

$max(a,b)[edit]

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)[edit]

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)[edit]

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)[edit]

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)[edit]

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

$rand()[edit]

Generates a random number in the range from 0 to 232-1. Available only in sort-related contexts, such as the Edit → Sort → Sort by ... menu command.

$sub(a,b)[edit]

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[edit]

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.

Foobar does not have a concept of TRUE and FALSE in a programming language sense where 0 or empty string are considered FALSE and other values TRUE. Therefore there is no difference between numeric 0 and string representation '0' which both are considered as values, and being attached a boolean value FALSE. Apostrophes are only required to escape certain syntax characters. Values are treated as numbers during arithmetic operations like $add().

$and(expr, ...)[edit]

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

$or(expr, ...)[edit]

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

$not(expr)[edit]

Logical Not. Returns the logical opposite of EXPR: false, if expr is true and true if expr is false.

$xor(expr,...)[edit]

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

Special case: $xor(expr1,expr2) returns true, if EXPR1 or EXPR2 is true. If both expressions are true, returns false.

Control flow functions[edit]

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

[...] (conditional section)[edit]

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)[edit]

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

Plain strings are FALSE. Field lookups and functions can introduce a boolean value of TRUE.
Examples:
1

#False: 
$if(0,True,False)
# False: 
$if('0',True,False)
# True or False: 
[$add(%rating%,1)]


The last one would display the value of %rating% plus one, if and only if %rating% is set for the track.

2 Ignore inserting the %album artist%, if it contains the word "various".

# Wrong: 
$if([%album artist%=Various],,%artist%-)
# Good approach:
$if($stricmp(%album artist%,Various),,%artist%-) 

$if(cond,then,else)[edit]

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(expr,else)[edit]

Like $if(expr,expr,else) except that expr is only evaluated once. In other words, if expression expr is true, expr is returned, otherwise the else part is evaluated and expr is returned as true.

$if3(a1,a2,...,aN,else)[edit]

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.

$ifequal(int1,int2,then,else)[edit]

Compares the integer numbers int1 and int2, if int1 is equal to int2, the then part is evaluated and its value returned. Otherwise the else part is evaluated and its value returned.

$ifgreater(int1,int2,then,else)[edit]

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

$iflonger(str,n,then,else)[edit]

Compares the length of the string str to the number n, if str is longer than n characters, the then part is evaluated and its value returned. Otherwise the else part is evaluated and its value returned.

$select(n,a1,...,aN)[edit]

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

String functions[edit]

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

$abbr(str)[edit]

Returns abbreviation of string str. Words which begin with an alphanumeric character are shortened to the first character. Spaces and parentheses are stripped. Example:

  • $abbr('This is a Long Title (12-inch version) [needs tags]') → TiaLT1v[needst

$abbr(str,len)[edit]

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

$ansi(str)[edit]

Converts string str 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(str)[edit]

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

$caps(str)[edit]

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

$caps2(str)[edit]

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

$char(nbr)[edit]

Returns Unicode character of nbr. You can search for characters and find the matching decimal number on this site.

$crc32(str)[edit]

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

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

$crlf()[edit]

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(str,len)[edit]

Returns first len characters from the left of the string str. This function is the same as $left(a,len). Negative numbers produce the entire string. Examples:

  • $cut('abc123',3) → abc
  • $cut('abc123',0) → (nothing)
  • $cut('abc123',-1) → abc123

$directory(path)[edit]

Extracts directory name from the file path.

$directory(path,n)[edit]

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

$directory_path(path)[edit]

Extracts directory path from the file path.

$ext(path)[edit]

Extracts file extension from string path; a file name or full path.

$filename(path)[edit]

Extracts file name from full path.

$fix_eol(str)[edit]

If str 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 str is returned unaltered.

$fix_eol(str,indicator)[edit]

If str 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 str is returned unaltered.

$hex(int,len)[edit]

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

$insert(str,insert,n)[edit]

Inserts insert into str after n characters.

$left(str,len)[edit]

Returns first len characters from the left of the string str. This function is the same as $cut(str,len). Negative numbers produce the entire string. Examples:

  • $left('abc123',3) → abc
  • $left('abc123',0) → (nothing)
  • $left('abc123',-1) → abc123

$len(str)[edit]

Returns length of string str in characters.

$len2(str)[edit]

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

$longer(str1,str2)[edit]

Returns true, if string str1 is longer than string str2, false otherwise.

$lower(str)[edit]

Converts string str to lowercase.

$longest(arg,...)[edit]

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

$num(nbr,len)[edit]

Formats the integer number nbr in decimal notation with len characters. Pads with zeros from the left if necessary. len includes the dash when the number is negative. If nbr is not numeric, it is treated as zero. Examples:

  • $num(123,5) → 00123
  • $num(-123,5) → -0123
  • $num(4.8,5) → 00004
  • $num(A1,5) → 00000

$pad(str,len)[edit]

Creates a left-aligned version of the string str. If str is shorter than len characters, the function adds spaces to the right of str to make the result len characters long. Otherwise the function returns str unchanged.

$pad_right(str,len)[edit]

Creates a right-aligned version of the string str. If str is shorter than len characters, the function adds spaces to the left of str to make the result len characters long. Otherwise the function returns str unchanged.

$pad(str,len,char)[edit]

Creates a left-aligned version of the string str. If str is shorter than len characters, the function adds char to the right of str to make the result len characters long. Otherwise the function returns str unchanged.

$pad_right(str,len,char)[edit]

Creates a right-aligned version of the string str. If str is shorter than len characters, the function adds char to the left of str to make the result len characters long. Otherwise the function returns str unchanged.

$padcut(str,len)[edit]

Returns first len characters from the left of str, if str is longer than len characters. Otherwise adds spaces to the right of str to make the result len characters long.

$padcut(str,len,char)[edit]

Returns first len characters from the left of str, if str is longer than len characters. Otherwise adds char to the right of str to make the result len characters long.

$padcut_right(str,len)[edit]

Returns first len characters from the left of str, if str is longer than len characters. Otherwise adds spaces to the left of str to make the result len characters long.

$padcut_right(str,len,char)[edit]

Returns first len characters from the left of str, if str is longer than len characters. Otherwise adds char to the left of str to make the result len characters long.

$progress(pos,range,len,char1,char2)[edit]

Creates a progress bar: pos contains position, range contains range, len progress bar length in characters, char1 and char2 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,char1,char2)[edit]

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

$repeat(expr,count)[edit]

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

$replace(str,search,replace)[edit]

Replaces all occurrences of string search in string str with string replace.

Can also be used with an arbitrary number of arguments. Note that $replace(str,search1,replace1,search2,replace2) is generally not the same as $replace($replace(str,search1,replace1),search2,replace2).

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

$right(str,len)[edit]

Returns the first len characters from the right of string str.

$roman(int)[edit]

Formats the integer number int in roman notation.

$rot13(str)[edit]

Performs ROT13 transformation to given string.

Example: $rot13('foobar2000') → "sbbone2000".

$shortest(str,...strN)[edit]

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

$strchr(str,char)[edit]

Returns position of first occurrence of character char in string str.

Example: $strchr(abca,a) → 1

$strrchr(str,char)[edit]

Returns positions of last occurrence of character char in string str.

Example: $strrchr(abca,a) → 4

$strstr(str1,str2)[edit]

Returns position of first occurrence of string str2 in string str1. Function is case-sensitive.

$strcmp(str1,str2)[edit]

Performs a case-sensitive comparison of the strings str1 and str2.

$stricmp(str1,str2)[edit]

Performs a case-insensitive comparison of the strings str1 and str2.

$stripprefix(str)[edit]

Removes A and The prefixes from string str.

$stripprefix(str,prefix1,prefix2,...)[edit]

Removes the specified prefixes from string str.

$substr(str,from,to)[edit]

Returns substring of string str, starting from FROM-th character and ending at TO-th character.

$swapprefix(str)[edit]

Moves A and The prefixes to the end of string str.

$swapprefix(str,prefix1,prefix2,...)[edit]

Moves the specified prefixes to the end of string str.

$trim(str)[edit]

Removes leading and trailing spaces from string str.

$tab()[edit]

Inserts one tabulator character.

$tab(count)[edit]

Inserts count tabulator characters.

$upper(str)[edit]

Converts string str to uppercase.

Track info fields and functions[edit]

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

Metadata fields and functions[edit]

Generally, metadata from the files (whether in tags or a cue sheet) is mapped directly to a field which can be referenced case-insensitively. For example, the first tag named URL can be referenced as %url%, and the first standard comment tag can be referenced as %comment%.

The following functions are also available for accessing metadata:

$meta(name)[edit]

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

Example: $meta(artist) → "He, She, They"

$meta(name,n)[edit]

Returns value of n-th (0,1,2 and so on) tag called name.

Example: $meta(artist,1) → "She"

$meta_sep(name,sep)[edit]

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 + They"

$meta_sep(name,sep,lastsep)[edit]

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: $meta_sep(artist,', ',', and ') → "He, She, and They"

$meta_test(...)[edit]

Returns 1, if all given tags exist, undefined otherwise.

Example: $meta_test(artist,title) → true

$meta_num(name)[edit]

Returns the number of values for the tag called name.

Example: $meta_num(artist) → 3

Remapped metadata fields[edit]

The following fields have special remapped values to make writing title format scripts more convenient:

%album artist%[edit]

Name of the artist of the album specified track belongs to. Checks following metadata fields, in this order: "album artist", "artist", "composer", "performer". The difference between this and %artist% is that %album artist% is intended for use where consistent value across entire album is needed even when per-track artists values vary.

%album%[edit]

Name of the album specified track belongs to. Checks following metadata fields, in this order: "album", "venue".

%artist%[edit]

Name of the artist of the track. Checks following metadata fields, in this order: "artist", "album artist", "composer", "performer". For a SHOUTcast stream which contains metadata, it is the StreamTitle up to the first "-" character.

%discnumber%[edit]

Index of disc specified track belongs to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.

%totaldiscs%[edit]

Index of total discs specified tracks belong to, within the album. Available only when "discnumber"/"disc" field is present in track’s metadata.

%track artist%[edit]

Name of the artist of the track; present only if %album artist% is different than %artist% for specific track. Intended for use together with %album artist%, to indicate track-specific artist info, e.g. "%album artist% - %title%[ '//' %track artist%]". In this case, the last part will be displayed only when track-specific artist info is present.

%title%[edit]

Title of the track. If "title" metadata field is missing, file name is used instead. For a SHOUTcast stream which contains metadata, it is the StreamTitle after the first "-" character.

%tracknumber%[edit]

Two-digit index of specified track within the album. Available only when "tracknumber" field is present in track’s metadata. An extra '0' is placed in front of single digit track numbers (5 becomes 05).

%track number%[edit]

Similar to %tracknumber%, however single digit track numbers are not reformatted to have an extra 0.

Technical information fields[edit]

%bitrate%[edit]

Bitrate of the track in kilobits per second. VBR files will show a dynamic display for currently played track (outside of the playlist).

%channels%[edit]

Number of channels in the track, as text; either "mono", "stereo" for 1 or 2 channels, respectively, otherwise a number followed by "ch", e.g. "6ch".

%codec%[edit]

Name of codec used to encode the track, e.g. PCM, FLAC, MP3, or AAC. If exact codec name is not available, file extension is used. The Default UI's standard Codec column displays the same info, but sometimes adds details, e.g. "MP3 / VBR V2" or "AAC / LC".

%filesize%[edit]

The exact file size in bytes. Old version: %_filesize%

%filesize_natural%[edit]

The approximate file size, automatically formatted in appropriate units such as megabytes or kilobytes, e.g. "8.49 MB"

%length%[edit]

The length of the track formatted as hours, minutes, and seconds, rounded to the nearest second. Old version: %_time_total%

%length_ex%[edit]

The length of the track formatted as hours, minutes, seconds, and milliseconds, rounded to the nearest millisecond.

%length_seconds%[edit]

The length of the track in seconds, rounded to the nearest second. Old version: %_time_total_seconds%

%length_seconds_fp%[edit]

The length of the track in seconds as a floating point number.

%length_samples%[edit]

The length of the track in samples.

%samplerate%[edit]

Sample rate of the track, in Hz.

Technical information functions[edit]

$info(name)[edit]

Returns value of technical information field called name.

For convenience, the %__name% alias is also available.

Example: $info(channels) → 2

Here is an informative list of recognized fields. Some of these depend on the media file type being queried.

field name Description
General
codec Codec (e.g. MP3)
codec_profile Codec Profile (e.g. CBR)
samplerate Sample Rate, in hertz (e.g. 44100)
bitrate Bitrate, in kilobits per second (e.g. 320)
tool Tool used to produce the file, possibly guessed (e.g. LAME3.97)
encoding Encoding lossiness (e.g. lossy)
channels Channels count (e.g. 2 [for stereo])
channel_mode Channel Mode, description of channels (e.g. 3 front, 2 rear surround channels + LFE)
bitspersample Bits Per Sample (e.g. 16)
tagtype Tag Type, comma-separated list of tag formats (e.g. id3v2|apev2)
cue_embedded Embedded Cuesheet presence (e.g. no [may be empty!])
md5 Audio MD5 hash, if container defines it (e.g. 1E24A910D91EF09A8CF403C9B6963961)
Other
ENC_DELAY LAME proprietary MP3 enc_delay value for gapless playback (e.g. 576)
ENC_PADDING LAME proprietary MP3 enc_padding value for gapless playback (e.g. 1536)
MP3_ACCURATE_LENGTH MP3 duration (%length% etc.) takes into account LAME or iTunes gapless playback info (e.g. yes)*
MP3_STEREO_MODE Stereo mode used in MP3 file (e.g. mono, stereo, joint stereo, etc.)
VERSION Version of tool (e.g. 3.99)
FLAGS Flags of tool (e.g. 22)


* MP3_ACCURATE_LENGTH won't exist if gapless playback info isn't present or the file is not an MP3. The info can be in a LAME tag in the VBR header, or in an iTunSMPB ID3v2 comment tag. Gapless playback info is taken into account in .m4a files, but there's no special field to say so.

$channels()[edit]

The number of channels in text format.

Example: $channels() → "stereo"

%replaygain_album_gain%[edit]

The ReplayGain album gain value.

%replaygain_album_peak%[edit]

The ReplayGain album peak value.

%replaygain_album_peak_db%[edit]

The ReplayGain album peak value in decibels.

%replaygain_track_gain%[edit]

The ReplayGain track gain value.

%replaygain_track_peak%[edit]

The ReplayGain track peak value.

%replaygain_track_peak_db%[edit]

The ReplayGain track peak value in decibels.

Special fields[edit]

%filename%[edit]

The filename without directory and extension.

%filename_ext%[edit]

The filename with extension, but without the directory.

%directoryname%[edit]

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

%last_modified%[edit]

The date and time the file was last modified. Eg: 2005-12-22 00:04:10

%path%[edit]

The complete path, including the filename and extension.

%_path_raw%[edit]

The path as URL including the protocol scheme.

%subsong%[edit]

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%[edit]

A string representing the version of foobar2000.

Time and date functions[edit]

These functions are used to manipulate time/date strings, notably (but not limited to), those gathered by the Playback Statistics component.

$year(time)[edit]

Retrieves the year part (formatted as four digits) from a time/date string.

$month(time)[edit]

Retrieves the month part (formatted as two digits) from a time/date string.

$day_of_month(time)[edit]

Retrieves the day of month part (formatted as two digits) from a time/date string.

$date(time)[edit]

Retrieves the date part (formatted as YYYY-MM-DD) from a time/date string.

$time(time)[edit]

Retrieves the time part (formatted as HH:MM:SS or HH:MM) from a date/time string.

Variable operations[edit]

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

For example:

code output
$put(foo,bar)$char(10)
$get(foo)$char(10)
$get(Foo)$char(10)
$puts(foo,2000)$char(10)
$get(foo)$char(10)
bar
bar
bar

2000

$get(name)[edit]

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 and is a non-empty string.

$put(name,value)[edit]

Stores value in the variable name and returns value unaltered.

$puts(name,value)[edit]

Stores value in the variable name and returns nothing.

Component-specific fields and functions[edit]

This section lists fields and functions which are specific to certain components. Unless otherwise stated, the fields and functions are only usable in the context of those components.

Now playing info[edit]

The following fields related to the currently playing item are only usable in certain locations outside of the playlist, e.g. in the status bar, the main window title and the copy command script.

%playback_time%[edit]

The elapsed time formatted as [HH:]MM:SS.

%playback_time_seconds%[edit]

The elapsed time in seconds. Old version: %_time_elapsed%

%playback_time_remaining%[edit]

The time remaining until the track ends, formatted as [HH:]MM:SS. Old version: %_time_remaining%

%playback_time_remaining_seconds%[edit]

The time remaining until the track ends, in seconds. Old version: %_time_remaining_seconds%

Playlist-only fields[edit]

The following fields are only usable in playlist display formatting (i.e., the column title formatting patterns).

%isplaying%[edit]

"1" if file is currently playing, empty string otherwise.

%ispaused%[edit]

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

%list_index%[edit]

A zero-padded playlist index of specified item. The first item is at index 1.

%list_total%[edit]

The number of items in the playlist.

%queue_index%[edit]

Index of the specified item in the playback queue. If the item has been queued multiple times, %queue_index% evaluates to the first index.

%queue_indexes%[edit]

List of indexes of the specified item in the playback queue. Same as %queue_index% unless the item has been queued more than once.

%queue_total%[edit]

Total amount of tracks in playback queue. Available only for queued tracks, for technical reasons.

Playlist text color[edit]

Dimmed and highlighted text[edit]

In the Default UI playlist, text color can be adjusted by enclosing it in angle-brackets. The only options are to make the text dimmer (mixing the default color with the background color) or brighter (mixing the default color with the highlight color):

  • <text> – dim text
  • <<text>> – dimmer text
  • <<<text>>> – dimmest text
  • >text< – bright text
  • >>text<< – brighter text
  • >>>text<<< – brightest text

Historical and Columns UI color functions[edit]

Prior to version 1.0, the default UI playlist supported the following color functions, which are still available in the Columns UI playlist:

$blend(color1,color2,part,total)[edit]

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.

$hsl()[edit]

Resets the text color to the default color.

$hsl(h,s,l)[edit]

Sets the color for text in the HSL color space. 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 240; the function is designed to interpret those values in the same way as the standard Windows color dialog.

$hsl(h1,s1,l1,h2,s2,l2)[edit]

Sets the color for text in the HSL color space. h1, s1 and l1 are the hue, saturation, and lightness of the color for unselected text. h2, s2 and l2 are the hue, saturation, and lightness of the color for selected text.

$rgb()[edit]

Resets the text color to the default color.

$rgb(r,g,b)[edit]

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)[edit]

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 of the color for selected text.

$transition(string,color1,color2)[edit]

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.

Album List[edit]

Playback Statistics[edit]

The foo_playcount component adds a number of fields for playback statistics and ratings. The fields can be used anywhere track info can be displayed. See the documentation for details:

Playlist Organizer[edit]

This component adds a number of fields to control the display of a list of playlists. See the documentation for details:

Columns UI[edit]

This component replaces the Default UI framework, including the playlist. See the documentation for details:

Additional Reading[edit]