Foobar2000:Titleformat Album List

Album list

Introduction

In foobar2000 0.8.3, the album list had the ability to have multiple entries for a single track. In the first 0.9 betas this feature was removed. With beta 11 it returns, although in a more powerful form and with a different syntax.

The major reason why the old version of the multiple-entries-per-track feature was removed was that it required that the formatting string be split at the pipe character "|" before evaluating it. In 0.9, the formatting string is evaluated first and split later, so the old solution no longer worked. Beta 11 offers a new solution that integrates better with the titleformatting syntax, and lifts some restrictions from the old solution.

Through a special field syntax or dedicated functions you can insert a list of all values of a field into the final string. This list will be decoded at the splitting stage. The list uses an encoding scheme similar to color codes. Like color codes (which don't work in album list, mind you) this limits the number of functions you can use on the output of these fields/functions without breaking the encoding, which would mess up the generated album list tree. Also see the section about safe functions below.

The exact encoding of the value list is an implementation detail and may change in future versions.

The new fields and functions are collectively called branching expressions. If you use multiple branching expressions in a single album list view, the number of entries produced by each will be multiplied. If, for example, you use "%<genre>%|%<artist>%" and a track has two genres and three artists, this track will get six entries, one for each genre-artist combination. (By the way, you would not have to put a "|" between %<genre>% and %<artist>%, you can use multiple branching expression on the same level of the album list hierarchy.)

Beware that gratuitous use of branching expressions can noticably prolong the time needed to generate the album list tree. There should be no significant performance loss, if you have mostly single-value tags.

Special fields

%<name>%

This generates a new tree branch for every non-empty value of the tag called name. If the tag does not exist, %<name>% evaluates to "?" (without the quotes). If at least one non-empty value exists, the boolean value of %<name>% is true, otherwise it is false.

This uses the normal remapping of metadata field names. It is not possible to access technical info or special fields with this syntax. (They don't have multiple values anyway.)

If only empty values exist, the track will be excluded from the generated album list tree.

Example:

 // genre is not remapped
 $if2(%<genre>%,Unknown genre)|
 // tracknumber is remapped, but no extra processing is applied (padding with zeroes)
 %<tracknumber>%|
 // artist is remapped and uses the values of the first actual tag, not all values of all tags artist can be remapped to
 %<artist>%

In the alternative syntax you can use field("<name>"), or see below for an alternative.

Functions

$meta_branch_remap(name)

This is identical to %<name>% except it does not produce a "?", if the tag does not exist.

$meta_branch(name)

Like $meta_branch_remap(name), but without the tag remapping.

Safe functions

This section gives details about which functions can be safely used on the result of a branching expression. The grouping is the same as on the Titleformat Reference page.

Control flow

All control flow functions are safe.

Arithetic functions

All arithmetic functions are useless, since the value of a branching expression is generally not an integer.

Boolean functions

Boolean functions can be used as normal, though traditional functions - especially $meta_test() may offer better performance than branching expressions. That is unless you specifically want to test for the "at least one non-empty value" condition.

Color functions

The color functions are useless in album list, as it does not support color codes.

String functions

String functions are more complicated, so this section is a bit lengthy.

As a rule of thumb, every function that replaces characters or sequences of characters should be safe, i.e. $lower(), $upper(), $caps(), $caps2(), and $ansi(). Even replace is safe, as long as you keep away from the range of non-printable ASCII characters; linefeed, carriage return, and tab are safe though.

Path manipulation functions like $directory(), $filename(), and $ext() are not safe.

Any string manipulation function that removes a part of a string or inserts a substring by position is generally unsafe. This includes $left(), $right(), $cut(), $pad(), etc.

$abbr() is not safe.

String comparison and measuring functions - with the exception of $strstr() - are generally useless. $strstr() can be used to test for the occurrence of a substring in the the returned value list, but you won't know in which value the occurrence is located.

Variable operations

The value of a branching expression can be stored in variables and retrieved without loss.