Music Plugins
Some of this documentation is similar to the Foobar2000 Title Formatting Reference as it uses a similar ATF system. Below is an extract of the Winamp supported ATF functionality.
See also: Extensions by Toaster before Winamp 9.0
’ (single quotation mark) outputs raw text without parsing. eg. ‘blah$blah%blah[]]]’ which will output all the string and ignore the special characters ($,%,[,]).
Note: Fields are defined by various components within Winamp. Some are specific to the Media Library (%rating%, %playcount%), some are provided by Winamp (%filename%, %folder%). In most cases, however, the input plugin provides the fields. Some input plugins provide a greater variety of fields than others. For example, the Windows Media plugin (in_wm, Winamp 5.12+), will provide values for ANY field in the form %WM/*% (see the extended attributes section of View File Info on any wma/wmv/asf file for examples).
Returns the full path of the file. To display the filename only, use the $filepart function.
Winamp 5.2+ Only.
Winamp 5.2+ or ATFE Only.
Winamp 5.2+ or ATFE Only.
For the fields listed below, info is taken from ML only if the file is present in the ML database and if the following option is checkmarked: Prefs (Ctrl+P) > Media Library > Local Media > ‘Use Library title information for Playlist Item Formatting’
In all other cases, the info is provided by the input plugin (if the respective input plugin supports the field).
Returns 1 for video, 0 for audio. Winamp 5.2+ Only.
Returns 1 for VBR(Variable Bitrate) audio, 0 for CBR(Constant Bitrate) audio.
The fields listed below may not work for all file formats.
Returns length of the track in miliseconds. For a formatted track length, use
$div(%length%,60000):$num($div($mod(%length%,60000),1000),2)
Returns title of the current stream
Returns name of the current stream
Returns the album artist. Winamp 5.3+ Only.
Winamp 5.3+ Only.
Winamp 5.3+ Only.
Winamp 5.3+ Only.
Winamp 5.3+ Only.
Winamp 5.3+ Only.
Winamp 5.3+ Only.
Winamp 5.3+ Only.
Winamp 5.3+ Only.
Info. Winamp 5.3+ Only.
Winamp 5.3+ Only.
Winamp 5.3+ Only.
Winamp 5.3+ Only.
Winamp 5.3+ Only.
Winamp 5.3+ Only.
Notes: Be careful about spaces after commas. $if(%title%, Has A Title, Has No Title) will display
” Has A Title” (note leading space)
not “Has A Title”.
The proper form should be $if(%title%,Has A Title,Has No Title).
Parameters: (a, then, else)
Returns: If a contains at least one valid, non-empty field, then is evaluated and returned, otherwise the else parameter is. Note that $if(A,A,B) is equivalent to $if2(A,B)
Example: $if(%artist%,Has an artist tag,Has no artist tag)
Parameters: (a, else)
Returns: If a contains a valid, non-empty field, a is evaluated and returned, otherwise the else parameter is.
Example: $if2(%album%,no-album)
Parameters: (a1, ..., aN, else)
Returns: If one of a1... aN contains a valid, non-empty field, the value is evaluated and returned, otherwise the else parameter is used.
Example: $if3(%artist%,%filename%,%album%,no field)
Parameters: (a, b1, c1, ..., bN, cN, else)
Returns: cN or else. A switch/case function, which determines which bN parameter is equal to a and returns the corresponding cN parameter. If none are matched, it returns the final parameter else.
Example: $decode($fileext(%filename%),MP3,MPEG-1 Layer 3,MP4,MPEG-4 Container,Other)
Winamp 5.2+ Only.
Parameters: (x1, x2, then, else)
Returns: Compares the integer numbers x1 and x2, if x1 is greater than x2, then is evaluated and its value returned. Otherwise the else part is evaluated and its value returned.
Example: $ifgreater(%rating%,2,Highly rated song,Not highly rated song)
Winamp 5.2+ Only.
Parameters: (a1, x1, then, else)
Returns: Compares whether the length of string a1 is longer than x1 characters, if a1 is longer, the then part is evaluated and its value returned. Otherwise the else part is evaluated and its value returned.
Example: $iflonger(%title%,15,A long title,A short title)
Winamp 5.2+ Only.
Parameters: (A, B, then, else)
Returns: If A = B do then else do else
Example: $IfStrEqual2(%year%,2006,New!:,Old:)
Winamp 5.2+ Only.
Parameters: (A, B, then)
Returns: If A = B do then else nothing
Example: $IfStrEqual(%year%,2006,New!:) will print “New!” if the media was published in 2006.
Winamp 5.2+ Only.
– Removed –
Parameters: (%a%, %b%) - The fields to check if populated.
Returns: 1 if the fields %a% and %b% are populated. An empty string if not. (?????)
Example: $if($and(%artist%,%title%),Has both artist and title,One field is missing)
Winamp 5.2+ Only.
Parameters: (x1, x2)
Returns: remainder of a division of x1 by x2
Example: $mod(21,8) returns “5”.
Winamp 5.2+ Only.
Parameters: (x1, x2)
Returns: x1 / x2. Result of a division of x1 by x2
Example: $div(60,10)
Winamp 5.2+ Only.
Parameters: (x1,x2,...,xn) - List of numbers to multiply
Returns: x1 * x2 * ... * xn. The supplied numbers multiplied
Example: $mul(7,8,3,4)
Winamp 5.2+ Only.
Parameters: (x1, x2, x3)
Returns: x1 * x2 / 3. x1 multiplied by x2, divided by x3. Result is rounded to nearest integer.
Example: $muldiv(10,6,3) returns “20”.
Winamp 5.2+ Only.
Parameters: (x1,x2,...,xn) - List of numbers to subtract
Returns: x1 - x2 - ... - xn. The result of x2...xn subtracted from x1.
Example: $sub(25,1,3,2,3)
Winamp 5.2+ Only.
Parameters: (x1,x2,...,xn) - List of numbers to add
Returns: x1 + x2 +...+ xn. The addition of all the numbers supplied
Example: $add(2,3,%playcount%,%rating%)
Winamp 5.2+ Only.
Parameters: (x1, x2) - Two numbers to compare
Returns: 1 if x1 is greater than x2, otherwise nothing. Similar in use to $ifgreater()
Example: $greater(3,2) – note does not appear to work within a $if() function.
Winamp 5.2+ Only.
Parameters: (x1,...,xn) - List of numbers to compare
Returns: The largest number in the arguments supplied
Example: $max(7,8,3,4)
Winamp 5.2+ Only.
Parameters: (x1,...,xn) - List of numbers to compare
Returns: The smallest number in the arguments supplied
Example: $min(7,8,3,4)
Winamp 5.2+ Only.
Parameters: (a1)
Returns: lower case of a1
Example: $lower(%title%)
Parameters: (a1)
Returns: upper case of a1
Example: $upper(%title%)
Parameters: (a1, a2, a3)
Returns: a1 with all occurences of a2 replaced by a3
Example: $replace(dum,u,o) writes “dom”.
Winamp 5.2+ Only.
Parameters: (a1, x1)
Returns: the first x1 characters of a1
Example: $left(%title%)
Winamp 5.2+ Only.
Parameters: (a1, x1)
Returns: the last x1 characters of a1
Example: $right(%title%)
Winamp 5.2+ Only.
Parameters: (a1)
Returns: the number of characters of a1
Example: $len(%artist%)
Winamp 5.2+ Only.
Parameters: TODO: (a1, a2)
Returns: TODO: a1
Example: TODO: $substr()
Winamp 5.2+ Only.
Parameters: (a1, a2)
Returns: index of first occurence of string a2 in a1
Example: $strstr(aacbbabb,ab) returns “6”.
Winamp 5.2+ Only.
Parameters: (a1, a2)
Returns: index of last occurence of character a2 in a1
Example: $strrchr(aacbbabb,a) returns “6”.
Winamp 5.2+ Only.
Parameters: (a1, a2)
Returns: index of first occurence of character a2 in a1
Example: $strlchr(aacbbabb,a) returns “1”.
Winamp 5.2+ Only.
Parameters: (a1, a2)
Returns: index of first occurence of character a2 in a1
Example: $strchr(aacbbabb,a) returns “1” (same as $strlchr() ??).
Winamp 5.2+ Only.
Parameters: (a1, a2)
Returns: a1 or a2 based on which has the shorter length.
Example: $shortest(%album%,%folder%)
Parameters: (a1, a2)
Returns: a1 or a2 based on which has the greater length.
Example: $longest(%album%,%folder%)
Parameters: (a1, x1)
Returns: a1 abbreviated.
Example: $abbr(Advanced Title Formatting,10) writes “ATF”.
x1 is optional. If defined, a1 will only be abbreviated when its length exceeds x1 characters.
Parameters: (a1, x2)
Returns: a1 padded with spaces or cut off, resulting in a string of x2 characters
Example: $padcut(%artist%,15)
Parameters: (a1, x2)
Returns: a1, cut off after the x2th character
Example: $cut(%artist%,15)
Parameters: (string, num, padstr)
Returns: string padded to at least num chars, with spaces by default, or specify a character (or repeating string) as padstr.
Example: $pad(%artist%,40), or $pad(%artist%,40,.) to pad with periods.
Parameters: (string, num, padstr)
Returns: string padded to at least num chars on the left, with spaces by default, or specify a character (or repeating string) as padstr.
Example: $lpad(%tracknumber%,3), or $lpad(%tracknumber%,3,0) to pad zeros in front.
Winamp 5.2+ Only.
Parameters: (a1)
Returns: a1 without any leading or trailing spaces
Example: $trim(%artist%)
Winamp 5.2+ Only.
Parameters: (a1, x1)
Returns: a1 repeated x1 times.
Example: $repeat(*,%rating%)
($fill() performed this function in Winamp 5.2 and was removed after 5.21.)
Parameters: (a1)
Returns: lower case of a1, with first letter of each word in upper case
Example: $caps(%artist%)
Parameters: (a1)
Returns: a1, with first letter of each word in upper case
Example: $caps2(%artist%)
Parameters: (a1)
Returns: file extension of a1
Example: $fileext(%filename%)
Parameters: (a1)
Returns: filename of a1 (i.e. without the leading path)
Example: $filepart(%filename%)
Parameters: (a1)
Returns: filename of a1 (i.e. without the leading path)
Example: $filename(%filename%)
Parameters: (a1, x1)
Returns: directory name of a1, after going up by x1 levels
Example: $directory(%filename%,2)
The above example will output “Music” if the full path of the file is “C:\Music\Artist - Album\Song.mp3”. x1 is optional, default is 1.
Winamp 5.2+ Only.
Parameters: (a1)
Returns: file extension of a1
Example: $ext(%filename%)
Winamp 5.2+ Only.
Parameters: (x1, x2)
Returns: x1 formatted as hexidecimal to x2 number of digits, padded to the left with zeros.
Example: $hex(%tracknumber%,4)
Winamp 5.2+ Only.
Parameters: (x1, x2)
Returns: x1 zero padded to the left to form a x2 digit number.
Example: $dec(%tracknumber%,5)
Winamp 5.2+ Only.
Parameters: (x1, x2)
Returns: x1 zero padded to the left to form a x2 digit number.
Example: $num(%tracknumber%,5)
Winamp 5.2+ Only.
Parameters: Any number of parameters
Returns: Nothing
Example: $null()
Does absolutely nothing. It is useful mainly in places where a parameter is required, but you want an empty string.
Winamp 5.2+ Only.
Parameters: (a1, x1)
Returns: The first x1 levels of a1
Example: $PathLPart(%filename%,2)
The above example will output “C:\Music” if the full path of the file is “C:\Music\Sonic Youth - Daydream Nation\01 - Teen Age Riot.mp3”.
Winamp 5.3+ Only.
Parameters: (a1, x1)
Returns: a1 minus the first x1 levels of a1
Example: $PathLTrim(%filename%,1)
The above example will output “Music\Sonic Youth - Daydream Nation\01 - Teen Age Riot.mp3” if the full path of the file is “C:\Music\Sonic Youth - Daydream Nation\01 - Teen Age Riot.mp3”.
Winamp 5.3+ Only.
Parameters: (a1, x1)
Returns: a1 minus the last x1 levels of a1
Example: $PathRTrim(%filename%,1)
The above example will output “C:\Music\Sonic Youth - Daydream Nation” if the full path of the file is “C:\Music\Sonic Youth - Daydream Nation\01 - Teen Age Riot.mp3”.
Winamp 5.3+ Only.
Parameters: (name, value)
Returns: Stores value to the named variable name. It may be later retrieved using $get(name). Use $put() to store a value and also return the value with the one function.
Example: $puts(artist_title,%artist% - %title%)
Winamp 5.2+ Only.
Parameters: (name, value)
Returns: value. Stores value to the named variable name. It may be later retrieved using $get(name). Use $puts() to store a value without returning it.
Example: $put(artist_title,%artist% - %title%)
Winamp 5.2+ Only.
Parameters: (name)
Returns: value of name variable previously set by a $put() or $puts() function
Example: $get(artist_title)
Winamp 5.2+ Only.
Parameters: TODO: (a1, a2)
Returns: TODO: a1
Example: TODO: $systime_second()
Winamp 5.2+ Only.
Parameters: TODO: (a1, a2)
Returns: TODO: a1
Example: TODO: $systime_minute()
Winamp 5.2+ Only.
Parameters: TODO: (a1, a2)
Returns: TODO: a1
Example: TODO: $systime_hour()
Winamp 5.2+ Only.
Parameters: TODO: (a1, a2)
Returns: TODO: a1
Example: TODO: $systime_day()
Winamp 5.2+ Only.
Parameters: TODO: (a1, a2)
Returns: TODO: a1
Example: TODO: $systime_month()
Winamp 5.2+ Only.
Parameters: TODO: (a1, a2)
Returns: TODO: a1
Example: TODO: $systime_year()
Winamp 5.2+ Only.
select tab crlf char