Author Topic: MusicBee functions for virtual tags cheatsheet  (Read 4574 times)

hiccup

  • Hero Member
  • *****
  • Posts: 5959
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 up


Their 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
Last Edit: June 12, 2022, 09:08:42 AM by hiccup

hiccup

  • Hero Member
  • *****
  • Posts: 5959
The above start post is a cheat sheet for MusicBee's functions for virtual tags that I have been keeping locally on my pc.
It helps me to keep my memory fresh on these functions, and allows for quick referencing and easy copying of a working syntax into a formula that I am working on, without the need to go and search online when I am not sure of something.

All functions are briefly explained, and where useful they are accompanied with a short working example.

I thought to share this so other users can either use it as a reference or copy it and store it on their pc also.

___

Some additional links that may be helpful on the matter:

A MusicBee Wiki page that contains similar content, on which my sheet was loosely based:
https://musicbee.fandom.com/wiki/Functions

A MusicBee forum topic containing a repository of virtual tags that may be helpful to gain more understanding of what can be done:
https://getmusicbee.com/forum/index.php?topic=9317.0

A forum thread that can be a starting point to learn more about RegEx:
https://getmusicbee.com/forum/index.php?topic=20952.msg123713#msg123713
 
Last Edit: April 25, 2022, 11:32:04 PM by hiccup


hiccup

  • Hero Member
  • *****
  • Posts: 5959
You're welcome sveakul!

I believe the very first version I posted had a problem with some double quotes.
(curly instead of straight)
On my system copying such a formula into MusicBee produced an error.
That should be fixed now.

hiccup

  • Hero Member
  • *****
  • Posts: 5959
Updated with the functions that become available after you have installed Boroda's 'Additional Tagging & Reporting Tools' plugin.


hiccup

  • Hero Member
  • *****
  • Posts: 5959
The start post was updated with information on functions that were recently added to MB v3.5