Hydrogenaudio Knowledgebase - User contributions [en]

Foobar2000:Title Formatting Reference

2014-04-02T20:21:17Z

Alwayswrming: /* $select(n,a1,...,aN) */

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

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

For details of the query syntax, which uses some of these fields to find files for playlists, etc., see: [[Foobar2000:Query_syntax|Query Syntax]].

= Field remappings =

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

== Metadata ==

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

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

=== %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 ==

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

=== %filesize_natural% ===
Size of the file, automatically formatted in appropriate units such as megabytes or kilobytes.

=== %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. In other words, if ''a'' is true, ''a'' is returned, otherwise the ''else'' part is evaluated and its value returned.

=== $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(s,n,then,else) ===

Compares the length of the string ''s'' to the number ''n'', if ''s'' 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) ===

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

=== $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'' 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) ===

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 232-1. Available only in sort-related contexts, such as the ''Edit → Sort → Sort by ...'' menu command.

=== $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 =

==For the Default User Interface==
Starting in version 1.0, the Default UI playlist view doesn't support color functions. In that location, text color can only be adjusted via angle-bracket syntax: Use < and > characters to make specific text <dimmed> ''vs.'' the default color or >highlight>ed with the highlight color, with up to three levels in each case, ''e.g.'': <dimmed>, >highlight<, >>more highlight<<, <<<very dim>>>.

==For Columns UI==

The playlist in the Columns UI still supports the following 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.

=== $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''.

= 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 ==

=== %playback_time% ===
Returns the elapsed time formatted as [HH:]MM:SS.

=== %playback_time_seconds% ===
Returns elapsed time in seconds.
Old version: <code>%_time_elapsed%</code>

=== %playback_time_remaining% ===
Returns remaining time until track ends, formatted as [HH:]MM:SS.
Old version: <code>%_time_remaining%</code>

=== %playback_time_remaining_seconds% ===
Returns remaining time in seconds.
Old version: <code>%_time_remaining_seconds%</code>

=== %length% ===
Returns the length of the track formatted as hours, minutes, and seconds, rounded to the nearest second.
Old version: <code>%_time_total%</code>

=== %length_ex% ===
Returns the length of the track formatted as hours, minutes, seconds, and milliseconds, rounded to the nearest millisecond.

=== %length_seconds% ===
Returns the length of the track in seconds, rounded to the nearest second.
Old version: <code>%_time_total_seconds%</code>

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

= Playlist info =
The following functions and fields are usable for playlist display formatting (eg. per-column title formatting patterns).

== Special fields ==

=== %isplaying% ===

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

=== %ispaused% ===

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

=== %list_index% ===

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

=== %list_total% ===

Returns number of items in the playlist.

=== %queue_index% ===

Index of the specified item in the playback queue; available in playlist only. 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; available in playlist only. 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.

= String functions =

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

=== $abbr(x) ===

Returns abbreviation of ''x''. 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(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''. You can search for characters and find the matching decimal number on this [http://www.fileformat.info/info/unicode/char/search.htm site].

=== $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 from the left of the string ''a''. 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(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.

=== $directory_path(x) ===

Extracts directory path from the file path ''x''.

=== $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 first ''len'' characters from the left of the string ''a''. This function is the same as $cut(a,len). Negative numbers produce the entire string. Examples:
* $left('abc123',3) → abc
* $left('abc123',0) → (nothing)
* $left('abc123',-1) → abc123

=== $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'' characters. Pads with zeros from the left if necessary. ''len'' includes the dash when the number is negative. If ''n'' 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(x,len) ===

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

=== $pad_right(x,len) ===

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

=== $pad(x,len,char) ===

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

=== $pad_right(x,len,char) ===

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

=== $padcut(x,len) ===

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

=== $padcut_right(x,len) ===

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

=== $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 [http://en.wikipedia.org/wiki/ROT13 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.

=== $stripprefix(x) ===

Removes ''A'' and ''The'' prefixes from x.

=== $stripprefix(x,prefix1,prefix2,...) ===

Removes the specified prefixes from x.

=== $swapprefix(x) ===

Moves ''A'' and ''The'' prefixes to the end of x.

=== $swapprefix(x,prefix1,prefix2,...) ===

Moves the specified prefixes to the end of x.

=== $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 (0,1,2 and so on) tag called ''name''.

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

=== $meta_test(...) ===
Returns ''1'', if all given tags exist, ''undefined'' otherwise.

Example: ''$meta_test(artist,title)'' → true

=== $meta_num(name) ===
Returns the number of values for the tag called ''name''.

Example: ''$meta_num(artist)'' → 3

== Technical information ==

=== $info(name) ===
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.

{| border="0" cellspacing="0" cellpadding="2"
! field name
! Description
|-
| colspan="2" style="background-color:#CCF"|'''General'''
|-
|codec
| style="background-color:#EEF"|'''Codec''' (''e.g.'' MP3)
|-
|codec_profile
| style="background-color:#EEF"|'''Codec Profile''' (''e.g.'' CBR)
|-
|samplerate
| style="background-color:#EEF"|'''Sample Rate''', in hertz (''e.g.'' 44100)
|-
|bitrate
| style="background-color:#EEF"|'''Bitrate''', in kilobits per second (''e.g.'' 320)
|-
|tool
| style="background-color:#EEF"|'''Tool''' used to produce the file, possibly guessed (''e.g.'' LAME3.97)
|-
|encoding
| style="background-color:#EEF"|'''Encoding''' lossiness (''e.g.'' lossy)
|-
|channels
| 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
| style="background-color:#EEF"|'''Bits Per Sample''' (''e.g.'' 16)
|-
|tagtype
| style="background-color:#EEF"|'''Tag Type''', comma-separated list of tag formats (''e.g.'' id3v2|apev2)
|-
|cue_embedded
| style="background-color:#EEF"|'''Embedded Cuesheet''' presence (''e.g.'' no <nowiki>[may be empty!]</nowiki>)
|-
|md5
| style="background-color:#EEF"|'''Audio MD5''' hash, if container defines it (''e.g.'' 1E24A910D91EF09A8CF403C9B6963961)
|-
| colspan="2" style="background-color:#CCF"|'''Other'''
|-
|ENC_DELAY
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_delay''' value (''e.g.'' 576)
|-
|ENC_PADDING
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_padding''' value (''e.g.'' 1536)
|-
|MP3_ACCURATE_LENGTH
| style="background-color:#EEF"|'''mp3_accurate_length''' supported (LAME proprietary header)? (''e.g.'' yes)
|-
|MP3_STEREO_MODE
| style="background-color:#EEF"|Stereo mode used in MP3 file (''e.g.'' mono, stereo, joint stereo, etc.)
|-
|VERSION
| style="background-color:#EEF"|'''Version''' of tool (''e.g.'' 3.99)
|-
|FLAGS
| style="background-color:#EEF"|'''Flags''' of tool (''e.g.'' 22)
|}

=== $channels() ===
Returns number of channels in text format.

Example: ''$channels()'' → "stereo"

=== %replaygain_album_gain% ===

Returns ReplayGain album gain value.

=== %replaygain_album_peak% ===

Returns ReplayGain album peak value.

=== %replaygain_track_gain% ===

Returns ReplayGain track gain value.

=== %replaygain_track_peak% ===

Returns ReplayGain track peak value.

== Special fields ==

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

==== %last_modified% ====

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

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

= Time/Date Functions =

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

=== $year(time) ===

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

=== $month(time) ===

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

=== $day_of_month(time) ===

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 =

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.

For example:
{| border="0" cellspacing="0" cellpadding="2"
! code
! output
|-
|<pre>$put(foo,bar)$char(10)
$get(foo)$char(10)
$get(Foo)$char(10)
$puts(foo,2000)$char(10)
$get(foo)$char(10)</pre>
| style="background-color:#EEF" |<pre>bar
bar
bar

2000</pre>
|}
=== $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 nothing

= 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 ==

* [http://www.foobar2000.org/components/view/foo_playcount Playback statistics homepage]
* [[Foobar2000:Titleformat Playback Statistics|Playback statistics titleformat reference]]

= Component-specific fields and functions =

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

== Album list ==
* [[Foobar2000:Titleformat_Album_List|Album List Title Formatting]]
* [[Foobar2000:Preferences:Album List|Preferences: Album List]]
== Playlist Organizer ==
* [http://wiki.hydrogenaudio.org/index.php?title=Foobar2000:Components/Playlist_Organizer_(foo_plorg)#Nodes Playlist Organizer: Nodes Title Formatting]

== Columns UI ==

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

= Additional Reading =

* [[Foobar2000:Titleformat_Introduction|Introduction to titleformat scripts]]
* '''titleformat_help.html''' in your Foobar2000 directory (ie C:\Program Files\foobar2000\titleformat_help.html) file:///C:/Program%20Files/foobar2000/titleformat_help.html

[[Category:foobar2000 Guides|Titleformat Reference]]

Foobar2000:Title Formatting Reference

2014-04-02T20:20:49Z

Alwayswrming: /* $select(n,a1,...,aN) */

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

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

For details of the query syntax, which uses some of these fields to find files for playlists, etc., see: [[Foobar2000:Query_syntax|Query Syntax]].

= Field remappings =

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

== Metadata ==

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

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

=== %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 ==

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

=== %filesize_natural% ===
Size of the file, automatically formatted in appropriate units such as megabytes or kilobytes.

=== %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. In other words, if ''a'' is true, ''a'' is returned, otherwise the ''else'' part is evaluated and its value returned.

=== $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(s,n,then,else) ===

Compares the length of the string ''s'' to the number ''n'', if ''s'' 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) ===

If the value of ''n'' is between 1 and N, ''n'' 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

=== $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'' 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) ===

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 232-1. Available only in sort-related contexts, such as the ''Edit → Sort → Sort by ...'' menu command.

=== $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 =

==For the Default User Interface==
Starting in version 1.0, the Default UI playlist view doesn't support color functions. In that location, text color can only be adjusted via angle-bracket syntax: Use < and > characters to make specific text <dimmed> ''vs.'' the default color or >highlight>ed with the highlight color, with up to three levels in each case, ''e.g.'': <dimmed>, >highlight<, >>more highlight<<, <<<very dim>>>.

==For Columns UI==

The playlist in the Columns UI still supports the following 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.

=== $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''.

= 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 ==

=== %playback_time% ===
Returns the elapsed time formatted as [HH:]MM:SS.

=== %playback_time_seconds% ===
Returns elapsed time in seconds.
Old version: <code>%_time_elapsed%</code>

=== %playback_time_remaining% ===
Returns remaining time until track ends, formatted as [HH:]MM:SS.
Old version: <code>%_time_remaining%</code>

=== %playback_time_remaining_seconds% ===
Returns remaining time in seconds.
Old version: <code>%_time_remaining_seconds%</code>

=== %length% ===
Returns the length of the track formatted as hours, minutes, and seconds, rounded to the nearest second.
Old version: <code>%_time_total%</code>

=== %length_ex% ===
Returns the length of the track formatted as hours, minutes, seconds, and milliseconds, rounded to the nearest millisecond.

=== %length_seconds% ===
Returns the length of the track in seconds, rounded to the nearest second.
Old version: <code>%_time_total_seconds%</code>

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

= Playlist info =
The following functions and fields are usable for playlist display formatting (eg. per-column title formatting patterns).

== Special fields ==

=== %isplaying% ===

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

=== %ispaused% ===

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

=== %list_index% ===

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

=== %list_total% ===

Returns number of items in the playlist.

=== %queue_index% ===

Index of the specified item in the playback queue; available in playlist only. 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; available in playlist only. 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.

= String functions =

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

=== $abbr(x) ===

Returns abbreviation of ''x''. 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(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''. You can search for characters and find the matching decimal number on this [http://www.fileformat.info/info/unicode/char/search.htm site].

=== $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 from the left of the string ''a''. 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(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.

=== $directory_path(x) ===

Extracts directory path from the file path ''x''.

=== $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 first ''len'' characters from the left of the string ''a''. This function is the same as $cut(a,len). Negative numbers produce the entire string. Examples:
* $left('abc123',3) → abc
* $left('abc123',0) → (nothing)
* $left('abc123',-1) → abc123

=== $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'' characters. Pads with zeros from the left if necessary. ''len'' includes the dash when the number is negative. If ''n'' 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(x,len) ===

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

=== $pad_right(x,len) ===

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

=== $pad(x,len,char) ===

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

=== $pad_right(x,len,char) ===

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

=== $padcut(x,len) ===

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

=== $padcut_right(x,len) ===

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

=== $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 [http://en.wikipedia.org/wiki/ROT13 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.

=== $stripprefix(x) ===

Removes ''A'' and ''The'' prefixes from x.

=== $stripprefix(x,prefix1,prefix2,...) ===

Removes the specified prefixes from x.

=== $swapprefix(x) ===

Moves ''A'' and ''The'' prefixes to the end of x.

=== $swapprefix(x,prefix1,prefix2,...) ===

Moves the specified prefixes to the end of x.

=== $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 (0,1,2 and so on) tag called ''name''.

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

=== $meta_test(...) ===
Returns ''1'', if all given tags exist, ''undefined'' otherwise.

Example: ''$meta_test(artist,title)'' → true

=== $meta_num(name) ===
Returns the number of values for the tag called ''name''.

Example: ''$meta_num(artist)'' → 3

== Technical information ==

=== $info(name) ===
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.

{| border="0" cellspacing="0" cellpadding="2"
! field name
! Description
|-
| colspan="2" style="background-color:#CCF"|'''General'''
|-
|codec
| style="background-color:#EEF"|'''Codec''' (''e.g.'' MP3)
|-
|codec_profile
| style="background-color:#EEF"|'''Codec Profile''' (''e.g.'' CBR)
|-
|samplerate
| style="background-color:#EEF"|'''Sample Rate''', in hertz (''e.g.'' 44100)
|-
|bitrate
| style="background-color:#EEF"|'''Bitrate''', in kilobits per second (''e.g.'' 320)
|-
|tool
| style="background-color:#EEF"|'''Tool''' used to produce the file, possibly guessed (''e.g.'' LAME3.97)
|-
|encoding
| style="background-color:#EEF"|'''Encoding''' lossiness (''e.g.'' lossy)
|-
|channels
| 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
| style="background-color:#EEF"|'''Bits Per Sample''' (''e.g.'' 16)
|-
|tagtype
| style="background-color:#EEF"|'''Tag Type''', comma-separated list of tag formats (''e.g.'' id3v2|apev2)
|-
|cue_embedded
| style="background-color:#EEF"|'''Embedded Cuesheet''' presence (''e.g.'' no <nowiki>[may be empty!]</nowiki>)
|-
|md5
| style="background-color:#EEF"|'''Audio MD5''' hash, if container defines it (''e.g.'' 1E24A910D91EF09A8CF403C9B6963961)
|-
| colspan="2" style="background-color:#CCF"|'''Other'''
|-
|ENC_DELAY
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_delay''' value (''e.g.'' 576)
|-
|ENC_PADDING
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_padding''' value (''e.g.'' 1536)
|-
|MP3_ACCURATE_LENGTH
| style="background-color:#EEF"|'''mp3_accurate_length''' supported (LAME proprietary header)? (''e.g.'' yes)
|-
|MP3_STEREO_MODE
| style="background-color:#EEF"|Stereo mode used in MP3 file (''e.g.'' mono, stereo, joint stereo, etc.)
|-
|VERSION
| style="background-color:#EEF"|'''Version''' of tool (''e.g.'' 3.99)
|-
|FLAGS
| style="background-color:#EEF"|'''Flags''' of tool (''e.g.'' 22)
|}

=== $channels() ===
Returns number of channels in text format.

Example: ''$channels()'' → "stereo"

=== %replaygain_album_gain% ===

Returns ReplayGain album gain value.

=== %replaygain_album_peak% ===

Returns ReplayGain album peak value.

=== %replaygain_track_gain% ===

Returns ReplayGain track gain value.

=== %replaygain_track_peak% ===

Returns ReplayGain track peak value.

== Special fields ==

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

==== %last_modified% ====

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

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

= Time/Date Functions =

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

=== $year(time) ===

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

=== $month(time) ===

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

=== $day_of_month(time) ===

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 =

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.

For example:
{| border="0" cellspacing="0" cellpadding="2"
! code
! output
|-
|<pre>$put(foo,bar)$char(10)
$get(foo)$char(10)
$get(Foo)$char(10)
$puts(foo,2000)$char(10)
$get(foo)$char(10)</pre>
| style="background-color:#EEF" |<pre>bar
bar
bar

2000</pre>
|}
=== $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 nothing

= 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 ==

* [http://www.foobar2000.org/components/view/foo_playcount Playback statistics homepage]
* [[Foobar2000:Titleformat Playback Statistics|Playback statistics titleformat reference]]

= Component-specific fields and functions =

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

== Album list ==
* [[Foobar2000:Titleformat_Album_List|Album List Title Formatting]]
* [[Foobar2000:Preferences:Album List|Preferences: Album List]]
== Playlist Organizer ==
* [http://wiki.hydrogenaudio.org/index.php?title=Foobar2000:Components/Playlist_Organizer_(foo_plorg)#Nodes Playlist Organizer: Nodes Title Formatting]

== Columns UI ==

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

= Additional Reading =

* [[Foobar2000:Titleformat_Introduction|Introduction to titleformat scripts]]
* '''titleformat_help.html''' in your Foobar2000 directory (ie C:\Program Files\foobar2000\titleformat_help.html) file:///C:/Program%20Files/foobar2000/titleformat_help.html

[[Category:foobar2000 Guides|Titleformat Reference]]

Foobar2000:Title Formatting Reference

2014-04-02T20:01:52Z

Alwayswrming: /* $if2(a,else) */

Foobar2000:Title Formatting Reference

2014-04-02T20:00:52Z

Alwayswrming: /* $if2(a,else) */

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

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

For details of the query syntax, which uses some of these fields to find files for playlists, etc., see: [[Foobar2000:Query_syntax|Query Syntax]].

= Field remappings =

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

== Metadata ==

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

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

=== %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 ==

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

=== %filesize_natural% ===
Size of the file, automatically formatted in appropriate units such as megabytes or kilobytes.

=== %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. In other words, if ''a'' is true, ''a'' is returned, otherwise ''else'' is returned.

=== $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(s,n,then,else) ===

Compares the length of the string ''s'' to the number ''n'', if ''s'' 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) ===

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

=== $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'' 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) ===

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 232-1. Available only in sort-related contexts, such as the ''Edit → Sort → Sort by ...'' menu command.

=== $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 =

==For the Default User Interface==
Starting in version 1.0, the Default UI playlist view doesn't support color functions. In that location, text color can only be adjusted via angle-bracket syntax: Use < and > characters to make specific text <dimmed> ''vs.'' the default color or >highlight>ed with the highlight color, with up to three levels in each case, ''e.g.'': <dimmed>, >highlight<, >>more highlight<<, <<<very dim>>>.

==For Columns UI==

The playlist in the Columns UI still supports the following 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.

=== $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''.

= 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 ==

=== %playback_time% ===
Returns the elapsed time formatted as [HH:]MM:SS.

=== %playback_time_seconds% ===
Returns elapsed time in seconds.
Old version: <code>%_time_elapsed%</code>

=== %playback_time_remaining% ===
Returns remaining time until track ends, formatted as [HH:]MM:SS.
Old version: <code>%_time_remaining%</code>

=== %playback_time_remaining_seconds% ===
Returns remaining time in seconds.
Old version: <code>%_time_remaining_seconds%</code>

=== %length% ===
Returns the length of the track formatted as hours, minutes, and seconds, rounded to the nearest second.
Old version: <code>%_time_total%</code>

=== %length_ex% ===
Returns the length of the track formatted as hours, minutes, seconds, and milliseconds, rounded to the nearest millisecond.

=== %length_seconds% ===
Returns the length of the track in seconds, rounded to the nearest second.
Old version: <code>%_time_total_seconds%</code>

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

= Playlist info =
The following functions and fields are usable for playlist display formatting (eg. per-column title formatting patterns).

== Special fields ==

=== %isplaying% ===

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

=== %ispaused% ===

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

=== %list_index% ===

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

=== %list_total% ===

Returns number of items in the playlist.

=== %queue_index% ===

Index of the specified item in the playback queue; available in playlist only. 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; available in playlist only. 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.

= String functions =

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

=== $abbr(x) ===

Returns abbreviation of ''x''. 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(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''. You can search for characters and find the matching decimal number on this [http://www.fileformat.info/info/unicode/char/search.htm site].

=== $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 from the left of the string ''a''. 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(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.

=== $directory_path(x) ===

Extracts directory path from the file path ''x''.

=== $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 first ''len'' characters from the left of the string ''a''. This function is the same as $cut(a,len). Negative numbers produce the entire string. Examples:
* $left('abc123',3) → abc
* $left('abc123',0) → (nothing)
* $left('abc123',-1) → abc123

=== $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'' characters. Pads with zeros from the left if necessary. ''len'' includes the dash when the number is negative. If ''n'' 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(x,len) ===

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

=== $pad_right(x,len) ===

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

=== $pad(x,len,char) ===

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

=== $pad_right(x,len,char) ===

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

=== $padcut(x,len) ===

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

=== $padcut_right(x,len) ===

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

=== $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 [http://en.wikipedia.org/wiki/ROT13 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.

=== $stripprefix(x) ===

Removes ''A'' and ''The'' prefixes from x.

=== $stripprefix(x,prefix1,prefix2,...) ===

Removes the specified prefixes from x.

=== $swapprefix(x) ===

Moves ''A'' and ''The'' prefixes to the end of x.

=== $swapprefix(x,prefix1,prefix2,...) ===

Moves the specified prefixes to the end of x.

=== $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 (0,1,2 and so on) tag called ''name''.

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

=== $meta_test(...) ===
Returns ''1'', if all given tags exist, ''undefined'' otherwise.

Example: ''$meta_test(artist,title)'' → true

=== $meta_num(name) ===
Returns the number of values for the tag called ''name''.

Example: ''$meta_num(artist)'' → 3

== Technical information ==

=== $info(name) ===
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.

{| border="0" cellspacing="0" cellpadding="2"
! field name
! Description
|-
| colspan="2" style="background-color:#CCF"|'''General'''
|-
|codec
| style="background-color:#EEF"|'''Codec''' (''e.g.'' MP3)
|-
|codec_profile
| style="background-color:#EEF"|'''Codec Profile''' (''e.g.'' CBR)
|-
|samplerate
| style="background-color:#EEF"|'''Sample Rate''', in hertz (''e.g.'' 44100)
|-
|bitrate
| style="background-color:#EEF"|'''Bitrate''', in kilobits per second (''e.g.'' 320)
|-
|tool
| style="background-color:#EEF"|'''Tool''' used to produce the file, possibly guessed (''e.g.'' LAME3.97)
|-
|encoding
| style="background-color:#EEF"|'''Encoding''' lossiness (''e.g.'' lossy)
|-
|channels
| 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
| style="background-color:#EEF"|'''Bits Per Sample''' (''e.g.'' 16)
|-
|tagtype
| style="background-color:#EEF"|'''Tag Type''', comma-separated list of tag formats (''e.g.'' id3v2|apev2)
|-
|cue_embedded
| style="background-color:#EEF"|'''Embedded Cuesheet''' presence (''e.g.'' no <nowiki>[may be empty!]</nowiki>)
|-
|md5
| style="background-color:#EEF"|'''Audio MD5''' hash, if container defines it (''e.g.'' 1E24A910D91EF09A8CF403C9B6963961)
|-
| colspan="2" style="background-color:#CCF"|'''Other'''
|-
|ENC_DELAY
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_delay''' value (''e.g.'' 576)
|-
|ENC_PADDING
| style="background-color:#EEF"|LAME proprietary MP3 '''enc_padding''' value (''e.g.'' 1536)
|-
|MP3_ACCURATE_LENGTH
| style="background-color:#EEF"|'''mp3_accurate_length''' supported (LAME proprietary header)? (''e.g.'' yes)
|-
|MP3_STEREO_MODE
| style="background-color:#EEF"|Stereo mode used in MP3 file (''e.g.'' mono, stereo, joint stereo, etc.)
|-
|VERSION
| style="background-color:#EEF"|'''Version''' of tool (''e.g.'' 3.99)
|-
|FLAGS
| style="background-color:#EEF"|'''Flags''' of tool (''e.g.'' 22)
|}

=== $channels() ===
Returns number of channels in text format.

Example: ''$channels()'' → "stereo"

=== %replaygain_album_gain% ===

Returns ReplayGain album gain value.

=== %replaygain_album_peak% ===

Returns ReplayGain album peak value.

=== %replaygain_track_gain% ===

Returns ReplayGain track gain value.

=== %replaygain_track_peak% ===

Returns ReplayGain track peak value.

== Special fields ==

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

==== %last_modified% ====

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

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

= Time/Date Functions =

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

=== $year(time) ===

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

=== $month(time) ===

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

=== $day_of_month(time) ===

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 =

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.

For example:
{| border="0" cellspacing="0" cellpadding="2"
! code
! output
|-
|<pre>$put(foo,bar)$char(10)
$get(foo)$char(10)
$get(Foo)$char(10)
$puts(foo,2000)$char(10)
$get(foo)$char(10)</pre>
| style="background-color:#EEF" |<pre>bar
bar
bar

2000</pre>
|}
=== $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 nothing

= 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 ==

* [http://www.foobar2000.org/components/view/foo_playcount Playback statistics homepage]
* [[Foobar2000:Titleformat Playback Statistics|Playback statistics titleformat reference]]

= Component-specific fields and functions =

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

== Album list ==
* [[Foobar2000:Titleformat_Album_List|Album List Title Formatting]]
* [[Foobar2000:Preferences:Album List|Preferences: Album List]]
== Playlist Organizer ==
* [http://wiki.hydrogenaudio.org/index.php?title=Foobar2000:Components/Playlist_Organizer_(foo_plorg)#Nodes Playlist Organizer: Nodes Title Formatting]

== Columns UI ==

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

= Additional Reading =

* [[Foobar2000:Titleformat_Introduction|Introduction to titleformat scripts]]
* '''titleformat_help.html''' in your Foobar2000 directory (ie C:\Program Files\foobar2000\titleformat_help.html) file:///C:/Program%20Files/foobar2000/titleformat_help.html

[[Category:foobar2000 Guides|Titleformat Reference]]