Foobar2000 Talk:Title Formatting Reference: Difference between revisions

From Hydrogenaudio Knowledgebase
(More... special fields (one of many))
(More)
Line 57: Line 57:
! %playlist_number%
! %playlist_number%
| Defined as ''$num(%_playlist_number%,$len(%_playlist_total%))''. Returns the position of the track as index into the playlist. The first track has index 1. The index is padded from the left with zeroes to the same number of digits as the last track.
| Defined as ''$num(%_playlist_number%,$len(%_playlist_total%))''. Returns the position of the track as index into the playlist. The first track has index 1. The index is padded from the left with zeroes to the same number of digits as the last track.
|}
{| border=1 cellspacing=0 cellpadding=2 style=""
! colspan="2" style="font-size:larger" | Control flow
|-
| colspan="2" | The functions in this section can be used to conditionally execute statements.
|-
! [...]
| Evaluates the expression between ''['' and '']''. If it has the truth value ''true'', its string value and the truth value ''true'' are returned. Otherwise an empty string and ''false'' are returned.
Example: ''[%artist%]'' returns the value of the artist tag, if it exists. Otherwise it returns nothing, when ''%artist%'' would return "?".
|-
! $if(cond,then)
| If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, ''false'' is returned.
|-
! $if(cond,then,else)
| If ''cond'' evaluates to ''true'', the ''then'' part is evaluated and its value returned. Otherwise, the ''else'' part is evaluated and its value returned.
|-
! $if2(a,else)
| Like ''$if(a,a,else)'' except that ''a'' is only evaluated once.
|-
! $if3(a1,a2,...,aN,else)
| Evaluates arguments ''a1'' ... ''aN'', until one is found that evaluates to ''true''. If that happens, its value is returned. Otherwise the ''else'' part is evaluated and its value returned.
|-
! $ifgreater(n1,n2,then,else)
| Compares the integer numbers ''n1'' and ''n2'', if ''n1'' is greater than ''n2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.
|-
! $iflonger(s1,s2,then,else)
| Compares the length of the strings ''s1'' and ''s2'', if ''s1'' is longer than ''s2'', the ''then'' part is evaluated and its value returned. Otherwise the ''else'' part is evaluated and its value returned.
|-
! $select(n,a1,...,aN)
| If the value of ''n'' is between 1 and N, ''an'' is evaluated and its value returned. Otherwise ''false'' is returned.
|}
== Arithmetic functions ==
The functions in this section can be used to perform arithmetic on integer numbers. A string will be automatically converted to a number and vice versa. The conversion to a number uses the longest prefix of the string, that can be interpreted as number. Leading whitespace is ignored.
Example: "c3po" -> 0, " -12" -> -12, but "- 12" -> 0
{| border=1 cellspacing=0 cellpadding=2
! $add(a,b)
| Adds ''a'' and ''b''.
Can be used with an arbitrary number of arguments. ''$add(a,b,...)'' is the same as ''$add($add(a,b),...)''.
|-
! $div(a,b)
| Divides ''a'' through ''b''. If ''b'' evaluates to zero, it returns ''a''.
Can be used with an arbitrary number of arguments. ''$div(a,b,...)'' is the same as ''$div($div(a,b),...)''.
|-
! $greater(a,b)
| Returns true, if ''a'' is greater than ''b'', otherwise false.
|-
! $max(a,b)
| Returns the maximum of ''a'' and ''b''.
Can be used with an arbitrary number of arguments. ''$max(a,b,...)'' is the same as ''$max($max(a,b),...)''.
|-
! $min(a,b)
| Returns the minimum of ''a'' and ''b''.
Can be used with an arbitrary number of arguments. ''$min(a,b,...)'' is the same as ''$min($min(a,b),...)''.
|-
! $mod(a,b)
| Computes the remainder of dividing ''a'' through ''b''. The result has the same sign as ''a''. If ''b'' evaluates to zero, the result is ''a''.
Can be used with an arbitrary number of arguments. ''$mod(a,b,...)'' is the same as ''$mod($mod(a,b),...)''.
|-
! $mul(a,b)
| Multiplies ''a'' and ''b''.
Can be used with an arbitrary number of arguments. ''$mul(a,b,...)'' is the same as ''$mul($mul(a,b),...)''.
|-
! $muldiv(a,b,c)
| Multiplies ''a'' and ''b'', then divides by ''c''. The result is rounded to the nearest integer.
|-
! $rand()
| Generates a random number in the range from 0 to 2<sup>32</sup>-1.
|-
! $sub(a,b)
| Subtracts ''b'' from ''a''.
Can be used with an arbitrary number of arguments. ''$sub(a,b,...)'' is the same as ''$sub($sub(a,b),...)''.
|}
== Boolean functions ==
The functions in this section can be used to work with truth values (''true'' and ''false''), which have no explicit representation in titleformat scripts. They do not return a string or number value. You can use them for more complex conditions with ''$if'' and related functions.
{| border=1 cellspacing=0 cellpadding=2
! $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''.
|}
|}

Revision as of 02:46, 15 May 2006

is there a way to change the field remappings? for instance, i want to make use of the MB-supplied ORIGYEAR field when possible for the %DATE% field.. --Herr klang 15:33, 12 Jun 2005 (CDT)

IMO, this page is too complicated and too long. Suggest a table formatted version. See titleformat_help.html in your foobar program directory. Perhaps this page should exist as an expanded version to be consistent? --Reglib 02:01, 3 May 2006 (CDT)


Metadata
%album artist% Defined as $if3($meta(album artist),$meta(artist),$meta(composer),$meta(performer)).
%album% Defined as $if3($meta(album),$meta(venue)).
%artist% Defined as $if3($meta(artist),$meta(album artist),$meta(composer),$meta(performer)).
%disc%

%discnumber%

Returns the disc number. The disc number is taken from the discnumber tag; if that does not exist, it is taken from the disc tag. If neither exist, the field is undefined.
%track artist% Defined as $meta(artist), if $meta(album artist) is different than $meta(artist), otherwise this field is empty.
%title% Defined as $if2($meta(title),%_filename%). Returns the title tag if available, otherwise it returns the filename excluding the extension.
%track%

%tracknumber%

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


Technical information
%bitrate% Defined as $if2($info(bitrate_dynamic),$info(bitrate)). Returns the current bitrate, if available, otherwise it returns the average bitrate. If neither is available, nothing is returned.
%channels% Defined as $channels(). Returns the number of channels in text form; returns "mono" and "stereo" instead of "1" and "2".
%filesize% Defined as %_filesize%. Returns the filesize in bytes.
%samplerate% Defined as $info(samplerate). Returns the samplerate in Hz.
%codec% Defined as $codec().


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


Control flow
The functions in this section can be used to conditionally execute statements.
[...] Evaluates the expression between [ and ]. If it has the truth value true, its string value and the truth value true are returned. Otherwise an empty string and false are returned.

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

$if(cond,then) If cond evaluates to true, the then part is evaluated and its value returned. Otherwise, false is returned.
$if(cond,then,else) If cond evaluates to true, the then part is evaluated and its value returned. Otherwise, the else part is evaluated and its value returned.
$if2(a,else) Like $if(a,a,else) except that a is only evaluated once.
$if3(a1,a2,...,aN,else) Evaluates arguments a1 ... aN, until one is found that evaluates to true. If that happens, its value is returned. Otherwise the else part is evaluated and its value returned.
$ifgreater(n1,n2,then,else) Compares the integer numbers n1 and n2, if n1 is greater than n2, the then part is evaluated and its value returned. Otherwise the else part is evaluated and its value returned.
$iflonger(s1,s2,then,else) Compares the length of the strings s1 and s2, if s1 is longer than s2, the then part is evaluated and its value returned. Otherwise the else part is evaluated and its value returned.
$select(n,a1,...,aN) If the value of n is between 1 and N, an is evaluated and its value returned. Otherwise false is returned.


Arithmetic functions

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

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

$add(a,b) Adds a and b.

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

$div(a,b) Divides a through b. If b evaluates to zero, it returns a.

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

$greater(a,b) Returns true, if a is greater than b, otherwise false.
$max(a,b) Returns the maximum of a and b.

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

$min(a,b) Returns the minimum of a and b.

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

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

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

$mul(a,b) Multiplies a and b.

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

$muldiv(a,b,c) Multiplies a and b, then divides by c. The result is rounded to the nearest integer.
$rand() Generates a random number in the range from 0 to 232-1.
$sub(a,b) Subtracts b from a.

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


Boolean functions

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

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

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

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

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

$not(x) Logical Not. Returns false, if x is true, otherwise it returns true.
$xor(...) Logical Exclusive-or of an arbitrary number of arguments. Returns true, if an odd number of arguments evaluate to true.

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