MusicBee functions for virtual tags cheatsheet

[hiccup]

This is an effort to list all functions that are available for formulas in virtual tags. (and some other locations in MusicBee)

It has a brief explanation on most of them, some complemented with a short example formula.

The list is current for MusicBee v3.5
(3.5.8274 or newer is strongly recommended)

Functions that are marked with * are available if you have the Additional Tagging & Reporting Tools plugin installed.
(The AT&RT functions listed here are current for plugin version 5.7.8442. Always be sure to use a recent version of the plugin)
Just installing the plugin suffices, it's not necessary to configure anything.

Post #2 contains explanations and some examples for most of these functions.

______________________________________________________________________________________________

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)
Right	$Right(<field>,n)
RomanNumerals	$RomanNumerals(<field>)
RSplit	$RSplit(<field>,search-text,index)
RxSplit	$RxSplit(<field>,regex-pattern,index)
RxMatch	$RxMatch(<field>,regex-pattern)
SentenceCase *	$SentenceCase(string)
TitleCase *	$TitleCase(string)
Split	$Split(<field>,search-text,index)
TagContainsAnyString *	$TagContainsAnyString(<URL>,tag_name,string1|string2|etc.)
TagContainsAllStrings *	$TagContainsAllStrings(<URL>,tag_name,string1|string2|etc.)
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)

basic arithmetic functions

name	syntax
Add	$Add(number1,number2)
Sub	$Sub(number1,number2)
Mul	$Mul(number1,number2)
Div	$Div(number1,number2)

other arithmetic functions

name	syntax
Eq *  (equal to) Ne *  (not equal to) Gt *  (greater than) Lt *  (less than) Ge *  (greater than or equal to) Le *  (less than or equal to)	$eq(number1,number2) $ne(number1,number2) $gt(number1,number2) $lt(number1,number2) $ge(number1,number2) $le(number1,number2)
Abs   (absolute)	$Abs(number)
Mod   (modulus)	$Mod(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)
Sqrt *   (square root)	$Sqrt(number)

time and date

name	syntax
Date	$Date(<field>,format)
DateCreated *	$DateCreated(<URL>)
Now *	$Now()
NumberOfDays *	$NumberOfDays(datetime1,datetime2)
AddDuration *	$AddDuration(duration1,duration2)
AddDurationToDateTime *	$AddDurationToDateTime(datetime,duration)
SubDuration *	$SubDuration(duration1,duration2)
SubDurationFromDateTime *	$SubDurationFromDateTime(datetime,duration)
MulDuration *	$MulDuration(duration, number)
SubDateTime *	$SubDateTime(datetime1,datetime2)

other functions

name	syntax
ASR *	$ASR(<URL>,preset_id)
Char *	$Char(hexadecimal code)
Count	$Count(<grouping-field>) or $Count(<field>,<grouping-field>)
First	$First(<field>)
Group	$Group(<field>,n)
LR *	$LR(<URL>,function_id)
Min	$Min(<field>,<grouping-field>)
Max	$Max(<field>,<grouping-field>)
Name	$Name(filename)
Sort	$Sort(<field>)
Sum	$Sum(<field>,<grouping-field>)

______________________________________________________________________________________________

text formatting (markup)

{color: r, g, b} {color: default} {font: name; style; size} {font: default} {contrast: n} {contrast: default}

______________________________________________________________________________________________

[hiccup]

  explanations and examples
___

$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.
___

$AddDuration(duration1,duration2)

returns the sum of two durations.

Duration can be either defined as literal (eg. 00/00/0001 means 1 year, 5:00 means 5 mins, 00/01/0000 10:05:15 means 1 day 10 hours 5 mins 15 secs, etc.)
or it can be obtained by subtracting two dates or two times. (or two datetimes in general)
Also, <Time> tag (track duration) is a valid duration.
 ___

$AddDurationToDateTime(datetime,duration)

returns the sum of a datetime and a duration.

Datetime can be either defined as literal (eg. 07/25/2022 or 07/25/2022 8:31 pm or 8:31:15 pm)
or as any date tag in MB. (eg. <Year>, <Original Year>, <Date Added>, etc.)

Duration can be either defined as literal (eg. 00/00/0001 means 1 year, 5:00 means 5 mins, 00/01/0000 10:05:15 means 1 day 10 hours 5 mins 15 secs, etc.)
or it can be obtained by subtracting two dates or two times. (or two datetimes in general)
Also, <Time> tag (track duration) is a valid duration.
___

$ASR(<URL>,preset_id)

This function makes it possible to use and integrate ASR (Advanced Search & Replace) presets in virtual tags.
(ASR is a feature of the Additional Tagging & Reporting Tools plugin, which is required for these two functions)

More detailed information and some examples can be found in the README section here, and in e.g. this post by forum member Messiaen.

___

$Char(hexadecimal code)

returns the glyph (symbol) of the hexadecimal code entered

example:
$Char(266A) will return the symbol for a music eighth note:  ♪

___

$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)
___

$DateCreated(<URL>)

returns the file creation date/time.
___

$Div(<field1>,<field2>)

returns the division of two numeric fields.
___

$eq(number1,number2)
        compares 2 integer or fractional numbers, determines if number1 is equal to number2, e.g. $eq(1.0,1) returns "T"
$ne(number1,number2)
        determines if number1 is not equal to number2
$gt(number1,number2)
        determines if number1 is greater than number2
$lt(number1,number2)
        determines if number1 is less than number2
$ge(number1,number2)
        determines if number1 is greater than or equal to to number2
$le(number1,number2)
        determines if number1 is less than or equal to number2

___

$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.
___

$LR(<URL>,function_id)

This function makes it possible to use and integrate LR (Library Reports) presets in virtual tags.
(LR is a feature of the Additional Tagging & Reporting Tools plugin, which is required for these two functions)

More detailed information and some examples can be found in the README section here, and in e.g. this post by forum member Messiaen.
___

$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:
$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.
___

$MulDuration(duration,number)

returns the multiplication of a duration and a floating point or integer number.

example:
$MulDuration(<Time>,<Play Count>)

Where duration can be either defined as literal (eg. 00/00/0001 means 1 year, 5:00 means 5 mins, 00/01/0000 10:05:15 means 1 day 10 hours 5 mins 15 secs, etc.)
or it can be obtained by subtracting two dates or two times. (or two datetimes in general)
___

$Name(filename)

returns the file name without the extension and the path to the file.
e.g. $Name(<filename>) or $Name(<URL>)
___

$Not(<field1>=<field2>)

returns 'T' if two tags have different values or 'F' if they are identical.
___

$Now()

returns the current date/time.

date/time format depends on your Windows regional settings.
e.g.:
11/01/2022 02:30:00 pm  (for US regional settings)
01.11.2022 14:30:00  (for European regional settings)
___

$NumberOfDays(datetime1,datetime2)

returns the number of days between datetime1 and datetime2.
___

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

$Random(max_number)

outputs a random integer number between 0 and max_number (including them)
___

$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.')
___

$Round(number,number_of_digits_after_decimal_point)

returns a number rounded to a given number of digits.

examples:
$Round(4.28,1) returns 4.3
$Round(5.2,0) returns 5
___

$RoundDown(number,number_of_digits_after_decimal_point)

returns a number rounded down to a given number of digits.

example:
$RoundDown(4.28,1) returns 4.2
___

$RoundUp(number,number_of_digits_after_decimal_point)

returns a number rounded up to a given number of digits.

example:
$RoundUp(5.2,0) returns 6
___

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

$SentenceCase(string)

capitalises the first letter of the first word in a string.

example:
$SentenceCase(<Title>)
would display La chanson des vieux amants for the title La Chanson Des Vieux Amants
___

$TitleCase(string)

capitalises the first letter of every word in a string.

example:
$TitleCase(<Title>)
would display Refrain From Screaming for the title REFRAIN FROM SCREAMING
___

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

$Sqrt(number)

returns the square root of a numeric field.
May be useful for gathering some library statistics (in conjunction with ALR functions)
___

$Sub(<field1>,<field2>)

returns the subtraction of (difference between) two numeric fields.
___

$SubDateTime(datetime1,datetime2)

returns the subtraction of (difference between) two datetimes.

Datetime can be either defined as literal (eg. 07/25/2022 or 07/25/2022 8:31 pm or 8:31:15 pm)
or as any date tag in MB. (eg. <Year>, <Original Year>, <Date Added>, etc.)
___

$SubDuration(duration1,duration2)

returns the subtraction of (difference between) two durations.

Duration can be either defined as literal (eg. 00/00/0001 means 1 year, 5:00 means 5 mins, 00/01/0000 10:05:15 means 1 day 10 hours 5 mins 15 secs, etc.)
or it can be obtained by subtracting two dates or two times. (or two datetimes in general)
Also, <Time> tag (track duration) is a valid duration.
___
 
$SubDurationFromDateTime(datetime,duration)

returns the subtraction of a datetime and a duration.

Datetime can be either defined as literal (eg. 07/25/2022 or 07/25/2022 8:31 pm or 8:31:15 pm)
or as any date tag in MB. (eg. <Year>, <Original Year>, <Date Added>, etc.)

Duration can be either defined as literal (eg. 00/00/0001 means 1 year, 5:00 means 5 mins, 00/01/0000 10:05:15 means 1 day 10 hours 5 mins 15 secs, etc.)
or it can be obtained by subtracting two dates or two times. (or two datetimes in general)
Also, <Time> tag (track duration) is a valid duration.
___

$TagContainsAnyString(<URL>,tag_name,string1|string2|etc.)

checks if a tag contains any of the strings separated by |
Returns 'T' or 'F' (true or false)

$TagContainsAllStrings(<URL>,tag_name,string1|string2|etc.)

checks if a tag contains all the strings separated by |
Returns 'T' or 'F' (true or false)

Note that these functions require <URL> to be kept as is, and the name of the tag of your choice should not be surrounded by < >
___

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

_________________________________________

Text formating of virtual tags (markup)

It's possible to format the output of virtual tags to use specific fonts, colours or contrast. The available options are:

{color: r, g, b}
{color: default}

{font: name; style; size}
{font: default}

{contrast: n}
{contrast: default}

example:

Code

{font: Segoe UI Symbol;Regular;11}{color: 10,160,35} 🎵{font: Comic Sans MS;Italic;10}{color: default}<Title>{font: Segoe UI Symbol;Regular;10}{color: 237,122,7}{contrast: 60}    👤 {font: default}{color: default}{contrast: 80}<Artist>

will produce:


 

_________________________________________________________________________________________________________________________

some additional resources:

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 MusicBee Tips and Tricks forum topic containing a repository of all useful regex functions that can be used in virtual tags and/or AT&RT:
https://getmusicbee.com/forum/index.php?topic=38817.0
 
Another forum thread that can be a starting point to learn more about RegEx:
https://getmusicbee.com/forum/index.php?topic=20952.msg123713#msg123713

[sveakul]

Beautiful, thanks hiccup!

[hiccup]

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]

Updated with the functions that become available after you have installed Boroda's 'Additional Tagging & Reporting Tools' plugin.

[Corliss Rain]

This is awesome, hiccup! Thanks!

[hiccup]

The start post was updated with information on functions that were recently added to MB v3.5

[hiccup]

Updated to be current for the most recent version of the Additional Tagging & Reporting Tools plugin.

[hiccup]

updated

Thanks Boroda, for providing explanations on the duration and datetime functions.

[hiccup]

A request to anyone using formulas that make use of more advanced date/time functions such as: AddDuration, SubDateTime, SubDurationFromDateTime etc.

It would be appreciated if you could share such a formula, and explain what its practical use is.
I could then add it as an example for these functions.
(it would be good if the formula is as brief as possible)

[boroda]

@hiccup, please change description:

Code

$DateCreated(<URL>)

returns the file creation date.

to:

Code

$DateCreated("<URL>")

returns the file creation date/time.

quotes allow to take into account parenthesis in URL, and "time" is for more clarity, it'not only date.

also, i've added 2 new functions to plugin:

Code

$TagContainsAnyString("<URL>",tag_name,string1|string2|etc.): returns "T" if tag
  contains any of the strings separated by |, otherwise returns "F".
  tag_name must be written without angle brackets,
  e.g. $TagContainsAnyString("<URL>",Title,a|an|the)

$TagContainsAllStrings("<URL>",tag_name,string1|string2|etc.): returns "T" if tag
  contains all strings separated by |, otherwise returns "F".

[The Incredible Boom Boom]

A request to anyone using formulas that make use of more advanced date/time functions such as: AddDuration, SubDateTime, SubDurationFromDateTime etc.

It would be appreciated if you could share such a formula, and explain what its practical use is.
I could then add it as an example for these functions.
(it would be good if the formula is as brief as possible)

I could share my use case, but... uh... it's... uh... not brief. 😅

[boroda]

i think hiccup could create the link from 1st/2nd post to large description in later post.

[hiccup]

I could share my use case, but... uh... it's... uh... not brief. 😅

Could you perhaps isolate only the date/time part(s) of it, and explain what it does?
I don't think I should add formula examples that take some severe studying to understand what they do ;-)

Else, if you can't shorten it, but think it can be useful to others, feel free to share it.
I will then do what Boroda suggested.

[hiccup]

@hiccup, please change…

I will do that this weekend.
(editing these posts that are full of BBcode (for formatting) is no fun, and I'm not up to that at this moment. ;-)