Post by GoneMAD on Mar 11, 2020 19:20:44 GMT -5
This is a working post and will be updated as more things are added. Eventually it will be replaced by some actual documentation. Feel free to ask questions or post custom metadata lines you create for others to use.
Edit: Updated 2021/07/29 - Added addition views for composer variable
Help page for Displayed Metadata View
Attached is a sample json file that can be used as a template: metadata_import.json (449 B)
Edit: I also attached a zip containing all the presets defined in GMMP custom_metadata_presets.zip (12.23 KB)
The json can be loaded in the metadata select UI using the import button on the toolbar. It will import to the "custom" metadata list. If nothing imports that means the json file is invalid.
Contents:
The basic format is as follows. markupLines is a list of metadata lines. Each line is a list of "metadata splits". Most lines will have a single split, but a line can contain up to 3 splits. In the example above, the last line has 2 splits separated by commas. If you would line a single line with multiple alignments, splits must be used (one alignment per split)
Splits can be assigned weights so they only take up a percentage of the width (default is 50/50 for 2 splits and 33/33/33 for 3 splits). The following example will use 75% of the width for the left split and 25% for the right split
Blank lines can be used to space lines out.
Variables:
A variable is surrounded by %% and will be replaced with metadata from the playing song. Not every variable is available to each views. Supported views are listed in parenthesis after each variable
Available variables:
If any of these do not work please let me know. Note: Now Playing variables are also available for widgets
Formatting:
A formatted region of a line is started with <keyword=value> (or simply <keyword>) and ends with </> Note: using the end marker is optional
Formatting keywords:
Functions:
Functions allow you to place logic / conditions / formatting into the metadata lines. Functions start with $
Functions were mostly implemented the exact same way foobar2000 did, so this documentation is almost straight from wiki.hydrogenaud.io/index.php?title=Foobar2000:Title_Formatting_Reference#.24if.28cond.2Cthen.29
Examples:
Available functions:
Edit: I have not tested every possible combinations so if there are issues let me know.
Edit: Updated 2021/07/29 - Added addition views for composer variable
Help page for Displayed Metadata View
Attached is a sample json file that can be used as a template: metadata_import.json (449 B)
Edit: I also attached a zip containing all the presets defined in GMMP custom_metadata_presets.zip (12.23 KB)
The json can be loaded in the metadata select UI using the import button on the toolbar. It will import to the "custom" metadata list. If nothing imports that means the json file is invalid.
Contents:
[
{
"markupLines" :
[
["<align=center><typeface=sans-serif><size=24>%tn%. %tr%"],
["<size=20><blank>"],
["<align=center><typeface=sans-serif><size=20>%ar%"],
["<align=center><typeface=sans-serif><size=20>%al%"],
["<size=20><blank>"],
["<align=center><typeface=sans-serif><size=16>%ge%", "<align=center><typeface=sans-serif><size=16>%yr%"],
["<align=center><typeface=sans-serif><size=16>%br%kbps", "<align=center><typeface=sans-serif><size=16>%sr%hz"]
]
}
]
The basic format is as follows. markupLines is a list of metadata lines. Each line is a list of "metadata splits". Most lines will have a single split, but a line can contain up to 3 splits. In the example above, the last line has 2 splits separated by commas. If you would line a single line with multiple alignments, splits must be used (one alignment per split)
["<align=center><typeface=sans-serif><size=16>%br%kbps", "<align=center><typeface=sans-serif><size=16>%sr%hz"]
Splits can be assigned weights so they only take up a percentage of the width (default is 50/50 for 2 splits and 33/33/33 for 3 splits). The following example will use 75% of the width for the left split and 25% for the right split
["<weight=0.75><align=left><typeface=sans-serif><size=30>%ps%) %tr%", "<weight=0.25><align=right><typeface=sans-serif><size=30>%du%"]
Blank lines can be used to space lines out.
["<size=20><blank>"]
Variables:
A variable is surrounded by %% and will be replaced with metadata from the playing song. Not every variable is available to each views. Supported views are listed in parenthesis after each variable
Available variables:
ALBUM_ARTIST = %aa% - (Now Playing, Album, Album Artist, Queue, Song/Album Details, Bookmark, Playlist, AudioFile)
ALBUM = %al% - (Now Playing, Album, Queue, Song/Album Details, Bookmark, Playlist, AudioFile)
ALBUM YEAR = %ayr% - (Now Playing, Album, Queue, Song/Album Details, Bookmark, Playlist, AudioFile)
ARTIST = %ar% - (Now Playing, Artist, Queue, Song/Album Details, Bookmark, Playlist, AudioFile)
BITRATE = %br% - (Now Playing, Playlist, AudioFile)
CHANNELS = %ch% - (Now Playing, Playlist, AudioFile)
COMMENT = %co% - (Now Playing, Playlist, AudioFile)
COMPOSER = %cp% - (Now Playing, Composer, Queue, Song/Album Details, Bookmark, Playlist, AudioFile)
DISCNO = %dn% - (Now Playing, Queue, Song/Album Details, Bookmark, Playlist, AudioFile)
DURATION = %du% - (Now Playing) (will be in Queue, Song/Album Details, Bookmark, Playlist, AudioFile)
FILE EXTENSION = %ext% - (Now Playing, Queue, Song/Album Details, Bookmark, Playlist, AudioFile, File)
FOLDER = %fo% - (Now Playing, Queue, Song/Album Details, Bookmark, Playlist, AudioFile, File)
FILENAME = %fn% - (Now Playing, Queue, Song/Album Details, Bookmark, Playlist, AudioFile, File, Folder)
FILESIZE (in bytes) = %fs% - (Now Playing, Playlist, File)
FULLPATH = %fp% - (Now Playing, Queue, Song/Album Details, Bookmark, Playlist, AudioFile, File, Folder)
GENRE = %ge% - (Now Playing, Genre, Queue, Song/Album Details, Bookmark, Playlist, AudioFile)
LAST PLAYED = %lp% (Now Playing, Queue, Song/Album Details, Bookmark)
PLAYCOUNT = %pc% - (Now Playing, Queue, Song/Album Details, Bookmark)
QUEUE / PLAYLIST POSITION = "%ps%" - (Now Playing, Queue, Playlist, AudioFile)
RATING = %ra% - (Now Playing, Queue, Song/Album Details, Bookmark, Playlist, AudioFile)
SAMPLE_RATE = %sr% - (Now Playing, Playlist, AudioFile)
SKIPCOUNT = %skp% - (Now Playing, Queue, Song/Album Details, Bookmark)
TRACK_NUM = %tn% - (Now Playing, Queue, Song/Album Details, Bookmark, Playlist, AudioFile)
TRACKNAME = %tr% - (Now Playing, Queue, Song/Album Details, Bookmark, Playlist, AudioFile)
TOTAL_TRACKS/QUEUE SIZE = "%tt%" (Now Playing)
YEAR = %yr% (Now Playing, Queue, Song/Album Details, Year, Bookmark, Playlist, AudioFile)
NEXT_TRACK_ALBUM = %nal% (Now Playing)
NEXT_TRACK_ALBUM_YEAR = %nayr% (Now Playing)
NEXT_TRACK_ALBUM_ARTIST = %naa% (Now Playing)
NEXT_TRACK_ARTIST = %nar% (Now Playing)
NEXT_TRACK_DISCNO = %ndn% (Now Playing)
NEXT_TRACK_DURATION = %ndu% (Now Playing)
NEXT_TRACK_GENRE = %nge% (Now Playing)
NEXT_TRACK_PLAYCOUNT = %npc% (Now Playing)
NEXT_TRACK_RATING = %nra% (Now Playing)
NEXT_TRACK_SKIPCOUNT = %nskp% (Now Playing)
NEXT_TRACK = %nt% (Now Playing)
NEXT_TRACK_NUM = %ntn% (Now Playing)
NEXT_TRACK_YEAR = %nyr% (Now Playing)
NEXT_TRACK_FILENAME = %nfn% (Now Playing)
NEXT_TRACK_FOLDER = %nfo% (Now Playing)
NEXT_TRACK_FULL_PATH = %nfp% (Now Playing)
NEXT_TRACK_EXT = %next% (Now Playing)
If any of these do not work please let me know. Note: Now Playing variables are also available for widgets
Formatting:
A formatted region of a line is started with <keyword=value> (or simply <keyword>) and ends with </> Note: using the end marker is optional
Formatting keywords:
<align=value> - Adjusts the alignment of the line / split. Valid values: left, center, right
<size=value> - Sets the font size. Suggested value range: 12-34
<typeface=value> - Sets the font typeface. Valid values: sans-serif, sans-serif-light, sans-serif-condensed, sans-serif-black, sans-serif-thin, sans-serif-medium, serif-monospace, monospace, serif
<color=value> - Text color based on theme. Defaults primary text color. Valid values: secondary (secondary text color), primary (theme primary color), primaryDark (theme primaryDark color), accent (theme accent color), white, also accepts a hexcode as long as it begins with a #
<blank> - Creates a blank line
<u> - Underline
<b> - Bold
<i> - Italic
<wrap> - Will wrap the line to the next line if the text extends past the end of the line
Functions:
Functions allow you to place logic / conditions / formatting into the metadata lines. Functions start with $
Functions were mostly implemented the exact same way foobar2000 did, so this documentation is almost straight from wiki.hydrogenaud.io/index.php?title=Foobar2000:Title_Formatting_Reference#.24if.28cond.2Cthen.29
Examples:
["<align=left><typeface=sans-serif><size=16>$upper(%ext%), %sr%hz, %br%kbps, %ch%, %du%"]
- This will make the file extension text all uppercase
["<align=center><typeface=sans-serif><size=20><b>$notempty(%cp%, %ar%)</b> - <i>%al%</i>"]
- Will show "Composer - Album" if there is a composer field, otherwise show "Artist - Album"
["$ifgreater(%dn%, 1, Disc: %dn% TrackNo: %tn%, TrackNo: %tn%)]
- If disc number is greater than 1: "Disc: 3 TrackNo: 7" if less than or equal to 1: "TrackNo: 7"
Available functions:
Control Flow Functions:
$if(cond,then)
If cond evaluates to true, the then part is evaluated and its value returned. Otherwise, false is returned.
Plain strings are FALSE. Field lookups and functions can introduce a boolean value of TRUE. Examples:
False: $if(0,True,False) False: $if('0',True,False) True or False: [$add(%rating%,1)]
The last one would display the value of %rating% plus one, if and only if %rating% is set for the track.
$if(cond,then,else)
If cond evaluates to true, the then part is evaluated and its value returned. Otherwise, the else part is evaluated and its value returned.
$if2(expr,else)
Like $if(expr,expr,else) except that expr is only evaluated once. In other words, if expression expr is true, expr is returned, otherwise the else part is evaluated and expr is returned as true.
$if3(a1,a2,...,aN,else)
Evaluates arguments a1 ... aN, until one is found that evaluates to true. If that happens, its value is returned. Otherwise the else part is evaluated and its value returned.
$ifequal(int1,int2,then,else)
Compares the integer numbers int1 and int2, if int1 is equal to int2, the then part is evaluated and its value returned. Otherwise the else part is evaluated and its value returned.
$ifgreater(int1,int2,then,else)
Compares the integer numbers int1 and int2, if int1 is greater than int2, the then part is evaluated and its value returned. Otherwise the else part is evaluated and its value returned.
$iflonger(str,n,then,else)
Compares the length of the string str to the number n, if str is longer than n characters, the then part is evaluated and its value returned. Otherwise the else part is evaluated and its value returned.
$select(n,a1,...,aN)
If the value of n is between 1 and N, an is evaluated and its value returned. Otherwise false is returned.
$notempty(val1, val2, val3, etc)
Will display the first parameter that is not empty.
String Functions:
$caps(str)
Converts first letter in every word of string str to uppercase, and all other letters to lowercase.
$caps2(str)
Converts first letter in every word of string str to uppercase, and leaves all other letters as they are.
$cut(str,len)
Returns first len characters from the left of the string str. This function is the same as $left(a,len). Negative numbers produce the entire string. Examples:
$cut('abc123',3) → abc
$cut('abc123',0) → (nothing)
$cut('abc123',-1) → abc123
$insert(str,insert,n)
Inserts insert into str after n characters.
$len(str)
Returns length of string str in characters.
$longer(str1,str2)
Returns true, if string str1 is longer than string str2, false otherwise.
$lower(str)
Converts string str to lowercase.
$longest(arg,...)
Returns the longest of its arguments. Can be used with an arbitrary number of strings.
$num(nbr,len)
Formats the integer number nbr in decimal notation with len characters. Pads with zeros from the left if necessary. len includes the dash when the number is negative. If nbr is not numeric, it is treated as zero. Examples:
$num(123,5) → 00123
$num(-123,5) → -0123
$num(4.8,5) → 00004
$num(A1,5) → 00000
$pad(str,len)
Creates a left-aligned version of the string str. If x is shorter than len characters, the function adds spaces to the right of str to make the result len characters long. Otherwise the function returns str unchanged.
$pad_right(str,len)
Creates a right-aligned version of the string str. If str is shorter than len characters, the function adds spaces to the left of str to make the result len characters long. Otherwise the function returns str unchanged.
$pad(str,len,char)
Creates a left-aligned version of the string str. If str is shorter than len characters, the function adds char to the right of str to make the result len characters long. Otherwise the function returns str unchanged.
$pad_right(str,len,char)
Creates a right-aligned version of the string str. If str is shorter than len characters, the function adds char to the left of str to make the result len characters long. Otherwise the function returns str unchanged.
$padcut(str,len)
Returns first len characters from the left of str, if str is longer than len characters. Otherwise adds spaces to the right of str to make the result len characters long.
$padcut(str,len,char)
Returns first len characters from the left of str, if str is longer than len characters. Otherwise adds char to the right of str to make the result len characters long.
$padcut_right(str,len)
Returns first len characters from the left of str, if str is longer than len characters. Otherwise adds spaces to the left of str to make the result len characters long.
$padcut_right(str,len,char)
Returns first len characters from the left of str, if str is longer than len characters. Otherwise adds char to the left of str to make the result len characters long.
$repeat(expr,count)
Returns count copies of expr. Note that expr is evaluated once before its value is used, so $repeat cannot be used for loops.
$replace(str,search,replace)
Replaces all occurrences of string search in string str with string replace.
Example to replace multiple artists separated by comma with something else:
$replace(%ar%,%comma%,;%space%) Changes Artist1,Artist2,Artist3 to Artist1; Artist2; Artist3
$replace(%ar%,%comma%,%comma%%space%) Changes Artist1,Artist2,Artist3 to Artist1, Artist2, Artist3
Can also be used with an arbitrary number of arguments. Note that $replace(str,search1,replace1,search2,replace2) is generally not the same as $replace($replace(str,search1,replace1),search2,replace2).
Example: $replace(ab,a,b,b,c) → "bc", $replace($replace(ab,a,b),b,c) → "cc"
$right(str,len)
Returns the first len characters from the right of string str.
$shortest(str,...strN)
Returns the first shortest element of its arguments. Can be used with an arbitrary number of strings.
$strchr(str,char)
Returns position of first occurrence of character char in string str or -1 if not found
Example: $strchr(abca,a) → 1
$strrchr(str,char)
Returns positions of last occurrence of character char in string str or -1 if not found
Example: $strrchr(abca,a) → 4
$strstr(str1,str2)
Returns position of first occurrence of string str2 in string str1 or -1 if not found. Function is case-sensitive.
$strcmp(str1,str2)
Performs a case-sensitive comparison of the strings str1 and str2. 0 is returned if equal
$stricmp(str1,str2)
Performs a case-insensitive comparison of the strings str1 and str2. 0 is returned if equal
$stripprefix(str)
Removes A and The prefixes from string str.
$stripprefix(str,prefix1,prefix2,...)
Removes the specified prefixes from string str.
$substr(str,from,to)
Returns substring of string str, starting from FROM-th character and ending at TO-th character.
$tab()
Inserts one tabulator character.
$tab(count)
Inserts count tabulator characters.
$upper(str)
Converts string str to uppercase.
Boolean functions:
$and(expr, ...)
Logical And of an arbitrary number of arguments. Returns true, if and only if all expr arguments evaluate to true.
$or(expr, ...)
Logical Or of an arbitrary number of arguments. Returns true, if at least one expression evaluates to true.
$not(expr)
Logical Not. Returns the logical opposite of EXPR: false, if expr is true and true if expr is false.
$xor(expr,...)
Logical Exclusive-or of an arbitrary number of arguments. Returns true, if an odd number of arguments evaluate to true.
Special case: $xor(expr1,expr2) returns true, if EXPR1 or EXPR2 is true. If both expressions are true, returns false.
Arithmetic Functions:
$add(a,b, ...)
Adds a and b.
Can be used with an arbitrary number of arguments. $add(a,b,...) is the same as $add($add(a,b),...).
$div(a,b)
Divides a by b and rounds down to an integer. If b evaluates to zero, it returns a.
Can be used with an arbitrary number of arguments. $div(a,b,...) is the same as $div($div(a,b),...).
$greater(a,b)
Returns true, if a is greater than b, otherwise false.
$max(a,b)
Returns the maximum of a and b.
Can be used with an arbitrary number of arguments. $max(a,b,...) is the same as $max($max(a,b),...).
$min(a,b)
Returns the minimum of a and b.
Can be used with an arbitrary number of arguments. $min(a,b,...) is the same as $min($min(a,b),...).
$mod(a,b)
Computes the remainder of dividing a through b. The result has the same sign as a. If b evaluates to zero, the result is a.
Can be used with an arbitrary number of arguments. $mod(a,b,...) is the same as $mod($mod(a,b),...).
$mul(a,b)
Multiplies a and b.
Can be used with an arbitrary number of arguments. $mul(a,b,...) is the same as $mul($mul(a,b),...).
$muldiv(a,b,c)
Multiplies a and b, then divides by c. The result is rounded to the nearest integer.
$sub(a,b)
Subtracts b from a.
Can be used with an arbitrary number of arguments. $sub(a,b,...) is the same as $sub($sub(a,b),...).
Special Functions:
$comment(val)
Ignores anything inside parens. Its for commenting the json file
$rating(val, min)
Converts val to rating stars. Range 0-10. 1 = half star 2 = 1 star 3 = 1.5 stars, etc. It will use the previously set color and size. Any rating below "min" will hide the stars
Example: $rating(%ra%) or $rating(%ra%, 0.5) First example shows all ratings including 0 star. Second example will only shows starts for rating > 0
$date(val, format)
Turns the value into a date/time string using the provided format. val needs to be a number (typically used with variables like Last Played). More info on the formats is provided here: https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html"]https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html
Example: $date(%lp%, YYYY-MM-dd) will show 2020-11-21
Literals:
%comma% - not a function but a way to use literal commas in functions
%startparen% - literal starting parenthesis (
%endparen% - literal ending parenthesis )
%space% - literal empty space
%period% - literal period .
Edit: I have not tested every possible combinations so if there are issues let me know.