This is an effort to list all available functions that can be used in virtual formulas.
It has a brief explanation on each, some complemented with a short example formula.
Additionally:At the bottom of this post is another section that lists functions that become available after installing Boroda's Additional Tagging & Reporting Tools plugin.
string functions name
| syntax
|
Contains | $Contains(<field>,search-value) |
CutLeft * | $CutLeft(string,count) |
CutRight * | $CutRight(string,count) |
IsMatch | $IsMatch(<field>,regex-pattern) |
IsNull | $IsNull(<field>,text,<field>) |
Left | $Left(<field>,n) |
Len | $Len(<field>) |
Lower | $Lower(<field>) |
Pad | $Pad(<field>,n) |
RemoveSortWords | $RemoveSortWords(<field>) |
Replace | $Replace(<field>,search-text,replace-text) |
RxReplace | $RxReplace(<field>,regex-pattern,replace-text) |
RxMatch | $RxMatch(<field>,regex-pattern) |
Right | $Right(<field>,n) |
RomanNumerals | $RomanNumerals(<field>) |
RSplit | $RSplit(<field>,search-text,index) |
RxSplit | $RxSplit(<field>,regex-pattern,index) |
Split | $Split(<field>,search-text,index) |
Trim | $Trim(<field>) |
Upper | $Upper(<field>) |
boolean operations name
| syntax
|
If | $If(<field1>=<field2>,true-value,false-value) |
And / Or | $If($And($Contains(<field>,search-text)=T,$Contains(<field>,search-text)=T),value1,value2) |
And / Or | $If($Or($Contains(<field>,search-text)=T,$Contains(<field>,search-text)=T),value1,value2) |
Not * | $Not(<field1>=<field2>,true-value,false-value) |
arithmetic functions name
| syntax
|
Add * | $Add(number1,number2) |
Sub * | $Sub(number1,number2) |
Mul * | $Mul(number1,number2) |
Div * | $Div(number1,number2) |
Abs (absolute) * | $Abs(number) |
Mod (modulus) * | $Mod(number1,number2) |
other functions name
| syntax
|
Count | $Count(<grouping-field>) or $Count(<field>,<grouping-field>) |
Date | $Date(<field>,format) |
First | $First(<field>) |
Group | $Group(<field>,n) |
Max | $Max(<field>,<grouping-field>) |
Min | $Min(<field>,<grouping-field>) |
Sort | $Sort(<field>) |
Sum | $Sum(<field>,<grouping-field>) |
* available for MusicBee v3.5 and upTheir workings:___
$Abs(<field>)
returns the absolute of a number.
(which is the distance of that number to zero. E.g. -3 gets output as 3)
___
$Add(<field1>,<field2>)
returns the sum of two numeric fields.
___
$Contains(<field>,search-value)
checks if a tag contains a given value, which can be a text string or a tag.
Returns 'T' or 'F' (true or false)
example:$Contains(<Genre>,rock)
will e.g. produce 'T' when the genre is 'Jazz-rock'By combining this function with the
$If function you can use it to output a custom text. (or the contents of another tag)
example:$If($Contains(<field>,search-value)="T",value1,value2)
(where value1 is produced when 'true' and value2 when 'false')___
$Count(<grouping-field>)
and
$Count(<field>,<grouping-field>)
returns the number of items in a defined group.
examples:$Count(<Album>)
returns the number of tracks of an album$Count(<Artist>)
returns the number of tracks of an artist$Count(<Album>, <Album Artist>)
returns the number of albums of an album artist___
$CutLeft(<field>,length)
returns a field with
n characters removed from the left.
$CutRight(<field>,length)
returns a field with
n characters removed from the right.
___
$Date(<field>,format)
returns a date field using a defined formatting, using an existing date tag as the source.
examples:$Date(<Date Modified>,yyyy/MM/dd HH:mm)
(will e.g. output: 2021/12/31 19:30)$Date(<Date Modified>,MMMM yyyy)
(will e.g. output: december 2021)Relevant formatting options:
date: d / dd / ddd / dddd
month: M / MM / MMM / MMMM
year: yy / yyyy
hour: H / HH
minute: m / mm
(the letter count defines displaying 1 or 2 digits, abbreviated, full)___
$Div(<field1>,<field2>)
returns the division of two numeric fields.
___
$First(<field>)
returns only the first value of a multi-value tag.
___
$Group(<field>,n)
returns an alphabetical grouping string.
The number for 'n' defines the amount of alphabetical characters the alphabet will be divided in.
examples:For the artist 'Deafheaven':$Group(<Artist>,3)
the output will be: DEF$Group(<Artist>,4)
the output will be: ABCD___
$If(<field1>=<field2>,true-value,false-value)
returns one of two values depending on a comparison of two different tags.
For numerical tags, besides
= (equals), also
< (less than) and
> (greater than) can be used.
$And(Criterion1,Criterion2)
$Or(Criterion1,Criterion2)
are both subfunctions that can be used in combination with the $If function.
They make it possible to have two (or more) criteria being met before returning a true or false result.
for 'And', both criteria must be met to output 'T'
for 'Or', at least one criterium must be met to output 'T'
example: $If($Or($Contains(<Album>,live)=T,$Contains(<Title>,live)=T),Live,Studio)
(checks if any of two different tags contains the word 'live')tip:
As an alternative to using $Or, you can also line up two (or more) tags in $Contains.
example:$If($Contains(<Album><Title><Keywords><Genre>,live)=T,Live,Studio)
(will check if any of these four tags contains 'live', and if so will output 'Live'.)___
$IsMatch(<field>,regex-pattern)
checks if a tag matches a regular expression.
Returns 'T' if true or 'F' if false.
example:$IsMatch(<Artist>,"^The\s")
(will output 'T' if the Artist tag begins with 'The')___
$IsNull(<field>,value if empty,<field>)
checks if a tag is empty, and then outputs either that- or another tag, or a value that can be either a text string or a tag.
This can also be useful to prevent MusicBee from displaying 'Unknown' for tags used in a formula that are empty.example:$IsNull(<Album>,"",<Album>)
(will display blank instead of 'Unknown' for tracks without an Album tag)___
$Left(<field>,n)
$Right(<field>,n)
'Left' returns the first 'n' count characters of a tag.
'Right' returns the last 'n' count characters of a tag.
___
$Len(<field>)
returns the amount of characters (length) of a tag.
___
$Lower(<field>)
$Upper(<field>)
converts a tag to all lower-case or all upper-case.
___
$Min(<field>,<grouping-field>)
checks for the item in a group that has the lowest value and outputs that value.
$Max(<field>,<grouping-field>)
checks for the item in a group that has the highest value and outputs that value.
examples:$Max(<Play Count>,<Album>)
(returns the highest play count that is found for any track(s) of an album)$Min(<Year (yyyy)>,<Artist>)
(returns the earliest year that is found for any track(s) of an artist)___
$Mod(<field1>,<field2)
returns the modulo of the division of two numeric tags.
___
$Mul(<field1>,<field2>)
returns the multiplication of two numeric fields.
___
$Not(<field1>=<field2>)
returns 'T' if two tags have different values or 'F' if they are identical.
___
$Pad(<field>,n)
pads numerical tags to 'n' digits by adding zeros at the beginning.
example:Pad(<Track#>,3)
(will e.g. output '001' for track '1')___
$RemoveSortWords(<field>)
outputs the content of a tag while removing the 'ignore words' as defined at: Preferences > Sorting/Grouping.
So e.g. 'The Beatles' can be output as 'Beatles'.
___
$Replace(<field>,search-value,replace-value)
searches a tag for a defined search value, and replaces that value with a defined replace value.
$RxReplace(<field>,regex-pattern,replace-text)
does the same, but allows for using regular expressions.
example:$RxReplace(<Title>,"feat[\W\.]",ft.)
(replaces 'feat.' in a title with 'ft.')___
$RxMatch(<field>,regex-pattern)
returns the text portion that is matched by a regular expression.
example:$RxMatch(<Year>,"\d{4}")
(returns the year only, so it will e.g. produce '2021' for both '2021-12-31' and '31/12/2021')___
$RomanNumerals(<field>)
outputs a numerical field formatted as Roman numerals.
example:$RomanNumerals(<Movement #>)
(will e.g. display 'III' for '3')___
$Split(<field>,search-text,index)
returns a defined index section of a tag.
The search-text defines the index divider, the index is a number that counts the sections from left to right.
example:$Split(<Title>,:,3)
(will return 'Three' for a title being: 'One: Two: Three: Four')$RSplit(<field>,search-text,index)
does the same as $Split, but counts from right to left.
$RxSplit(<field>,regex-pattern,index)
does the same as $Split, but allows for using a regular expression to define the split value.
___
$Sort(<field>)
returns a tag in the format of a sorting field, moving 'Ignore words' (as defined at: Preferences > Sorting/Grouping) to the end of the tag.
example:$Sort(<Artist>)
(will output 'Beatles, The' for 'The Beatles')___
$Sub(<field1>,<field2>)
returns the subtraction of two numeric fields.
___
$Sum(<field>,<grouping-field>)
returns the total count of an item in reference to a group.
examples:$Sum(<Play Count>,<Artist>)
(returns the total play count for all tracks of an artist)$Sum(<Play Count>,<Album>)
(returns the combined play count for all the tracks of an album)___
$Trim(<field>)
removes any spaces from the beginning and the end of a tag.
_____________________________________________________________________________________________________________________________________________________________________
These functions become available for use in virtual tags after installing Boroda's Additional Tagging & Reporting Tools plugin:More information on this fantastic plugin can be found here:
https://getmusicbee.com/addons/plugins/49/additional-tagging-amp-reporting-tools/basic arithmetic name
| syntax
|
Add * | $Add(number1,number2) |
Sub * | $Sub(number1,number2) |
Mul * | $Mul(number1,number2) |
Div * | $Div(number1,number2) |
Random | $Random(max_number) |
Round | $Round(number,number_of_digits_after_decimal_point) |
RoundDown | $RoundDown(number,number_of_digits_after_decimal_point) |
RoundUp | $RoundUp(number,number_of_digits_after_decimal_point) |
other arithmetic name
| syntax
|
Abs (absolute) * | $Abs(number) |
Lg (decimal logarithm) | $Lg(number) |
Ln (natural logarithm) | $Ln(number) |
Log (logarithm) | $Log(number,base) |
Mod (modulus) * | $Mod(number1,number2) |
Sqrt (square root) | $Sqrt(number) |
boolean operations name
| syntax
|
Not * | $Not(parameter) |
Xor | $Xor(parameter1,parameter2) |
string functions name
| syntax
|
Len | $Len(string): length of string |
CutLeft * | $CutLeft(string,count) |
CutRight * | $CutRight(string,count) |
Name | $Name(filename) |
SentenceCase | $SentenceCase(string) |
TitleCase | $TitleCase(string) |
time and date name
| syntax
|
AddDuration | $AddDuration(duration1,duration2) |
AddDurationToDateTime | $AddDurationToDateTime(datetime,duration) |
Now | $Now() |
NumberOfDays | $NumberOfDays(datetime1,datetime2) |
SubDateTime | $SubDateTime(datetime1,datetime2) |
SubDuration | $SubDuration(duration1,duration2) |
SubDurationFromDateTime | $SubDurationFromDateTime(datetime,duration) |
* these functions are now available by default in MusicBee v3.5 and up