WINAMP HELP

Winamp for Windows Documentation

Winamp is the best, freeware media player that allows you to play most audio formats (including Internet Radio Stations) and video. Winamp works with portable media players, allows you to rip and burn CDs, has a built-in media library, graphic equalizer and visualizations. With the advanced plug-in mechanism, you have the possibility to increase its functionality. Thanks to skins Winamp can look and behave as you like...

Advanced Title Formatting

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.

1. ATF Usage
2. Fields
3. Functions
4. Examples
- 4.1 Standard ATF syntax
- 4.2 Advanced ATF syntax

1. ATF Usage

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 ($,%,[,])

⇡ Back To Top

2. Fields

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).

2.1 Provided by Winamp

%filename%

Returns the full path of the file. To display the filename only, use the $filepart function..

%folder%

Returns the containing folder. [Winamp 5.2+ Only]

2.2 Provided by ML

%rating%

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]

%playcount%

Returns the playcount (number of times track has been played), if the file is stored in the Media Library database. [Winamp 5.2+ Only]

2.3 Provided by ML or input plugin

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.

%artist%

Returns the Artist field.

%title%

Returns the Title field.

%album%

Returns the Album field.

%year%

Returns the Year field.

%genre%

Returns the Genre field.

%comment%

Returns the Comment field.

%tracknumber%

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.

%track%

Same as %tracknumber%

%albumartist%

Returns the Album Artist field. [Winamp 5.3+ Only]

%disc%

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

%composer%

Returns the Composer field.

%publisher%

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

%streamtitle%

Returns the Streaming Title for streams, if one exists.

%bitrate%

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

%length%

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

%type%

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

%vbr%

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

%category%

Returns the Category field. [Winamp 5.55+ Only]

%producer%

Returns the (record or film) Producer field. [Winamp 5.57+ Only.]

%director%

Returns the (film) Director field, mainly used for videos. [Winamp 5.57+ Only.]

2.4 Provided by input plugin

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

%trackartist%

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

%mood%

Returns the Mood field. [Winamp 5.3+ Only]

%bpm%

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

%key%

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

%lyricist%

Returns the Lyricist field. [Winamp 5.3+ Only]

%conductor%

Returns the Conductor field. [Winamp 5.3+ Only]

%tool%

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

%family%

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

%encoder%

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

%ISRC%

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

%replaygain_track_gain%

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

%replaygain_album_gain%

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

%replaygain_track_peak%

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

%replaygain_album_peak%

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

%gain%

Returns the Gain value, if it exists. [Winamp 5.3+ Only]

⇡ Back To Top

3. Functions

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).

3.1 Control Flow

[...]

Conditional section

$if

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)

$if2

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)

$if3

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)

$decode

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

$ifgreater

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

$iflonger

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

$IfStrEqual2

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

$IfStrEqual

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

3.2 Logic Operations

$and

– Removed –

Parameters: (%a%, %b%)
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

3.3 Arithmetic Operations

$mod

Parameters: (x1, x2)
Returns:
remainder of a division of x1 by x2
Example: $mod(21,8) returns “5”.

Winamp 5.2+ Only

$div

Parameters: (x1, x2)
Returns:
x1 / x2. Result of a division of x1 by x2
Example: $div(60,10)

Winamp 5.2+ Only

$mul

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

$muldiv

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

$sub

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

$add

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

$greater

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

$max

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

$min

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

3.4 String Operations

$lower

Parameters: (a1)
Returns:
lower case of a1
Example: $lower(%title%)

$upper

Parameters: (a1)
Returns:
upper case of a1
Example: $upper(%title%)

$replace

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

$left

Parameters: (a1, x1)
Returns:
the first x1 characters of a1
Example: $left(%title%)

Winamp 5.2+ Only

$right

Parameters: (a1, x1)
Returns:
the last x1 characters of a1
Example: $right(%title%)

Winamp 5.2+ Only

$len

Parameters: (a1)
Returns:
the number of characters of a1
Example: $len(%artist%)

Winamp 5.2+ Only

$substr

Parameters: (a1, a2)
Returns:
TODO: a1
Example: $substr()

Winamp 5.2+ Only

$strstr

Parameters: (a1, a2)
Returns:
index of first occurence of string a2 in a1
Example: $strstr(aacbbabb,ab) returns “6”.

Winamp 5.2+ Only

$strrchr

Parameters: (a1, a2)
Returns:
index of last occurence of character a2 in a1
Example: $strrchr(aacbbabb,a) returns “6”.

Winamp 5.2+ Only

$strlchr

Parameters: (a1, a2)
Returns:
index of first occurence of character a2 in a1
Example: $strlchr(aacbbabb,a) returns “1”.

Winamp 5.2+ Only

$strchr

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

$shortest

Parameters: (a1, a2)
Returns:
a1 or a2 based on which has the shorter length.
Example: $shortest(%album%,%folder%)

$longest

Parameters: (a1, a2)
Returns:
a1 or a2 based on which has the greater length.
Example: $longest(%album%,%folder%)

$abbr

Parameters: (a1, x1)
Returns:
a1 abbreviated.
Example: $abbr(%album%) converts Album name of eg. “Final Fantasy VI” to “FFVI”.
Example: $abbr(Advanced Title Formatting,10) writes “ATF”.
Example: $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.

$padcut

Parameters: (a1, x2)
Returns:
a1 padded with spaces or cut off, resulting in a string of x2 characters
Example: $padcut(%artist%,15)

$cut

Parameters: (a1, x2)
Returns:
a1, cut off after the x2th character
Example: $cut(%comment%,15) writes the first 15 characters of the Comment field.

$pad

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.

$lpad

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

$trim

Parameters: (a1)
Returns:
a1 without any leading or trailing spaces
Example: $trim(%artist%)

Winamp 5.2+ Only

$repeat

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.)

$caps

Parameters: (a1)
Returns:
lower case of a1, with first letter of each word in upper case
Example: $caps(%artist%)

$caps2

Parameters: (a1)
Returns:
a1, with first letter of each word in upper case
Example: $caps2(%artist%)

$fileext

Parameters: (a1)
Returns:
file extension of a1
Example: $fileext(%filename%)

$filepart

Parameters: (a1)
Returns:
filename of a1 (i.e. without the leading path)
Example: $filepart(%filename%)

$filename

Parameters: (a1)
Returns:
filename of a1 (i.e. without the leading path)
Example: $filename(%filename%)

$directory

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

$split

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

$ext

Parameters: (a1)
Returns:
file extension of a1
Example: $ext(%filename%)

Winamp 5.2+ Only

$hex

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

$dec

Parameters: (x1, x2)
Returns:
x1 zero padded to the left to form a x2 digit number.
Example: $dec(%tracknumber%,5)

Winamp 5.2+ Only

$num

Parameters: (x1, x2)
Returns:
x1 zero padded to the left to form a x2 digit number.
Example: $num(%tracknumber%,5)

Winamp 5.2+ Only

$null

Parameters: Any number of parameters
Returns:
Nothing
Example: Does absolutely nothing. It is useful mainly in places where a parameter is required, but you want an empty string.

Winamp 5.2+ Only

$PathLPart

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

$PathRPart

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

$PathLTrim

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

$PathRTrim

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

3.5 Variables

$puts

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

$put

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

$get

Parameters: (name)
Returns:
value of name variable previously set by a $put() or $puts() function
Example: $get(artist_title)

Winamp 5.2+ Only

3.6 System Info

$systime_second

Parameters: TODO: (a1, a2)
Returns:
TODO: a1
Example: TODO: $systime_second()

Winamp 5.2+ Only

$systime_minute

Parameters: TODO: (a1, a2)
Returns:
TODO: a1
Example: TODO: $systime_minute()

Winamp 5.2+ Only

$systime_hour

Parameters: TODO: (a1, a2)
Returns:
TODO: a1
Example: TODO: $systime_hour()

Winamp 5.2+ Only

$systime_day

Parameters: TODO: (a1, a2)
Returns:
TODO: a1
Example: TODO: $systime_day()

Winamp 5.2+ Only

$systime_month

Parameters: TODO: (a1, a2)
Returns:
TODO: a1
Example: TODO: $systime_month()

Winamp 5.2+ Only

$systime_year

Parameters: TODO: (a1, a2)
Returns:
TODO: a1
Example: TODO: $systime_year()

Winamp 5.2+ Only

3.7 Others

$select

$tab

$crlf

$char

⇡ Back To Top

4. Examples

[ .... ] - displays contents of brackets only if at least one of the fields referenced inside has been found.

Example: [%artist%-] will show: "artist-" only if the %artist% tag is populated, otherwise it will not show anything at all (including the hyphen and spaces).

4.1 Standard ATF syntax

Syntax: [%artist% - ][%album% - ][$num(%track%,2) - ]$if2(%title%,$filepart(%filename%))

Example: Pink Floyd - Animals - 02 - Dogs

4.2 Advanced ATF syntax

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 kb/s ] *****

This site is not officially associated with Winamp in any way. All copyrights, trademarks, logos and names of the entities mentioned on this site are the property of their respective owners.

This site uses cookies to provide services at the highest level. By continuing to use the site, you agree to their use.

HTML 5 | CSS 3.0 | Privacy Policy | DONATE

Last updated: Tuesday, 9 January 2024 (12:36:24)