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

hiccup

  • Hero Member
  • *****
  • Posts: 6343
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 suggested)

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.4.8303. 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
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
Count$Count(<grouping-field>) or $Count(<field>,<grouping-field>)
First$First(<field>)
Group$Group(<field>,n)
Min$Min(<field>,<grouping-field>)
Max$Max(<field>,<grouping-field>)
Name$Name(filename)
Sort$Sort(<field>)
Sum$Sum(<field>,<grouping-field>)

___________________________________________________________________________
Last Edit: November 27, 2022, 09:00:23 PM by hiccup

hiccup

  • Hero Member
  • *****
  • Posts: 6343
  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.

___

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

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

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


_________________________________________________________________________________________________________________________


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 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: August 27, 2022, 04:00:59 PM by hiccup


hiccup

  • Hero Member
  • *****
  • Posts: 6343
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: 6343
Updated with the functions that become available after you have installed Boroda's 'Additional Tagging & Reporting Tools' plugin.


hiccup

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


hiccup

  • Hero Member
  • *****
  • Posts: 6343
Updated to be current for the most recent version of the Additional Tagging & Reporting Tools plugin.

hiccup

  • Hero Member
  • *****
  • Posts: 6343
updated

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

hiccup

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

  • Hero Member
  • *****
  • Posts: 3816
@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

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

  • Hero Member
  • *****
  • Posts: 3816
i think hiccup could create the link from 1st/2nd post to large description in later post.

hiccup

  • Hero Member
  • *****
  • Posts: 6343
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.