Winamp ATF Reference

Below is an extract of the Winamp supported ATF functionality.
ATF determines how Winamp should display metadata in the Playlist window and Main window songticker. The global ATF string can be manually edited via the 'Titles' page in the Winamp Preferences.


The default ATF string in Winamp is:
[%artist% - ]$if2(%title%,$filepart(%filename%)


This will be displayed as: 'Artist - Title' if the Artist and Title metadata fields are populated in the file tags, otherwise it will just display the filename instead.

%blah% denotes a metadata field.

$blah() denotes a function call.

[] means "don't display unless metadata was found".

‘ ’ (single quotation marks) 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.

Returns the containing folder.
Winamp 5.2+ Only.

Returns the track rating as an integer from 1 to 5, if set. To display as stars or another character, use the $repeat function.

Winamp 5.2+ Only.

Returns the playcount (number of times track has been played), if the file is stored in the Media Library database.

Winamp 5.2+ 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).

Most of these are straightforward and are taken from the standard file tags, and therefore don't require any additional explanatory notes.

Returns the Artist field.

Returns the Title field.

Returns the Album field.

Returns the Year field.

Returns the Genre field.

Returns the Comment field.

Returns the TrackNumber with no padding, eg. Track 1 will be displayed as 1.
To pad with zeros, eg. 01, 02...10, 11, use the $num or $lpad function.

Same as %tracknumber%

Returns the Album Artist field.
Winamp 5.3+ Only.

Returns the Disc No. tag, if available, eg. 1/2 (Disc #1 of a 2CD set).

Returns the Composer field.

Returns the Publisher (Record Label) field.
Winamp 5.3+ Only.

Returns the Streaming Title for streams, if one exists.

Returns the Bitrate (will use average bitrate for vbr).

Returns length of the track in miliseconds. For a formatted track length, use
$div(%length%,60000):$num($div($mod(%length%,60000),1000),2)

Returns 1 for video, 0 for audio.
Winamp 5.2+ Only.

Returns 1 for VBR(Variable Bitrate) audio, 0 for CBR(Constant Bitrate) audio.

Returns the Category field.
Winamp 5.55+ Only.

The fields listed below may not work for all file formats.

Returns the Track Artist field (equivalent to Artist), if different to Album Artist.
Winamp 5.3+ Only.

Returns the Mood field.
Winamp 5.3+ Only.

Returns the BPM (Beats Per Minute), if data/field exists.
Winamp 5.3+ Only.

Returns the Key field (eg. E Minor), if it exists.
Winamp 5.3+ Only.

Returns the Lyricist field.
Winamp 5.3+ Only.

Returns the Conductor field.
Winamp 5.3+ Only.

Returns the Encoded/Tool (software used to rip/encode track) field, eg. Winamp 5.34.
Winamp 5.3+ Only.

Returns the filetype's Family, eg. M4A returns: MPEG-4 Audio File Format
Winamp 5.5+ Only.

Returns the Encoder, eg. LAME 3.97
Winamp 5.3+ Only.

International Standard Recording Code, or ISO 3901 (Info)
Winamp 5.3+ Only.

Returns the ReplayGain Track Gain value (eg. -3.16 dB), if it exists.
Winamp 5.3+ Only.

Returns the ReplayGain Album Gain value, if it exists.
Winamp 5.3+ Only.

Returns the ReplayGain Track Peak value, if it exists.
Winamp 5.3+ Only.

Returns the ReplayGain Album Peak value, if it exists.
Winamp 5.3+ Only.

Returns the Gain value, if it exists.
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%,2007,New!:,Old:)
Example: $IfStrEqual2(%type%,1,'(Video)','(Audio)')

Winamp 5.2+ Only.

Parameters: (A, B, then)
Returns: If A = B do then else nothing
Example: $IfStrEqual(%year%,2007,New!:) will print “New!” if the media was published in 2007.

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.
Examples: $abbr(%album%) converts Album name of eg. “Final Fantasy VI” to “FFVI”.
$abbr(Advanced Title Formatting,10) writes “ATF”.
$abbr(%album%,10) writes abbreviated Album name, only if longer than 10 char's.
x1 is optional. If defined, a1 will only be abbreviated when its length exceeds x1 char's.

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(%comment%,15) writes the first 15 characters of the Comment field.

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: (a, token, which)
Returns: Splitting of disc and/or track strings, eg. to show "1" instead of "1/11"
Example: [$num(%track%,2)$IfStrNotEqual($split(%track%,/,1),,/$num($split(%track%,/,1),2))]

Winamp 5.5+ 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: The last x1 levels of a1
Example: $PathRPart(%filename%,2)
The above example will output “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 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

[ .... ] - displays contents of brackets only if at least one of the fields referenced inside has been found, eg. [%artist% - ] will show:  "Artist - "  only if the %artist% tag is populated, otherwise it will not show anything at all (including the hyphen and spaces).

Syntax: [%artist% - ][%album% - ][$num(%track%,2) - ]$if2(%title%,$filepart(%filename%))
Example: Pink Floyd - Animals - 02 - Dogs

Syntax: [$if2(%albumartist%,%artist%) - ][%album% - ][$num(%track%,2) - ]
$IfStrNotEqual(%artist%,$if2(%albumartist%,%artist%),[%artist% - ])
[$if2(%title%,$filepart(%filename%))][$if($fileext(%filename%),'   [  ',)]
[%year%  |  ][$fileext(%filename%) ][$if(%bitrate%, '|'  ,)][%bitrate% 'kbps' ]
[$if($fileext(%filename%),']',)][   $repeat(*,%rating%) ]
Returns: AlbumArtist - Album - ## - Artist - Title  [ Year | Ext | Bitrate ]  StarRating
if AlbumArtist is different to TrackArtist, otherwise shows Standard format.
Example: Various - Arcana - 01 - Tripswitch - Calabi Yau   [ 2006  |  mp3  |  205 kbps ]  *****