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: ♪
___
$CharN(hexadecimal code,decimal number of times)
returns a Unicode character (defined by its hexadecimal code) repeated a specified number of times
example:
$If(<Release type>="studio album",$CharN(200b,4)"Albums (studio)",$If(<Release type>="live album",$CharN(200b,3)"Albums (live)",$If(<Release type>="compilation album",$CharN(200b,2)"Albums (compilation)",)))
adds a specific number of zero-width spaces in front of specific album types
this is useful for creating a custom and non-alphabetical sorting order
___
$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.
___
$Lg(number)
returns the logarithm of a number (base 10)
example:
$Mul($Lg(<Track peak>),20) dB *
(returns the peak audio value of a track in dB)
* <Track peak> is not available by default in MusicBee
See here for how to make it available.
___
$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 is 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:{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/FunctionsA 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.0A 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
